qualia_client_core/wellfair/
sync_outbox.rs1use 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 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 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 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 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 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 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 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}