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