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