Skip to main content

rightkit_sync/helper/
mod.rs

1//! Backend for a helper process speaking the `rightkit-sync-helper/1`
2//! line-JSON protocol. The macOS CloudKit helper (`rightkit-cloudkit-helper`,
3//! Swift) is the production implementation. See `API.md` section 4.
4
5mod process;
6pub use crate::wire;
7
8use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
9use std::sync::{Arc, Mutex};
10
11use serde_json::{json, Map, Value};
12
13pub use process::{HelperConfig, HelperProcess};
14use wire::{b64_decode, b64_encode, WireRecord};
15
16use crate::error::{SyncError, SyncResult};
17use crate::record::RawRecord;
18use crate::traits::{AuthProvider, Backend, ChangePage, RecordOutcome, SavePolicy, SyncObserver};
19
20/// Seconds to wait before retrying when a page had per-record fetch
21/// failures and the helper gave no guidance (iOS busy hint).
22const FAILED_FETCH_RETRY_SECS: f64 = 30.0;
23
24struct Shared {
25    process: HelperProcess,
26    scope: Mutex<Option<String>>,
27    generation: AtomicU64,
28    enabled: AtomicBool,
29    observer: Arc<dyn SyncObserver>,
30}
31
32/// One helper process shared by the backend and the auth provider of a
33/// single sync engine. Clone freely.
34#[derive(Clone)]
35pub struct CloudKitHelper {
36    shared: Arc<Shared>,
37}
38
39impl CloudKitHelper {
40    pub fn new(cfg: HelperConfig, observer: Arc<dyn SyncObserver>) -> Self {
41        Self {
42            shared: Arc::new(Shared {
43                process: HelperProcess::new(cfg),
44                scope: Mutex::new(None),
45                generation: AtomicU64::new(0),
46                enabled: AtomicBool::new(true),
47                observer,
48            }),
49        }
50    }
51
52    pub fn backend(&self) -> HelperBackend {
53        HelperBackend {
54            shared: Arc::clone(&self.shared),
55        }
56    }
57
58    pub fn auth(&self) -> HelperAuth {
59        HelperAuth {
60            shared: Arc::clone(&self.shared),
61        }
62    }
63
64    /// Number of helper processes started so far.
65    pub fn spawn_count(&self) -> u64 {
66        self.shared.process.spawn_count()
67    }
68
69    /// Stop the helper process; the next call starts a fresh one.
70    pub fn shutdown(&self) {
71        self.shared.process.shutdown();
72    }
73}
74
75impl Shared {
76    fn call(&self, cmd: &str, params: Map<String, Value>) -> SyncResult<Map<String, Value>> {
77        let resp = self.process.call(cmd, params)?;
78        if resp.ok {
79            Ok(resp.rest)
80        } else {
81            let err = resp.error.unwrap_or_else(|| {
82                wire::WireError::new("transient", "helper reported failure without detail", None)
83            });
84            Err(err.into_sync_error())
85        }
86    }
87
88    fn scoped(&self, params: Value) -> Map<String, Value> {
89        let mut m = match params {
90            Value::Object(m) => m,
91            _ => Map::new(),
92        };
93        let scope = self.scope.lock().unwrap().clone();
94        m.insert(
95            "expected_scope".into(),
96            scope.map(Value::String).unwrap_or(Value::Null),
97        );
98        m
99    }
100
101    fn note_scope(&self, scope: Option<String>) {
102        let mut cur = self.scope.lock().unwrap();
103        if *cur != scope {
104            if cur.is_some() {
105                // Account/container/zone changed: fence in-flight passes.
106                self.generation.fetch_add(1, Ordering::SeqCst);
107                self.observer
108                    .event("account_scope_changed", "helper scope changed");
109            }
110            *cur = scope;
111        }
112    }
113}
114
115/// Account state and identity from the helper's `status` command.
116pub struct HelperAuth {
117    shared: Arc<Shared>,
118}
119
120impl HelperAuth {
121    /// The user's sync toggle. Disabling cancels an in-flight pass.
122    pub fn set_enabled(&self, enabled: bool) {
123        self.shared.enabled.store(enabled, Ordering::SeqCst);
124        if !enabled {
125            self.shared.generation.fetch_add(1, Ordering::SeqCst);
126        }
127    }
128}
129
130impl AuthProvider for HelperAuth {
131    fn enabled(&self) -> bool {
132        self.shared.enabled.load(Ordering::SeqCst)
133    }
134
135    fn availability(&self) -> SyncResult<()> {
136        let body = self.shared.call("status", Map::new())?;
137        let scope = body
138            .get("scope")
139            .and_then(Value::as_str)
140            .map(str::to_string);
141        self.shared.note_scope(scope);
142        match body.get("status").and_then(Value::as_str) {
143            Some("ready") => Ok(()),
144            _ => Err(SyncError::Unavailable(
145                body.get("detail")
146                    .and_then(Value::as_str)
147                    .unwrap_or("iCloud is unavailable")
148                    .to_string(),
149            )),
150        }
151    }
152
153    fn generation(&self) -> u64 {
154        self.shared.generation.load(Ordering::SeqCst)
155    }
156
157    fn account_scope(&self) -> Option<String> {
158        self.shared.scope.lock().unwrap().clone()
159    }
160}
161
162/// Zone I/O through the helper.
163pub struct HelperBackend {
164    shared: Arc<Shared>,
165}
166
167fn strings(body: &Map<String, Value>, key: &str) -> Vec<String> {
168    body.get(key)
169        .and_then(Value::as_array)
170        .map(|a| {
171            a.iter()
172                .filter_map(|v| v.as_str().map(str::to_string))
173                .collect()
174        })
175        .unwrap_or_default()
176}
177
178fn malformed(what: &str) -> SyncError {
179    SyncError::Transient(format!("malformed helper response: {what}"))
180}
181
182impl HelperBackend {
183    fn call_scoped(&self, cmd: &str, params: Value) -> SyncResult<Map<String, Value>> {
184        let params = self.shared.scoped(params);
185        let body = self.shared.call(cmd, params)?;
186        if let Some(scope) = body.get("scope").and_then(Value::as_str) {
187            // A response scope that differs from the one we sent means the
188            // account moved under an in-flight call.
189            let expected = self.shared.scope.lock().unwrap().clone();
190            if expected.as_deref() != Some(scope) {
191                self.shared.note_scope(Some(scope.to_string()));
192                return Err(SyncError::Cancelled);
193            }
194        }
195        Ok(body)
196    }
197}
198
199impl Backend for HelperBackend {
200    fn prepare(&self) -> SyncResult<()> {
201        let body = self.call_scoped("prepare", json!({}))?;
202        if let Some(e) = body.get("subscription_error").and_then(Value::as_str) {
203            // Subscription failure is non-fatal: zone sync still works, only
204            // silent pushes are lost.
205            self.shared.observer.event("subscription_failed", e);
206        }
207        Ok(())
208    }
209
210    fn fetch_changes(&self, since: Option<&[u8]>) -> SyncResult<ChangePage> {
211        let since = since.map(b64_encode);
212        let body = self.call_scoped("fetch_changes", json!({ "since": since }))?;
213        // H13: a per-record fetch failure inside an otherwise good page must
214        // fail the page, or the cursor would advance past a record the feed
215        // never lists again.
216        let failed = strings(&body, "failed_records");
217        if !failed.is_empty() {
218            let secs = body
219                .get("failed_retry_after_secs")
220                .and_then(Value::as_f64)
221                .filter(|s| s.is_finite() && *s > 0.0)
222                .unwrap_or(FAILED_FETCH_RETRY_SECS);
223            return Err(SyncError::RetryAfter {
224                secs,
225                detail: format!("{} record(s) failed to fetch", failed.len()),
226            });
227        }
228        let undecodable = strings(&body, "undecodable_records");
229        if !undecodable.is_empty() {
230            self.shared
231                .observer
232                .event("records_undecodable", &undecodable.join(","));
233        }
234        let mut records = Vec::new();
235        for v in body
236            .get("records")
237            .and_then(Value::as_array)
238            .ok_or_else(|| malformed("records"))?
239        {
240            let wire: WireRecord =
241                serde_json::from_value(v.clone()).map_err(|e| malformed(&e.to_string()))?;
242            records.push(wire.into_raw().map_err(|e| malformed(&e))?);
243        }
244        let new_token = match body.get("token").and_then(Value::as_str) {
245            Some(t) => Some(b64_decode(t).map_err(|e| malformed(&e))?),
246            None => None,
247        };
248        Ok(ChangePage {
249            records,
250            deleted_record_names: strings(&body, "deleted"),
251            new_token,
252            more_coming: body
253                .get("more_coming")
254                .and_then(Value::as_bool)
255                .unwrap_or(false),
256        })
257    }
258
259    fn fetch_record(&self, record_name: &str) -> SyncResult<Option<RawRecord>> {
260        let body = self.call_scoped("fetch_record", json!({ "record_name": record_name }))?;
261        match body.get("record") {
262            None | Some(Value::Null) => Ok(None),
263            Some(v) => {
264                let wire: WireRecord =
265                    serde_json::from_value(v.clone()).map_err(|e| malformed(&e.to_string()))?;
266                Ok(Some(wire.into_raw().map_err(|e| malformed(&e))?))
267            }
268        }
269    }
270
271    fn save_records(
272        &self,
273        records: &[RawRecord],
274        policy: SavePolicy,
275    ) -> SyncResult<Vec<RecordOutcome>> {
276        let policy = match policy {
277            SavePolicy::Overwrite => "overwrite",
278            SavePolicy::IfServerUnchanged => "if_server_unchanged",
279        };
280        let wire: Vec<WireRecord> = records.iter().map(WireRecord::from).collect();
281        let body =
282            self.call_scoped("save_records", json!({ "policy": policy, "records": wire }))?;
283        let outcomes = body
284            .get("outcomes")
285            .and_then(Value::as_array)
286            .ok_or_else(|| malformed("outcomes"))?;
287        let mut out = Vec::with_capacity(outcomes.len());
288        for o in outcomes {
289            let name = o
290                .get("name")
291                .and_then(Value::as_str)
292                .ok_or_else(|| malformed("outcome name"))?
293                .to_string();
294            let result = if o.get("ok").and_then(Value::as_bool).unwrap_or(false) {
295                Ok(())
296            } else {
297                let err: wire::WireError = o
298                    .get("error")
299                    .cloned()
300                    .and_then(|e| serde_json::from_value(e).ok())
301                    .unwrap_or_else(|| wire::WireError::new("transient", "save failed", None));
302                Err(err.into_sync_error())
303            };
304            let server_record = match o.get("server_record") {
305                None | Some(Value::Null) => None,
306                Some(v) => {
307                    let wire: WireRecord =
308                        serde_json::from_value(v.clone()).map_err(|e| malformed(&e.to_string()))?;
309                    Some(wire.into_raw().map_err(|e| malformed(&e))?)
310                }
311            };
312            out.push(RecordOutcome {
313                record_name: name,
314                result,
315                server_record,
316            });
317        }
318        Ok(out)
319    }
320}