1mod 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
20const FAILED_FETCH_RETRY_SECS: f64 = 30.0;
23
24const 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#[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 pub fn spawn_count(&self) -> u64 {
71 self.shared.process.spawn_count()
72 }
73
74 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 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
120pub struct HelperAuth {
122 shared: Arc<Shared>,
123}
124
125impl HelperAuth {
126 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
167pub struct HelperBackend {
169 shared: Arc<Shared>,
170}
171
172fn malformed(what: &str) -> SyncError {
173 SyncError::Transient(format!("malformed helper response: {what}"))
174}
175
176fn 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 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 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 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}