Skip to main content

syncular_client/
progress.rs

1//! Ephemeral live sync work (SPEC §7.7), observable while the core is busy.
2use crate::api::TransportCauseKind;
3use serde::{Deserialize, Serialize};
4use std::collections::BTreeMap;
5use std::sync::{Arc, Mutex, Weak};
6
7#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
8#[serde(rename_all = "camelCase")]
9pub struct SyncProgress {
10    /// §7.6: the core's random epoch; (`epoch`, `attempt`) identifies the attempt.
11    pub epoch: String,
12    pub attempt: u64,
13    pub state: ProgressState,
14    pub phase: ProgressPhase,
15    #[serde(skip_serializing_if = "Option::is_none")]
16    pub unit_id: Option<String>,
17    #[serde(skip_serializing_if = "Option::is_none")]
18    pub table: Option<String>,
19    #[serde(skip_serializing_if = "Option::is_none")]
20    pub segment_id: Option<String>,
21    pub bytes_received: u64,
22    #[serde(skip_serializing_if = "Option::is_none")]
23    pub bytes_total: Option<u64>,
24    pub rows_processed: u64,
25    #[serde(skip_serializing_if = "Option::is_none")]
26    pub rows_total: Option<u64>,
27    /// SQLite image payloads: time in import transactions before COMMIT, in ms.
28    #[serde(skip_serializing_if = "Option::is_none")]
29    pub import_write_ms: Option<u64>,
30    /// SQLite image payloads: time committing them and publishing their changes.
31    #[serde(skip_serializing_if = "Option::is_none")]
32    pub import_commit_ms: Option<u64>,
33    #[serde(skip_serializing_if = "Option::is_none")]
34    pub error_code: Option<String>,
35    #[serde(skip_serializing_if = "Option::is_none")]
36    pub cause_kind: Option<TransportCauseKind>,
37    #[serde(skip_serializing_if = "Option::is_none")]
38    pub http_status: Option<u16>,
39    /// Present on `failed` when the core scheduled a background retry.
40    #[serde(skip_serializing_if = "Option::is_none")]
41    pub retry_delay_ms: Option<u64>,
42}
43#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
44#[serde(rename_all = "camelCase")]
45pub enum ProgressState {
46    Running,
47    Complete,
48    Failed,
49}
50#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
51#[serde(rename_all = "camelCase")]
52pub enum ProgressPhase {
53    Request,
54    Download,
55    Import,
56}
57
58pub type SyncProgressListener = Arc<dyn Fn(&SyncProgress) + Send + Sync>;
59
60struct Delivery {
61    callback: SyncProgressListener,
62    revision: Mutex<u64>,
63}
64impl Delivery {
65    fn notify(&self, revision: u64, snapshot: &SyncProgress) {
66        let mut delivered = self.revision.lock().expect("progress delivery lock");
67        if revision <= *delivered {
68            return;
69        }
70        *delivered = revision;
71        // Serialize a late initial replay with updates from the owner thread.
72        // The observer registry is unlocked, so callbacks can read/unsubscribe.
73        let _ =
74            std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| (self.callback)(snapshot)));
75    }
76}
77#[derive(Default)]
78struct Inner {
79    snapshot: Option<SyncProgress>,
80    listeners: BTreeMap<u64, Arc<Delivery>>,
81    revision: u64,
82    next_listener: u64,
83}
84
85#[derive(Clone, Default)]
86pub struct ProgressObserver(Arc<Mutex<Inner>>);
87
88/// Keep this guard alive to receive updates; dropping it unsubscribes.
89pub struct ProgressSubscription {
90    inner: Weak<Mutex<Inner>>,
91    id: u64,
92}
93impl Drop for ProgressSubscription {
94    fn drop(&mut self) {
95        if let Some(inner) = self.inner.upgrade() {
96            inner
97                .lock()
98                .expect("progress lock")
99                .listeners
100                .remove(&self.id);
101        }
102    }
103}
104impl ProgressObserver {
105    pub fn snapshot(&self) -> Option<SyncProgress> {
106        self.0.lock().expect("progress lock").snapshot.clone()
107    }
108    pub fn subscribe(
109        &self,
110        listener: impl Fn(&SyncProgress) + Send + Sync + 'static,
111    ) -> ProgressSubscription {
112        let listener = Arc::new(Delivery {
113            callback: Arc::new(listener),
114            revision: Mutex::new(0),
115        });
116        let (id, revision, snapshot) = {
117            let mut inner = self.0.lock().expect("progress lock");
118            inner.next_listener += 1;
119            let id = inner.next_listener;
120            inner.listeners.insert(id, listener.clone());
121            (id, inner.revision, inner.snapshot.clone())
122        };
123        if let Some(snapshot) = snapshot {
124            listener.notify(revision, &snapshot);
125        }
126        ProgressSubscription {
127            inner: Arc::downgrade(&self.0),
128            id,
129        }
130    }
131    pub(crate) fn start(&self, epoch: &str) -> u64 {
132        let attempt = self.snapshot().map_or(1, |s| s.attempt + 1);
133        self.emit(SyncProgress {
134            epoch: epoch.to_owned(),
135            attempt,
136            state: ProgressState::Running,
137            phase: ProgressPhase::Request,
138            unit_id: None,
139            table: None,
140            segment_id: None,
141            bytes_received: 0,
142            bytes_total: None,
143            rows_processed: 0,
144            rows_total: None,
145            import_write_ms: None,
146            import_commit_ms: None,
147            error_code: None,
148            cause_kind: None,
149            http_status: None,
150            retry_delay_ms: None,
151        });
152        attempt
153    }
154    pub(crate) fn update(&self, update: impl FnOnce(&mut SyncProgress)) {
155        if let Some(mut snapshot) = self.snapshot() {
156            if snapshot.state != ProgressState::Running {
157                return;
158            }
159            update(&mut snapshot);
160            self.emit(snapshot);
161        }
162    }
163    fn emit(&self, snapshot: SyncProgress) {
164        let (revision, listeners) = {
165            let mut inner = self.0.lock().expect("progress lock");
166            inner.snapshot = Some(snapshot.clone());
167            inner.revision += 1;
168            (
169                inner.revision,
170                inner.listeners.values().cloned().collect::<Vec<_>>(),
171            )
172        };
173        for listener in listeners {
174            listener.notify(revision, &snapshot);
175        }
176    }
177}
178
179#[cfg(test)]
180mod tests {
181    use super::*;
182    #[test]
183    fn observes_running_work_and_unsubscribes_without_affecting_sync() {
184        let observer = ProgressObserver::default();
185        observer.start("e");
186        let events = Arc::new(Mutex::new(Vec::new()));
187        let captured = events.clone();
188        let reader = observer.clone();
189        let subscription = observer.subscribe(move |progress| {
190            assert!(reader.snapshot().is_some()); // Callback holds no observer lock.
191            captured.lock().unwrap().push(progress.clone());
192        });
193        let _broken = observer.subscribe(|_| panic!("observer failure"));
194        observer.update(|p| {
195            p.phase = ProgressPhase::Import;
196            p.rows_processed = 1024;
197        });
198        assert_eq!(events.lock().unwrap().len(), 2);
199        drop(subscription);
200        observer.update(|p| {
201            p.state = ProgressState::Failed;
202            p.error_code = Some("sync.transport_failed".into());
203        });
204        assert_eq!(events.lock().unwrap().len(), 2);
205        observer.start("e");
206        let snapshot = observer.snapshot().unwrap();
207        assert_eq!(snapshot.attempt, 2);
208        assert_eq!(snapshot.rows_processed, 0);
209        assert_eq!(snapshot.error_code, None);
210    }
211    #[test]
212    fn late_subscription_replay_cannot_move_progress_backwards() {
213        let observer = ProgressObserver::default();
214        observer.start("e");
215        let before = observer.snapshot().unwrap();
216        let events = Arc::new(Mutex::new(Vec::new()));
217        let captured = events.clone();
218        let delivery = Delivery {
219            callback: Arc::new(move |p| captured.lock().unwrap().push(p.rows_processed)),
220            revision: Mutex::new(0),
221        };
222        let mut after = before.clone();
223        after.rows_processed = 1024;
224        delivery.notify(2, &after);
225        delivery.notify(1, &before);
226        assert_eq!(*events.lock().unwrap(), vec![1024]);
227    }
228}