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