Skip to main content

qualia_client_core/wellfair/
sync_outbox.rs

1//! Durable sync outbox: queued record commits awaiting upstream acknowledgement.
2
3use std::fs::{self, OpenOptions};
4use std::io::{BufRead, BufReader, Write};
5use std::path::{Path, PathBuf};
6
7use serde::{Deserialize, Serialize};
8use wellfare_core::conditions::journal_kind_for_record_id;
9use wellfare_core::record::RecordEnvelope;
10
11pub const SYNC_OUTBOX_FILE: &str = "wellfair/sync_outbox.jsonl";
12pub const MAX_LIST: usize = 256;
13
14#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
15#[serde(rename_all = "PascalCase")]
16pub enum SyncOutboxState {
17    Queued,
18    Sent,
19    Acknowledged,
20    Rejected,
21}
22
23#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
24pub struct SyncOutboxEntry {
25    pub operation_id: String,
26    pub record_id: String,
27    pub kind: String,
28    pub committed_unix: u32,
29    pub state: SyncOutboxState,
30}
31
32impl SyncOutboxEntry {
33    /// Constructs from envelope.
34    pub fn from_envelope(envelope: &RecordEnvelope, committed_unix: u32) -> Self {
35        Self {
36            operation_id: uuid::Uuid::new_v4().to_string(),
37            record_id: envelope.id.clone(),
38            kind: journal_kind_for_record_id(&envelope.id).to_string(),
39            committed_unix,
40            state: SyncOutboxState::Queued,
41        }
42    }
43}
44
45pub struct SyncOutbox {
46    path: PathBuf,
47}
48
49impl SyncOutbox {
50    /// Opens.
51    pub fn open(storage_root: impl AsRef<Path>) -> std::io::Result<Self> {
52        let path = storage_root.as_ref().join(SYNC_OUTBOX_FILE);
53        if let Some(parent) = path.parent() {
54            fs::create_dir_all(parent)?;
55        }
56        if !path.exists() {
57            OpenOptions::new().create(true).write(true).open(&path)?;
58        }
59        Ok(Self { path })
60    }
61
62    /// Enqueues a job.
63    pub fn enqueue(&self, entry: &SyncOutboxEntry) -> std::io::Result<()> {
64        let line =
65            serde_json::to_string(entry).map_err(|e| std::io::Error::other(e.to_string()))?;
66        let mut file = OpenOptions::new().append(true).open(&self.path)?;
67        writeln!(file, "{line}")?;
68        file.sync_all()?;
69        Ok(())
70    }
71
72    /// Lists all entries.
73    pub fn list_all(&self) -> std::io::Result<Vec<SyncOutboxEntry>> {
74        let file = fs::File::open(&self.path)?;
75        let reader = BufReader::new(file);
76        let mut entries = Vec::new();
77        for line in reader.lines() {
78            let line = line?;
79            if line.trim().is_empty() {
80                continue;
81            }
82            if let Ok(entry) = serde_json::from_str::<SyncOutboxEntry>(&line) {
83                entries.push(entry);
84            }
85        }
86        Ok(entries)
87    }
88
89    /// Lists recent entries.
90    pub fn list_recent(&self, limit: usize) -> std::io::Result<Vec<SyncOutboxEntry>> {
91        let mut entries = self.list_all()?;
92        let keep = limit.min(MAX_LIST);
93        if entries.len() > keep {
94            entries.drain(0..entries.len() - keep);
95        }
96        entries.reverse();
97        Ok(entries)
98    }
99
100    /// Queued count.
101    pub fn count_queued(&self) -> std::io::Result<usize> {
102        Ok(self
103            .list_all()?
104            .into_iter()
105            .filter(|e| e.state == SyncOutboxState::Queued)
106            .count())
107    }
108
109    /// Updates state.
110    pub fn update_state(
111        &self,
112        operation_id: &str,
113        state: SyncOutboxState,
114    ) -> std::io::Result<bool> {
115        let all = self.list_all()?;
116        let mut found = false;
117        let mut rewritten = Vec::with_capacity(all.len());
118        for mut entry in all {
119            if entry.operation_id == operation_id {
120                entry.state = state;
121                found = true;
122            }
123            rewritten.push(entry);
124        }
125        if !found {
126            return Ok(false);
127        }
128        let tmp = self.path.with_extension("jsonl.tmp");
129        {
130            let mut file = OpenOptions::new()
131                .create(true)
132                .write(true)
133                .truncate(true)
134                .open(&tmp)?;
135            for entry in &rewritten {
136                let line = serde_json::to_string(entry)
137                    .map_err(|e| std::io::Error::other(e.to_string()))?;
138                writeln!(file, "{line}")?;
139            }
140            file.sync_all()?;
141        }
142        fs::rename(&tmp, &self.path)?;
143        Ok(true)
144    }
145}
146
147#[cfg(test)]
148mod tests {
149    use super::*;
150    use wellfare_core::record::{EpistemicStatus, EvidenceType, RecordEnvelope, SensitivityClass};
151
152    fn sample_envelope(id: &str) -> RecordEnvelope {
153        RecordEnvelope {
154            id: id.into(),
155            owner_did: "did:wf:owner".into(),
156            author_did: "did:wf:owner".into(),
157            proxy_did: None,
158            epistemic_status: EpistemicStatus::Asserted,
159            evidence_type: EvidenceType::DeviceMeasured,
160            sensitivity: SensitivityClass::Restricted,
161            asserted_time_unix: 1_700_000_000,
162            asserted_instant: None,
163            valid_time_start_unix: None,
164            valid_time_start_instant: None,
165            valid_time_end_unix: None,
166            valid_time_end_instant: None,
167            predecessor_id: None,
168            blob_hash: Some("deadbeef".into()),
169            tombstone: false,
170        }
171    }
172
173    #[test]
174    fn sync_outbox_enqueue_and_list() {
175        let dir = tempfile::tempdir().unwrap();
176        let outbox = SyncOutbox::open(dir.path()).unwrap();
177        let envelope = sample_envelope("urn:wellfair:weight:abc");
178        let entry = SyncOutboxEntry::from_envelope(&envelope, 1_700_000_100);
179        outbox.enqueue(&entry).unwrap();
180
181        let listed = outbox.list_recent(10).unwrap();
182        assert_eq!(listed.len(), 1);
183        assert_eq!(listed[0].record_id, "urn:wellfair:weight:abc");
184        assert_eq!(listed[0].kind, "weight");
185        assert_eq!(listed[0].committed_unix, 1_700_000_100);
186        assert_eq!(listed[0].state, SyncOutboxState::Queued);
187        assert!(!listed[0].operation_id.is_empty());
188    }
189
190    #[test]
191    fn sync_outbox_survives_reopen() {
192        let dir = tempfile::tempdir().unwrap();
193        let outbox = SyncOutbox::open(dir.path()).unwrap();
194        let envelope = sample_envelope("urn:wellfair:sleep:xyz");
195        let entry = SyncOutboxEntry::from_envelope(&envelope, 42);
196        outbox.enqueue(&entry).unwrap();
197
198        let reopened = SyncOutbox::open(dir.path()).unwrap();
199        let listed = reopened.list_recent(5).unwrap();
200        assert_eq!(listed.len(), 1);
201        assert_eq!(listed[0].kind, "sleep");
202        assert_eq!(reopened.count_queued().unwrap(), 1);
203    }
204
205    #[test]
206    fn sync_outbox_state_transition() {
207        let dir = tempfile::tempdir().unwrap();
208        let outbox = SyncOutbox::open(dir.path()).unwrap();
209        let envelope = sample_envelope("urn:wellfair:steps:1");
210        let entry = SyncOutboxEntry::from_envelope(&envelope, 99);
211        outbox.enqueue(&entry).unwrap();
212
213        assert!(outbox
214            .update_state(&entry.operation_id, SyncOutboxState::Sent)
215            .unwrap());
216        let listed = outbox.list_recent(1).unwrap();
217        assert_eq!(listed[0].state, SyncOutboxState::Sent);
218        assert_eq!(outbox.count_queued().unwrap(), 0);
219
220        assert!(outbox
221            .update_state(&entry.operation_id, SyncOutboxState::Acknowledged)
222            .unwrap());
223        assert_eq!(
224            outbox.list_recent(1).unwrap()[0].state,
225            SyncOutboxState::Acknowledged
226        );
227    }
228
229    #[test]
230    fn sync_outbox_serializes_pascal_case_state() {
231        let dir = tempfile::tempdir().unwrap();
232        let outbox = SyncOutbox::open(dir.path()).unwrap();
233        let entry =
234            SyncOutboxEntry::from_envelope(&sample_envelope("urn:wellfair:heart_rate:hr1"), 1);
235        outbox.enqueue(&entry).unwrap();
236
237        let raw = fs::read_to_string(dir.path().join(SYNC_OUTBOX_FILE)).unwrap();
238        assert!(raw.contains("\"state\":\"Queued\""));
239        assert!(raw.contains("\"kind\":\"heart_rate\""));
240    }
241}