Native iCloud apps for Windows and Linux, built in Rust. Notes, Reminders, Calendar, Contacts, Drive and Photos, offline and in sync with your iPhone.
Rust apple-notesapple-reminderscloudkitcrdtdesktop-appicloudicloud-calendaricloud-driveicloud-notesicloud-photosiphonelinuxlinux-desktoplocal-firstoffline-firstprivacyrusttauritauri-appwindows
//! Reading a CloudKit private-database zone.
//!
//! Three things about this API bite immediately, and all three fail quietly:
//!
//! * `records/query` is refused for types Apple has not marked indexable — `Reminder` is
//! one — so `changes/zone` is the way in. It is also the incremental path.
//! * `desiredKeys: []` asks for *no* fields rather than all of them, which returns records
//! that look empty.
//! * Responses page. Ignoring `moreComing` silently truncates someone's data.
use crate::{Error, Result};
use serde_json::{json, Value};
/// Records fetched in one request.
///
/// A real account's zone runs to thousands — mostly tombstones — so a small page turns one
/// refresh into dozens of round trips.
const PAGE_SIZE: u64 = 500;
/// A ceiling on paging, so a server that always says `moreComing` cannot spin forever.
const MAX_PAGES: usize = 200;
pub struct ZoneClient<'a> {
http: &'a reqwest::Client,
base: String,
container: String,
params: Vec<(String, String)>,
/// Which of the container's databases: the account's own, or what others share with it.
database: Database,
/// Whose zone it is, for a zone another account owns (one shared with this one): CloudKit
/// finds a shared zone only by its name and its owner together.
owner: Option<String>,
}
/// A CloudKit container's databases this client reads.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Database {
/// The account's own records.
Private,
/// Zones other accounts have shared with this one (an album someone invited you to).
Shared,
}
impl Database {
fn path(self) -> &'static str {
match self {
Self::Private => "private",
Self::Shared => "shared",
}
}
}
/// One page of zone changes.
pub struct Page {
pub records: Vec<Value>,
pub sync_token: Option<String>,
pub more_coming: bool,
}
/// Why a zone came back with nothing, when it did.
///
/// CloudKit answers all of these with HTTP 200 and puts the trouble inside the zone's own
/// result, so a status check alone says everything went fine.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ZoneTrouble {
/// The account has no such zone. A new Apple ID that has never opened Notes has no Notes
/// zone at all — which is an empty library, not a failure.
Missing,
/// The cursor was refused. CloudKit expires them, and a client that has been closed for a
/// while comes back holding one Apple no longer knows. The answer is to start over.
StaleCursor,
/// "Not now": the zone throttled, busy with another write, or asking to be tried later,
/// with the seconds it asked for when it said.
Busy(Option<u64>),
/// The session was not accepted for the zone: a fresh sign-in, not a fault in the zone.
Unauthenticated,
/// Advanced Data Protection keeps the zone from this session until it is approved on one
/// of the person's devices (`ACCESS_DENIED`, "private db access disabled").
Locked,
/// Something else, which is worth showing to somebody.
Other(&'static str),
}
fn trouble_with(zone_result: &Value) -> Option<ZoneTrouble> {
let code = zone_result.get("serverErrorCode").and_then(Value::as_str);
let reason = zone_result.get("reason").and_then(Value::as_str);
match code {
Some("ZONE_NOT_FOUND") => Some(ZoneTrouble::Missing),
Some("ACCESS_DENIED")
if reason.is_some_and(|r| {
r.to_ascii_lowercase()
.contains("private db access disabled")
}) =>
{
Some(ZoneTrouble::Locked)
}
// An expired change token, with or without a reason. Without this arm a bare
// `CHANGE_TOKEN_EXPIRED` matched nothing below and read as an empty, finished page:
// "nothing changed", on a token that would never be read again — every change made
// elsewhere from then on never arrived.
Some("CHANGE_TOKEN_EXPIRED") => Some(ZoneTrouble::StaleCursor),
// Said inside a 200 for the one zone, not as the request's status (timlaing/pyicloud
// #384): read as a refusal, a moment's throttling failed the whole pass in Apple's
// words, and a lapsed session read as a broken zone rather than a sign-in.
Some("THROTTLED" | "TRY_AGAIN_LATER" | "ZONE_BUSY") => Some(ZoneTrouble::Busy(
zone_result.get("retryAfter").and_then(Value::as_u64),
)),
Some("AUTHENTICATION_FAILED" | "AUTHENTICATION_REQUIRED") => {
Some(ZoneTrouble::Unauthenticated)
}
// Apple says BAD_REQUEST for a cursor it will not read, with the reason naming the
// continuation: "Unknown sync continuation type", "Invalid continuation format".
Some("BAD_REQUEST")
if reason.is_some_and(|r| r.to_lowercase().contains("continuation")) =>
{
Some(ZoneTrouble::StaleCursor)
}
// A reason with no code at all still means the zone was refused; so does a code with
// no reason — any code at all is Apple saying something went wrong with the zone.
Some(_) => Some(ZoneTrouble::Other("refused")),
None if reason.is_some() => Some(ZoneTrouble::Other("refused")),
_ => None,
}
}
/// How many times a busy CloudKit is asked before saying so.
const BUSY_TRIES: u32 = 3;
/// A record refused only because the zone was mid-write for someone else — Apple's
/// "Sync zone CAS Op-Lock failed. There was a concurrent write … Retry request", coded
/// ZONE_BUSY or TRY_AGAIN_LATER — measured deleting notes one after another. Nothing was
/// applied; the same change, sent again, goes through.
fn zone_was_busy(code: &str, reason: &str) -> bool {
matches!(code, "ZONE_BUSY" | "TRY_AGAIN_LATER")
|| reason
.to_ascii_lowercase()
.contains("sync zone cas op-lock failed")
}
/// The longest single wait a busy CloudKit is given, whatever it asks for.
const LONGEST_WAIT: u64 = 30;
impl<'a> ZoneClient<'a> {
pub fn new(
http: &'a reqwest::Client,
ckdatabasews_root: &str,
container: &str,
params: Vec<(String, String)>,
) -> Self {
Self {
http,
base: ckdatabasews_root.trim_end_matches('/').to_string(),
container: container.to_string(),
params,
database: Database::Private,
owner: None,
}
}
/// The same client, reading `database`.
#[must_use]
pub fn in_database(mut self, database: Database) -> Self {
self.database = database;
self
}
/// The same client, for zones `owner` owns (a zone shared with this account).
#[must_use]
pub fn owned_by(mut self, owner: Option<String>) -> Self {
self.owner = owner;
self
}
/// A zone as CloudKit names it in a request: its name, and its owner where it is someone
/// else's.
fn zone_id(&self, zone: &str) -> Value {
let mut id = json!({ "zoneName": zone, "zoneType": "REGULAR_CUSTOM_ZONE" });
if let Some(owner) = &self.owner {
id["ownerRecordName"] = json!(owner);
}
id
}
/// The address of one of the database's operations (`records/lookup`, `zones/list` …).
fn url(&self, operation: &str) -> String {
format!(
"{}/database/1/{}/production/{}/{operation}",
self.base,
self.container,
self.database.path()
)
}
fn query(&self) -> Vec<(String, String)> {
let mut q = self.params.clone();
q.push(("ckjsBuildVersion".into(), "17DProjectDev77".into()));
q.push(("ckjsVersion".into(), "2.6.1".into()));
q
}
/// One page of changes for `zone`.
/// POST to CloudKit, waiting out a busy server the way it asks to be waited out.
///
/// Measured on the account: an overloaded CloudKit answers 503 with
/// `{"serverErrorCode":"SERVER_OVERLOADED","retryAfter":10}`. That went to the screen as
/// raw JSON and the write was simply lost. It is a request to come back shortly, so it is
/// honoured — up to `BUSY_TRIES` times, never waiting more than `LONGEST_WAIT` — and only
/// a server still busy after that is reported, in words.
async fn post_json(&self, url: &str, body: &Value) -> Result<(reqwest::StatusCode, String)> {
let mut tries = 0;
loop {
tries += 1;
let response = self
.http
.post(url)
.query(&self.query())
.json(body)
.send()
.await?;
let status = response.status();
let header_wait = response
.headers()
.get("retry-after")
.and_then(|v| v.to_str().ok())
.and_then(|v| v.trim().parse::<u64>().ok());
let text = response.text().await.unwrap_or_default();
// Advanced Data Protection keeping this session out until it is approved on a
// device (403 ACCESS_DENIED, "private db access disabled"): said as that, for every
// CloudKit read and write, rather than as Apple's JSON.
if !status.is_success() {
crate::approval_needed(status, &text)?;
}
// A zone busy with another write answers 409 ZONE_BUSY — "rejected, retry", the
// whole request not applied — measured when a phone and this app wrote at once.
// Two of this app's own writes to one zone close together (notes deleted one after
// another in Recently Deleted) answer 409 TRY_AGAIN_LATER, "Sync zone CAS Op-Lock
// failed. There was a concurrent write" — the same: nothing applied, ask again.
// Each is a wait like 503's, not a conflict over the record.
let zone_busy = status.as_u16() == 409
&& (text.contains("\"ZONE_BUSY\"") || text.contains("\"TRY_AGAIN_LATER\""));
if !matches!(status.as_u16(), 429 | 503) && !zone_busy {
return Ok((status, text));
}
if tries >= BUSY_TRIES {
quiet!("cloudkit: still busy after {tries} tries ({status})");
// Busy, not refused: nothing was applied, and a change waiting to be sent is
// kept for later rather than dropped as if Apple had turned it down.
return Err(Error::Busy);
}
let asked = serde_json::from_str::<Value>(&text)
.ok()
.and_then(|v| v.get("retryAfter").and_then(Value::as_u64))
.or(header_wait)
.unwrap_or(2);
tokio::time::sleep(std::time::Duration::from_secs(asked.clamp(1, LONGEST_WAIT))).await;
}
}
pub async fn changes(&self, zone: &str, sync_token: Option<&str>) -> Result<Page> {
let mut zone_body = json!({
"zoneID": self.zone_id(zone),
"maxChanges": PAGE_SIZE,
});
// An empty string is not a cursor — Apple answers one with a 500. Absent means
// "from the beginning", which is what an empty one was trying to say anyway.
if let Some(token) = sync_token.map(str::trim).filter(|t| !t.is_empty()) {
zone_body["syncToken"] = Value::String(token.to_string());
}
// Note: no `desiredKeys`. Sending an empty list asks Apple for no fields at all.
let url = self.url("changes/zone");
let mut tries = 0;
loop {
tries += 1;
match self.changes_once(&url, zone, &zone_body).await {
Err(e) => return Err(e),
Ok(Ok(page)) => return Ok(page),
// Waited out as a busy request is (`post_json`), then said in words.
Ok(Err(asked)) if tries < BUSY_TRIES => {
let wait = asked.unwrap_or(2).clamp(1, LONGEST_WAIT);
tokio::time::sleep(std::time::Duration::from_secs(wait)).await;
}
Ok(Err(_)) => {
quiet!("cloudkit: zone {zone} still busy after {tries} tries");
return Err(Error::Busy);
}
}
}
}
/// One `changes/zone` request: the page, or the wait a busy zone asked for.
async fn changes_once(
&self,
url: &str,
zone: &str,
zone_body: &Value,
) -> Result<std::result::Result<Page, Option<u64>>> {
let (status, text) = self
.post_json(url, &json!({ "zones": [zone_body] }))
.await?;
if status.as_u16() == 450 {
return Err(Error::ReauthRequired);
}
if !status.is_success() {
return Err(Error::Protocol(format!(
"CloudKit zone {zone} returned {status}: {}",
text.chars().take(200).collect::<String>()
)));
}
let body: Value = serde_json::from_str(&text)
.map_err(|e| Error::Protocol(format!("CloudKit returned invalid JSON: {e}")))?;
let zone_result = body
.get("zones")
.and_then(Value::as_array)
.and_then(|zones| zones.first())
.ok_or_else(|| Error::Protocol("CloudKit returned no zone".into()))?;
match trouble_with(zone_result) {
// A zone that does not exist is an account that has never used the thing. Reading
// it as an empty, finished walk is the truth; raising is not.
Some(ZoneTrouble::Missing) => {
return Ok(Ok(Page {
records: Vec::new(),
sync_token: None,
more_coming: false,
}))
}
Some(ZoneTrouble::StaleCursor) => return Err(Error::StaleCursor),
Some(ZoneTrouble::Busy(asked)) => return Ok(Err(asked)),
Some(ZoneTrouble::Unauthenticated) => return Err(Error::ReauthRequired),
Some(ZoneTrouble::Locked) => return Err(Error::NeedsDeviceApproval),
Some(ZoneTrouble::Other(_)) => {
let reason = zone_result
.get("reason")
.and_then(Value::as_str)
.unwrap_or("no reason given");
return Err(Error::Protocol(format!(
"CloudKit refused zone {zone}: {reason}"
)));
}
None => {}
}
Ok(Ok(Page {
records: zone_result
.get("records")
.and_then(Value::as_array)
.cloned()
.unwrap_or_default(),
sync_token: zone_result
.get("syncToken")
.and_then(Value::as_str)
.map(ToString::to_string),
more_coming: zone_result
.get("moreComing")
.and_then(Value::as_bool)
.unwrap_or(false),
}))
}
/// Every record in a zone, following `moreComing`.
///
/// Returns the records and the final sync token, which a later call can resume from so a
/// refresh fetches only what changed.
pub async fn all_records(&self, zone: &str, since: Option<&str>) -> Result<ZoneWalk> {
match self.walk(zone, since).await {
// CloudKit expires cursors, so an app that has been closed for a while comes back
// holding one Apple will not read. Starting over is what it expects a client to
// do, and it is invisible to the person: the library is already on disk, and a
// full pass replaces it with the same thing plus whatever changed.
Err(Error::StaleCursor) if since.is_some() => self.walk(zone, None).await,
other => other,
}
}
async fn walk(&self, zone: &str, since: Option<&str>) -> Result<ZoneWalk> {
let since = since.map(str::trim).filter(|t| !t.is_empty());
let mut records = Vec::new();
let mut token = since.map(ToString::to_string);
let mut complete = false;
for page_no in 0..MAX_PAGES {
let page = self.changes(zone, token.as_deref()).await?;
// A cursor answered with no position at all was not taken: an expired one can
// come back as an empty zone result, which read as "nothing changed" for good.
if page_no == 0 && token.is_some() && page.sync_token.is_none() {
return Err(Error::StaleCursor);
}
records.extend(page.records);
let (next, advanced) = advance(token.take(), page.sync_token);
token = next;
if !page.more_coming {
complete = true;
break;
}
// "More coming" with no new position — none, or the one just sent — would ask
// the same thing again, up to the page limit (coddingtonbear/icloud-md#48): it
// stops there, unfinished, and the next pass asks again from where it is.
if !advanced {
break;
}
}
Ok(ZoneWalk {
records,
from_start: since.is_none(),
token,
complete,
})
}
}
/// Where a walk carries on from after a page: the page's position, or — given none, or an empty
/// one — the one it was asked from, so the last page leaving it out never loses the place
/// (and the next pass never reads the whole zone again for it). Answers whether it moved.
pub(crate) fn advance(asked: Option<String>, given: Option<String>) -> (Option<String>, bool) {
match given.filter(|t| !t.is_empty()) {
Some(t) if asked.as_ref() != Some(&t) => (Some(t), true),
Some(t) => (Some(t), false),
None => (asked, false),
}
}
/// What one walk of a zone returned.
///
/// `complete` is the part that matters. A walk stops at a page cap, and one that stopped
/// early has seen only part of the zone — treating that as the whole truth and pruning
/// everything it did not mention would delete records that are perfectly fine. Nothing
/// authoritative may be done with a walk that did not finish.
pub struct ZoneWalk {
pub records: Vec<Value>,
pub token: Option<String>,
pub complete: bool,
/// Read from the zone's beginning — no cursor asked for, or the cursor refused and the
/// walk started over. A walk from a cursor carries only changes, where absence means
/// unchanged; one started over after a refused cursor carries everything and is as
/// authoritative as a first pass (`ZoneWalk::whole`).
pub from_start: bool,
}
impl ZoneWalk {
/// Whether this walk read the zone from its beginning — asked for no cursor, or its cursor
/// refused and the walk started over — and to its end. Only such a walk is the whole truth
/// that rows missing from it may be pruned by; any other carries changes, or part of the
/// zone, where absence means nothing.
#[must_use]
pub fn whole(&self) -> bool {
self.from_start && self.complete
}
}
/// Field helpers. CloudKit wraps every value as `{"type": …, "value": …}`.
pub mod field {
use serde_json::Value;
#[must_use]
pub fn string(record: &Value, name: &str) -> Option<String> {
record
.pointer(&format!("/fields/{name}/value"))?
.as_str()
.map(ToString::to_string)
}
#[must_use]
pub fn int(record: &Value, name: &str) -> Option<i64> {
record.pointer(&format!("/fields/{name}/value"))?.as_i64()
}
#[must_use]
pub fn flag(record: &Value, name: &str) -> bool {
int(record, name).unwrap_or(0) != 0
}
/// CloudKit timestamps are milliseconds; the library stores seconds.
#[must_use]
pub fn timestamp_seconds(record: &Value, name: &str) -> Option<i64> {
int(record, name).map(|ms| ms / 1000)
}
/// The target of a REFERENCE field, e.g. `List/A233F124-…`.
#[must_use]
pub fn reference(record: &Value, name: &str) -> Option<String> {
record
.pointer(&format!("/fields/{name}/value/recordName"))?
.as_str()
.map(ToString::to_string)
}
/// Text out of a document field such as `TitleDocument`.
#[must_use]
pub fn document_text(record: &Value, name: &str) -> Option<String> {
crate::ckdocument::text_from_base64(&string(record, name)?)
}
#[must_use]
pub fn record_name(record: &Value) -> Option<String> {
record.get("recordName")?.as_str().map(ToString::to_string)
}
#[must_use]
pub fn record_type(record: &Value) -> Option<String> {
record.get("recordType")?.as_str().map(ToString::to_string)
}
}
/// Seconds between the Unix epoch and Apple's, the first moment of 2001 UTC.
const APPLE_EPOCH: f64 = 978_307_200.0;
/// The token key Apple uses for a field: its name with the first letter lowered, except where
/// Apple named it something else.
fn token_key(field: &str) -> String {
match field {
"ReminderIDs" => "reminderIDsMergeableOrdering".into(),
_ => {
let mut chars = field.chars();
chars.next().map_or_else(String::new, |first| {
first.to_lowercase().chain(chars).collect()
})
}
}
}
/// Add a `ResolutionTokenMap` to `fields` advancing the token of every field in it.
fn stamp_tokens(fields: &mut Value, current: Option<&Value>) {
let Some(written) = fields.as_object() else {
return;
};
let mut map: Value = current
.and_then(|c| c.pointer("/fields/ResolutionTokenMap/value"))
.and_then(Value::as_str)
.and_then(|s| serde_json::from_str(s).ok())
.filter(|v: &Value| v.get("map").is_some_and(Value::is_object))
.unwrap_or_else(|| json!({ "map": {} }));
let now = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map_or(0.0, |d| d.as_secs_f64())
- APPLE_EPOCH;
let writer = crate::topotext::writer_id();
let names: Vec<String> = written
.keys()
.filter(|k| k.as_str() != "ResolutionTokenMap")
.cloned()
.collect();
for name in names {
let key = token_key(&name);
let counter = map["map"][&key]["counter"].as_u64().unwrap_or(0) + 1;
map["map"][key] =
json!({ "counter": counter, "modificationTime": now, "replicaID": writer });
}
fields["ResolutionTokenMap"] = json!({ "type": "STRING", "value": map.to_string() });
}
#[cfg(test)]
mod token_tests {
use super::*;
fn tokens(fields: &Value) -> Value {
serde_json::from_str(fields["ResolutionTokenMap"]["value"].as_str().unwrap()).unwrap()
}
/// The shape measured on the phone's own records.
#[test]
fn each_field_written_gets_its_token_advanced() {
let current = json!({ "fields": { "ResolutionTokenMap": { "type": "STRING", "value":
r#"{"map":{"titleDocument":{"counter":1,"modificationTime":803701265.4,"replicaID":"A"},
"priority":{"counter":4,"modificationTime":803701265.4,"replicaID":"B"},
"reminderIDsMergeableOrdering":{"counter":123,"modificationTime":1.0,"replicaID":"C"}}}"# } } });
let mut fields = json!({
"TitleDocument": { "type": "ENCRYPTED_BYTES", "value": "x" },
"ReminderIDs": { "type": "STRING", "value": "[]" },
"LastModifiedDate": { "type": "TIMESTAMP", "value": 1 },
});
stamp_tokens(&mut fields, Some(¤t));
let map = &tokens(&fields)["map"];
assert_eq!(map["titleDocument"]["counter"], 2);
assert_eq!(map["reminderIDsMergeableOrdering"]["counter"], 124);
assert_eq!(map["lastModifiedDate"]["counter"], 1);
// What was not written is left exactly as it was.
assert_eq!(map["priority"]["counter"], 4);
assert_eq!(map["priority"]["replicaID"], "B");
// Now, in Apple's seconds, by this installation.
let t = map["titleDocument"]["modificationTime"].as_f64().unwrap();
assert!(t > 812_000_000.0, "{t}");
assert_eq!(
map["titleDocument"]["replicaID"],
crate::topotext::writer_id()
);
}
#[test]
fn a_new_record_starts_every_token_at_one() {
let mut fields = json!({ "Name": { "type": "STRING", "value": "GYM" } });
stamp_tokens(&mut fields, None);
assert_eq!(tokens(&fields)["map"]["name"]["counter"], 1);
}
#[test]
fn a_broken_map_is_started_again_rather_than_kept() {
let current = json!({ "fields": { "ResolutionTokenMap": { "type": "STRING", "value": "not json" } } });
let mut fields = json!({ "Flagged": { "type": "NUMBER_INT64", "value": 1 } });
stamp_tokens(&mut fields, Some(¤t));
assert_eq!(tokens(&fields)["map"]["flagged"]["counter"], 1);
}
}
#[cfg(test)]
mod tests {
/// A zone another account owns is asked for in the shared database, by its name and its
/// owner together; the account's own zones, in the private one, by name alone.
#[test]
fn a_shared_zone_is_named_with_its_owner_in_the_shared_database() {
let http = reqwest::Client::new();
let own = ZoneClient::new(&http, "https://ck.example/", "c", vec![]);
assert_eq!(
own.url("zones/list"),
"https://ck.example/database/1/c/production/private/zones/list"
);
assert!(own.zone_id("Z").get("ownerRecordName").is_none());
let theirs = ZoneClient::new(&http, "https://ck.example/", "c", vec![])
.in_database(Database::Shared)
.owned_by(Some("_owner".into()));
assert_eq!(
theirs.url("records/lookup"),
"https://ck.example/database/1/c/production/shared/records/lookup"
);
assert_eq!(theirs.zone_id("Z")["ownerRecordName"], "_owner");
assert_ne!(
own.scope(),
theirs.scope(),
"what is learnt of one is never taken for the other"
);
}
use super::*;
use wiremock::matchers::{method, path_regex};
use wiremock::{Mock, MockServer, ResponseTemplate};
fn record(name: &str, kind: &str) -> Value {
json!({
"recordName": name,
"recordType": kind,
"fields": { "Completed": { "type": "NUMBER_INT64", "value": 0 } }
})
}
fn overloaded() -> ResponseTemplate {
// What the account sent, verbatim but for the uuid.
ResponseTemplate::new(503).set_body_json(json!({
"uuid": "1", "retryAfter": 1, "serverErrorCode": "SERVER_OVERLOADED"
}))
}
/// A busy CloudKit asks to be asked again shortly; asked again, the change goes through
/// instead of being lost with raw JSON on the screen.
#[tokio::test]
async fn an_overloaded_cloudkit_is_waited_out() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(overloaded())
.up_to_n_times(1)
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "recordName": "R", "recordChangeTag": "t2" }]
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
client
.update_record("Reminders", "R", "Reminder", Some("t1"), json!({}))
.await
.unwrap();
}
/// A zone busy with another device's write answers 409 ZONE_BUSY and asks to be asked
/// again — measured on the account — and asked again, the write goes through.
#[tokio::test]
async fn a_busy_zone_is_waited_out() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(409).set_body_json(json!({
"uuid": "1", "serverErrorCode": "ZONE_BUSY",
"reason": "Sync zone CAS Op-Lock failed. There was a concurrent write and this operation was rejected. Retry"
})))
.up_to_n_times(1)
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "recordName": "R", "recordChangeTag": "t2" }]
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
client
.update_record("Reminders", "R", "Reminder", Some("t1"), json!({}))
.await
.unwrap();
}
/// Two of this app's own writes close together: Apple's answer, word for word as he met it
/// deleting notes in Recently Deleted, is waited out the same way.
#[tokio::test]
async fn a_concurrent_write_is_tried_again() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(409).set_body_json(json!({
"uuid": "d1fdc23f-b3c5-4537-8ab2-75e2ec1606f9", "serverErrorCode": "TRY_AGAIN_LATER",
"reason": "Sync zone CAS Op-Lock failed. There was a concurrent write and this operation was rejected."
})))
.up_to_n_times(1)
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "recordName": "N", "recordChangeTag": "t2" }]
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.notes", vec![]);
client
.update_record("Notes", "N", "Note", Some("t1"), json!({}))
.await
.unwrap();
}
/// The same refusal carried per record in a 200, as Apple also sends it: tried again too.
#[tokio::test]
async fn a_record_refused_for_a_busy_zone_is_tried_again() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "recordName": "N", "serverErrorCode": "TRY_AGAIN_LATER",
"reason": "Sync zone CAS Op-Lock failed. There was a concurrent write and this operation was rejected. Retry request..." }]
})))
.up_to_n_times(1)
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "recordName": "N", "recordChangeTag": "t2" }]
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.notes", vec![]);
client
.update_record("Notes", "N", "Note", Some("t1"), json!({}))
.await
.unwrap();
}
/// And one still busy after that is said in a sentence, not Apple's JSON.
#[tokio::test]
async fn a_cloudkit_that_stays_busy_says_so_plainly() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(overloaded())
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
let message = client
.update_record("Reminders", "R", "Reminder", Some("t1"), json!({}))
.await
.unwrap_err()
.to_string();
assert_eq!(
message,
"iCloud is busy right now. Nothing was changed — try again in a minute."
);
}
/// Ignoring moreComing silently truncates someone's data, so paging is the thing to test.
#[tokio::test]
async fn paging_follows_more_coming_to_the_end() {
let server = MockServer::start().await;
let pages = vec![
json!({ "zones": [{ "records": [record("a", "Reminder")],
"syncToken": "t1", "moreComing": true }] }),
json!({ "zones": [{ "records": [record("b", "Reminder")],
"syncToken": "t2", "moreComing": true }] }),
json!({ "zones": [{ "records": [record("c", "Reminder")],
"syncToken": "t3", "moreComing": false }] }),
];
for page in pages {
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone$"))
.respond_with(ResponseTemplate::new(200).set_body_json(page))
.up_to_n_times(1)
.mount(&server)
.await;
}
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
let ZoneWalk { records, token, .. } = client.all_records("Reminders", None).await.unwrap();
assert_eq!(records.len(), 3, "every page must be collected");
assert_eq!(
token.as_deref(),
Some("t3"),
"the final cursor is what resumes later"
);
}
/// A server that says more-coming but hands back the position it was asked from would be
/// asked the same thing two hundred times (coddingtonbear/icloud-md#48): the walk stops,
/// unfinished, at the position it reached.
#[tokio::test]
async fn paging_stops_when_the_cursor_does_not_move() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"zones": [{ "records": [record("a", "Reminder")], "syncToken": "STUCK", "moreComing": true }]
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
let walk = client.all_records("Reminders", None).await.unwrap();
assert!(!walk.complete, "not the whole zone");
assert_eq!(walk.token.as_deref(), Some("STUCK"));
assert_eq!(
server.received_requests().await.unwrap().len(),
2,
"asked once more, then stopped"
);
}
/// A last page that leaves its position out, or leaves it empty, keeps the one the walk
/// was at: dropped, the next pass read the whole zone again.
#[test]
fn a_page_without_a_position_keeps_the_one_before() {
assert_eq!(advance(Some("A".into()), None), (Some("A".into()), false));
assert_eq!(
advance(Some("A".into()), Some(String::new())),
(Some("A".into()), false)
);
assert_eq!(
advance(Some("A".into()), Some("A".into())),
(Some("A".into()), false)
);
assert_eq!(
advance(Some("A".into()), Some("B".into())),
(Some("B".into()), true)
);
assert_eq!(advance(None, Some("B".into())), (Some("B".into()), true));
assert_eq!(advance(None, None), (None, false));
}
/// A server that always says more-coming without a cursor must not spin.
#[tokio::test]
async fn paging_stops_when_there_is_no_cursor() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"zones": [{ "records": [record("a", "Reminder")], "moreComing": true }]
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
let ZoneWalk { records, .. } = client.all_records("Reminders", None).await.unwrap();
assert_eq!(records.len(), 1);
}
#[tokio::test]
async fn a_refused_zone_is_an_error_not_an_empty_result() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"zones": [{ "reason": "Zone does not exist" }]
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
assert!(client.all_records("Missing", None).await.is_err());
}
#[test]
fn field_helpers_read_cloudkits_wrapping() {
let rec = json!({
"recordName": "Reminder/abc",
"recordType": "Reminder",
"fields": {
"Completed": { "type": "NUMBER_INT64", "value": 1 },
"CreationDate": { "type": "TIMESTAMP", "value": 1_753_808_338_928_i64 },
"List": { "type": "REFERENCE", "value": { "recordName": "List/xyz" } }
}
});
assert_eq!(field::record_name(&rec).as_deref(), Some("Reminder/abc"));
assert_eq!(field::record_type(&rec).as_deref(), Some("Reminder"));
assert!(field::flag(&rec, "Completed"));
assert!(
!field::flag(&rec, "Missing"),
"an absent flag reads as false"
);
assert_eq!(field::reference(&rec, "List").as_deref(), Some("List/xyz"));
assert_eq!(
field::timestamp_seconds(&rec, "CreationDate"),
Some(1_753_808_338),
"milliseconds must become seconds"
);
}
}
impl ZoneClient<'_> {
/// Update one record in the zone.
///
/// `changes` are merged into the record's existing fields, so only what actually changed
/// is sent. The change tag is CloudKit's optimistic-concurrency check: if the record
/// moved since we read it, Apple refuses rather than silently overwriting whatever the
/// phone did.
/// [`Self::update_record`] with no retry: a conflict comes back as [`Error::Conflict`].
///
/// For writes built from the record as it stood — a note's document, with its merge
/// records — where resending the same fields under a newer tag would lay a stale document
/// over whatever the other device just wrote.
pub async fn update_record_exact(
&self,
zone: &str,
record_name: &str,
record_type: &str,
change_tag: &str,
changes: Value,
) -> Result<Value> {
self.modify(
zone,
json!({ "operationType": "update", "record": {
"recordName": record_name,
"recordType": record_type,
"recordChangeTag": change_tag,
"fields": changes,
} }),
)
.await
}
pub async fn update_record(
&self,
zone: &str,
record_name: &str,
record_type: &str,
change_tag: Option<&str>,
changes: Value,
) -> Result<Value> {
let mut record = json!({
"recordName": record_name,
"recordType": record_type,
"fields": changes,
});
// CloudKit rejects an update with no change tag outright — not as a conflict, as a
// malformed request. The local copy legitimately may not have one yet: a record
// created a moment ago has a name before it has a tag. Fetching the current tag is
// what makes a write on a just-created record work instead of failing at 400.
let tag = match change_tag {
Some(tag) => Some(tag.to_string()),
None => self
.lookup_record(zone, record_name)
.await?
.and_then(|fresh| {
fresh
.get("recordChangeTag")
.and_then(Value::as_str)
.map(ToString::to_string)
}),
};
if let Some(tag) = tag {
record["recordChangeTag"] = Value::String(tag);
}
match self
.modify(
zone,
json!({ "operationType": "update", "record": record.clone() }),
)
.await
{
Err(Error::Conflict) => {
// The record moved since we read it — usually the phone changed it, sometimes
// our own previous write advanced the tag. Read the current tag and try once
// more, rather than handing the user an error we can resolve ourselves.
let Some(fresh) = self.lookup_record(zone, record_name).await? else {
return Err(Error::Protocol(
"that record no longer exists in iCloud".into(),
));
};
let Some(tag) = fresh.get("recordChangeTag").and_then(Value::as_str) else {
return Err(Error::Conflict);
};
let mut retried = record;
retried["recordChangeTag"] = Value::String(tag.to_string());
self.modify(
zone,
json!({ "operationType": "update", "record": retried }),
)
.await
}
other => other,
}
}
/// Send one operation to `records/modify` and surface what came back.
/// A `records/query` in the zone: `query` is CloudKit's `{recordType, filterBy}`. For the
/// server-side operations Apple runs as queries — completing a repeating reminder is one —
/// as much as for reading. Answers with the records it returns.
pub async fn records_query(&self, zone: &str, query: Value) -> Result<Vec<Value>> {
let body = json!({
"query": query,
"zoneID": self.zone_id(zone),
});
let url = self.url("records/query");
let (status, text) = self.post_json(&url, &body).await?;
if status.as_u16() == 450 {
return Err(Error::ReauthRequired);
}
if !status.is_success() {
return Err(Error::Protocol(format!(
"CloudKit refused the query ({status}): {}",
text.chars().take(200).collect::<String>()
)));
}
let parsed: Value = serde_json::from_str(&text)
.map_err(|e| Error::Protocol(format!("CloudKit returned invalid JSON: {e}")))?;
Ok(parsed
.get("records")
.and_then(Value::as_array)
.cloned()
.unwrap_or_default())
}
async fn modify(&self, zone: &str, operation: Value) -> Result<Value> {
// A record refused because the zone was busy with another write was not applied: the
// same request goes again after a moment, as a busy server's is.
let mut tries = 0;
loop {
tries += 1;
match self.modify_once(zone, &operation).await {
Err(Error::Busy) if tries < BUSY_TRIES => {
tokio::time::sleep(std::time::Duration::from_millis(
400 * u64::from(tries) * u64::from(tries),
))
.await;
}
Err(Error::Busy) => return Err(Error::Busy),
other => return other,
}
}
}
async fn modify_once(&self, zone: &str, operation: &Value) -> Result<Value> {
let body = json!({
"operations": [operation],
"zoneID": self.zone_id(zone),
});
let url = self.url("records/modify");
let (status, text) = self.post_json(&url, &body).await?;
if status.as_u16() == 450 {
return Err(Error::ReauthRequired);
}
if !status.is_success() {
return Err(Error::Protocol(format!(
"CloudKit refused the change ({status}): {}",
text.chars().take(200).collect::<String>()
)));
}
let parsed: Value = serde_json::from_str(&text)
.map_err(|e| Error::Protocol(format!("CloudKit returned invalid JSON: {e}")))?;
// A 200 can still carry a per-record failure, which is how a conflict arrives.
if let Some(reason) = parsed.pointer("/records/0/reason").and_then(Value::as_str) {
let code = parsed
.pointer("/records/0/serverErrorCode")
.and_then(Value::as_str)
.unwrap_or("");
if zone_was_busy(code, reason) {
return Err(Error::Busy);
}
// Apple signals a stale change tag as CONFLICT, and sometimes as an "oplock"
// message with a different code; both mean the same thing.
let stale = code == "CONFLICT" || reason.to_ascii_lowercase().contains("oplock");
return Err(if stale {
Error::Conflict
} else {
Error::Protocol(format!("CloudKit refused the change: {reason}"))
});
}
Ok(parsed)
}
}
impl ZoneClient<'_> {
/// Create a record in the zone.
///
/// The caller supplies the record name so the same identifier can be stored locally
/// without waiting for a round trip.
/// [`Self::update_record`], with each changed field's resolution token advanced.
///
/// Reminders and lists carry `ResolutionTokenMap`, a JSON map from each field to
/// `{counter, modificationTime, replicaID}`, and a phone merges field by field on those
/// tokens. A write that leaves them alone gives a phone no reason to prefer it — measured on
/// the account, a reminder created here had every token at counter 0, and the phone's own
/// edits carry counters of 1 and up. So each field written gets its counter raised, the
/// time set to now, and this installation as the writer. Only for record types that carry
/// the map: CloudKit refuses a field its schema does not already have.
pub async fn update_record_signed(
&self,
zone: &str,
record_name: &str,
record_type: &str,
change_tag: Option<&str>,
changes: Value,
) -> Result<Value> {
// The token map is one field written whole, worked out from the record as read. The
// plain retry resent it after a conflict: every counter a phone had raised in between
// went back to what it was before, and the phone's next merge could prefer an older
// value of a field this write never touched. So each try is stamped from a fresh read,
// and written only over that version.
let mut tag = change_tag.map(ToString::to_string);
for _ in 0..5 {
let current = self.lookup_record(zone, record_name).await?;
let mut stamped = changes.clone();
stamp_tokens(&mut stamped, current.as_ref());
let Some(fresh) = current
.as_ref()
.and_then(|c| c.get("recordChangeTag"))
.and_then(Value::as_str)
else {
// Nothing there to stamp against: Apple's own answer to the write says why.
return self
.update_record(zone, record_name, record_type, tag.as_deref(), stamped)
.await;
};
// The caller's tag first, as before: a change made elsewhere since it was read is
// still laid under this one, field by field, on the fresh read below.
let first = tag.take().unwrap_or_else(|| fresh.to_string());
match self
.update_record_exact(zone, record_name, record_type, &first, stamped)
.await
{
Err(Error::Conflict) => continue,
other => return other,
}
}
Err(Error::Conflict)
}
/// [`Self::update_record_signed`] with no retry: a conflict comes back as
/// [`Error::Conflict`], for a caller whose fields were built from the record as it stood
/// (a reminder's title document) and must be built again, not resent.
pub async fn update_record_signed_exact(
&self,
zone: &str,
record_name: &str,
record_type: &str,
change_tag: &str,
mut changes: Value,
) -> Result<Value> {
let current = self.lookup_record(zone, record_name).await?;
stamp_tokens(&mut changes, current.as_ref());
self.update_record_exact(zone, record_name, record_type, change_tag, changes)
.await
}
/// Change a record by working the change out from the record as Apple holds it, written
/// only over that exact version — and, if another device wrote first, read again and
/// worked out again. For fields written whole from what was read, such as a list's order:
/// the plain retry resent the array built from the older read, and a reminder the phone
/// had just added dropped out of the order. `change` answers `None` when nothing needs
/// writing. Signed as [`Self::update_record_signed`] signs.
pub async fn edit_record_signed(
&self,
zone: &str,
record_name: &str,
record_type: &str,
change: impl Fn(&Value) -> Option<Value>,
) -> Result<Option<Value>> {
self.edit_record_inner(zone, record_name, record_type, change, true)
.await
}
/// [`Self::edit_record_signed`] for records Apple does not sign — notes.
pub async fn edit_record(
&self,
zone: &str,
record_name: &str,
record_type: &str,
change: impl Fn(&Value) -> Option<Value>,
) -> Result<Option<Value>> {
self.edit_record_inner(zone, record_name, record_type, change, false)
.await
}
async fn edit_record_inner(
&self,
zone: &str,
record_name: &str,
record_type: &str,
change: impl Fn(&Value) -> Option<Value>,
signed: bool,
) -> Result<Option<Value>> {
for _ in 0..5 {
let Some(current) = self.lookup_record(zone, record_name).await? else {
return Err(Error::Refused("That is no longer in iCloud.".into()));
};
let Some(mut changes) = change(¤t) else {
return Ok(None);
};
let Some(tag) = current.get("recordChangeTag").and_then(Value::as_str) else {
return Err(Error::Conflict);
};
if signed {
stamp_tokens(&mut changes, Some(¤t));
}
match self
.update_record_exact(zone, record_name, record_type, tag, changes)
.await
{
Ok(v) => return Ok(Some(v)),
Err(Error::Conflict) => continue,
Err(e) => return Err(e),
}
}
Err(Error::Conflict)
}
/// [`Self::create_record`], with a first token for every field, as the phone makes one.
pub async fn create_record_signed(
&self,
zone: &str,
record_name: &str,
record_type: &str,
mut fields: Value,
) -> Result<Value> {
stamp_tokens(&mut fields, None);
self.create_record(zone, record_name, record_type, fields)
.await
}
pub async fn create_record(
&self,
zone: &str,
record_name: &str,
record_type: &str,
fields: Value,
) -> Result<Value> {
let made = self
.modify(
zone,
json!({
"operationType": "create",
"record": {
"recordName": record_name,
"recordType": record_type,
"fields": fields,
},
}),
)
.await;
match made {
// The connection dropped with the request out: Apple may have made it and the
// answer been lost. Said to have failed, it was made again under a new name — a
// second reminder, a second note. The name is ours, so Apple is asked.
Err(Error::Network(e)) => match self.lookup_record(zone, record_name).await {
Ok(Some(record)) => Ok(json!({ "records": [record] })),
_ => Err(Error::Network(e)),
},
other => other,
}
}
/// Create a record CloudKit names itself, as icloud.com creates a Photos album: no
/// `recordName` in the body. Answers the record made, its name with it.
pub async fn create_record_unnamed(
&self,
zone: &str,
record_type: &str,
fields: Value,
) -> Result<Value> {
let answer = self
.modify(
zone,
json!({
"operationType": "create",
"record": { "recordType": record_type, "fields": fields },
}),
)
.await?;
answer.pointer("/records/0").cloned().ok_or_else(|| {
Error::Protocol("CloudKit made the record but did not say what it is".into())
})
}
/// Remove a record outright.
///
/// `forceDelete` is CloudKit's delete-regardless-of-change-tag. The alternative is to
/// pass the tag and have Apple refuse if it moved, which is right when a person is
/// editing and wrong when they have said to delete the thing.
pub async fn delete_record(&self, zone: &str, record_name: &str) -> Result<()> {
self.modify(
zone,
json!({
"operationType": "forceDelete",
"record": { "recordName": record_name },
}),
)
.await?;
Ok(())
}
/// Many records updated at once, as icloud.com sends a selection: up to 200 operations to a
/// `records/modify`, not atomic — each record stands or falls alone — and a record whose
/// change tag had moved (the phone changed it) tried once more on its fresh tag. Answers
/// each update's outcome in the order given: the record as it now is, or why not.
pub async fn update_records(
&self,
zone: &str,
record_type: &str,
updates: &[(String, Option<String>, Value)],
) -> Result<Vec<std::result::Result<Value, String>>> {
let mut out: Vec<std::result::Result<Value, String>> = Vec::with_capacity(updates.len());
for chunk in updates.chunks(200) {
let first = self.modify_many(zone, record_type, chunk).await?;
// The stale ones, once more on the tag Apple has now.
let stale: Vec<usize> = first
.iter()
.enumerate()
.filter(|(_, r)| matches!(r, Err(Error::Conflict)))
.map(|(i, _)| i)
.collect();
let mut answers: Vec<std::result::Result<Value, String>> = first
.into_iter()
.map(|r| r.map_err(|e| e.to_string()))
.collect();
if !stale.is_empty() {
let names: Vec<&str> = stale.iter().map(|&i| chunk[i].0.as_str()).collect();
let fresh = self.lookup_tags(zone, &names).await?;
let again: Vec<(String, Option<String>, Value)> = stale
.iter()
.map(|&i| {
let (name, _, fields) = &chunk[i];
(name.clone(), fresh.get(name).cloned(), fields.clone())
})
.collect();
let second = self.modify_many(zone, record_type, &again).await?;
for (&i, r) in stale.iter().zip(second) {
answers[i] = r.map_err(|e| e.to_string());
}
}
out.extend(answers);
}
Ok(out)
}
/// One `records/modify` of many updates, not atomic; each record's own outcome.
async fn modify_many(
&self,
zone: &str,
record_type: &str,
updates: &[(String, Option<String>, Value)],
) -> Result<Vec<Result<Value>>> {
let operations: Vec<Value> = updates
.iter()
.map(|(name, tag, fields)| {
let mut record =
json!({ "recordName": name, "recordType": record_type, "fields": fields });
if let Some(tag) = tag {
record["recordChangeTag"] = Value::String(tag.clone());
}
json!({ "operationType": "update", "record": record })
})
.collect();
let body = json!({
"operations": operations,
"zoneID": self.zone_id(zone),
"atomic": false,
});
let url = self.url("records/modify");
let (status, text) = self.post_json(&url, &body).await?;
if status.as_u16() == 450 {
return Err(Error::ReauthRequired);
}
if !status.is_success() {
return Err(Error::Protocol(format!(
"CloudKit refused the change ({status}): {}",
text.chars().take(200).collect::<String>()
)));
}
let parsed: Value = serde_json::from_str(&text)
.map_err(|e| Error::Protocol(format!("CloudKit returned invalid JSON: {e}")))?;
let records = parsed
.get("records")
.and_then(Value::as_array)
.cloned()
.unwrap_or_default();
// Matched by name, not place: an answer missing for one is that one's failure.
Ok(updates
.iter()
.map(|(name, _, _)| {
let Some(r) = records
.iter()
.find(|r| r.get("recordName").and_then(Value::as_str) == Some(name.as_str()))
else {
return Err(Error::Protocol("CloudKit did not answer for it".into()));
};
match r.get("reason").and_then(Value::as_str) {
None => Ok(r.clone()),
Some(reason) => {
let code = r
.get("serverErrorCode")
.and_then(Value::as_str)
.unwrap_or("");
// A busy zone is retried as a moved tag is, once more on a fresh read.
Err(
if code == "CONFLICT"
|| reason.to_ascii_lowercase().contains("oplock")
|| zone_was_busy(code, reason)
{
Error::Conflict
} else {
Error::Protocol(format!("CloudKit refused the change: {reason}"))
},
)
}
}
})
.collect())
}
/// The current change tags of many records, by name; one missing is not there any more.
async fn lookup_tags(
&self,
zone: &str,
names: &[&str],
) -> Result<std::collections::HashMap<String, String>> {
let url = self.url("records/lookup");
let body = json!({
"records": names.iter().map(|n| json!({ "recordName": n })).collect::<Vec<_>>(),
"zoneID": self.zone_id(zone),
});
let (status, text) = self.post_json(&url, &body).await?;
if status.as_u16() == 450 {
return Err(Error::ReauthRequired);
}
if !status.is_success() {
return Err(Error::Protocol(format!(
"CloudKit couldn't look those up ({status})"
)));
}
let parsed: Value = serde_json::from_str(&text).unwrap_or(Value::Null);
Ok(parsed
.get("records")
.and_then(Value::as_array)
.into_iter()
.flatten()
.filter_map(|r| {
Some((
r.get("recordName")?.as_str()?.to_string(),
r.get("recordChangeTag")?.as_str()?.to_string(),
))
})
.collect())
}
/// The names of the container's private zones Apple could read (`zones/list`). An entry it
/// could not fetch still names its zone but carries `serverErrorCode`, and is left out.
pub async fn zone_names(&self) -> Result<Vec<String>> {
let url = self.url("zones/list");
let (status, text) = self.post_json(&url, &json!({})).await?;
if status.as_u16() == 450 || status.as_u16() == 401 {
return Err(Error::ReauthRequired);
}
if !status.is_success() {
return Err(Error::Protocol(format!(
"CloudKit couldn't list its zones ({status})"
)));
}
let parsed: Value = serde_json::from_str(&text).unwrap_or(Value::Null);
Ok(parsed
.get("zones")
.and_then(Value::as_array)
.into_iter()
.flatten()
.filter(|z| z.get("serverErrorCode").is_none())
.filter_map(|z| z.pointer("/zoneID/zoneName").and_then(Value::as_str))
.map(str::to_string)
.collect())
}
/// Every zone in the database Apple could read (`zones/list`), as its name and — in the
/// shared database, where zones belong to other accounts — its owner.
pub async fn zone_ids(&self) -> Result<Vec<(String, Option<String>)>> {
let (status, text) = self.post_json(&self.url("zones/list"), &json!({})).await?;
if status.as_u16() == 450 || status.as_u16() == 401 {
return Err(Error::ReauthRequired);
}
if !status.is_success() {
return Err(Error::Protocol(format!(
"CloudKit couldn't list its zones ({status})"
)));
}
let parsed: Value = serde_json::from_str(&text).unwrap_or(Value::Null);
let shared = self.database == Database::Shared;
Ok(parsed
.get("zones")
.and_then(Value::as_array)
.into_iter()
.flatten()
.filter(|z| {
z.get("serverErrorCode").is_none() && z.get("deleted") != Some(&json!(true))
})
.filter_map(|z| {
let name = z.pointer("/zoneID/zoneName")?.as_str()?.to_string();
let owner = z
.pointer("/zoneID/ownerRecordName")
.and_then(Value::as_str)
.filter(|_| shared)
.map(str::to_string);
Some((name, owner))
})
.collect())
}
/// Who this client reads for: the database, the container and the account (`dsid`), so
/// something learnt of one account is never taken for another's.
#[must_use]
pub fn scope(&self) -> String {
let dsid = self
.params
.iter()
.find(|(k, _)| k == "dsid")
.map_or("", |(_, v)| v.as_str());
format!(
"{}|{}|{}|{}|{dsid}",
self.base,
self.container,
self.database.path(),
self.owner.as_deref().unwrap_or("")
)
}
pub async fn lookup_record(&self, zone: &str, record_name: &str) -> Result<Option<Value>> {
let url = self.url("records/lookup");
let body = json!({
"records": [{ "recordName": record_name }],
"zoneID": self.zone_id(zone),
});
let (status, text) = self.post_json(&url, &body).await?;
if status.as_u16() == 450 {
return Err(Error::ReauthRequired);
}
// Nothing there is an answer; a server that failed to say is not. A busy or broken
// lookup read as "no such record" sent callers on to create what already existed, or
// to skip what was there.
if status.as_u16() == 404 {
return Ok(None);
}
if !status.is_success() {
return Err(Error::Protocol(format!(
"CloudKit couldn't look that up ({status})"
)));
}
let parsed: Value = serde_json::from_str(&text).unwrap_or(Value::Null);
Ok(parsed
.get("records")
.and_then(Value::as_array)
.and_then(|r| r.first())
.filter(|r| r.get("recordChangeTag").is_some())
.cloned())
}
/// A reference field pointing at another record in the same zone.
#[must_use]
pub fn reference_to(&self, zone: &str, record_name: &str) -> Value {
json!({
"type": "REFERENCE",
"value": {
"action": "VALIDATE",
"recordName": record_name,
"zoneID": self.zone_id(zone),
}
})
}
}
#[cfg(test)]
mod modify_tests {
use super::*;
use wiremock::matchers::{method, path_regex};
use wiremock::{Mock, MockServer, ResponseTemplate};
async fn server_returning(body: Value) -> MockServer {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(200).set_body_json(body))
.mount(&server)
.await;
server
}
#[tokio::test]
async fn an_update_sends_only_what_changed_with_its_change_tag() {
let server = server_returning(json!({ "records": [{ "recordName": "Reminder/1" }] })).await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
client
.update_record(
"Reminders",
"Reminder/1",
"Reminder",
Some("tag-7"),
json!({ "Completed": { "value": 1, "type": "NUMBER_INT64" } }),
)
.await
.unwrap();
let requests = server.received_requests().await.unwrap();
let sent: Value = serde_json::from_slice(&requests[0].body).unwrap();
assert_eq!(sent["operations"][0]["operationType"], "update");
assert_eq!(sent["operations"][0]["record"]["recordChangeTag"], "tag-7");
assert_eq!(
sent["operations"][0]["record"]["fields"]["Completed"]["value"],
1
);
assert_eq!(sent["zoneID"]["zoneName"], "Reminders");
}
/// A refusal that is not a stale tag must surface Apple's own words, and must not be
/// retried — retrying a quota or permission error just asks twice for the same refusal.
#[tokio::test]
async fn a_refusal_that_is_not_a_conflict_is_reported_verbatim() {
let server = server_returning(json!({
"records": [{ "reason": "quota exceeded", "serverErrorCode": "QUOTA_EXCEEDED" }]
}))
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
let err = client
.update_record(
"Reminders",
"Reminder/1",
"Reminder",
Some("tag"),
json!({}),
)
.await
.unwrap_err();
assert!(err.to_string().contains("quota exceeded"), "got: {err}");
let requests = server.received_requests().await.unwrap();
assert_eq!(
requests.len(),
1,
"a non-conflict refusal must not be retried"
);
}
}
#[cfg(test)]
mod walk_tests {
use super::*;
use wiremock::matchers::{method, path_regex};
use wiremock::{Mock, MockServer, ResponseTemplate};
/// A walk that runs out of pages has seen only part of the zone. Saying so is what
/// stops a caller treating it as the whole truth and deleting everything it missed.
#[tokio::test]
async fn a_walk_that_never_ends_is_reported_incomplete() {
let server = MockServer::start().await;
// Every page claims there is more, forever.
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"zones": [{
"records": [{ "recordName": "Reminder/1", "recordType": "Reminder" }],
"moreComing": true,
"syncToken": "next"
}]
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
let walk = client.all_records("Reminders", None).await.unwrap();
assert!(!walk.complete, "hitting the page cap is not completion");
}
#[tokio::test]
async fn a_walk_that_finishes_says_so() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"zones": [{
"records": [{ "recordName": "Reminder/1", "recordType": "Reminder" }],
"moreComing": false,
"syncToken": "done"
}]
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
let walk = client.all_records("Reminders", None).await.unwrap();
assert!(walk.complete);
assert_eq!(walk.records.len(), 1);
assert_eq!(walk.token.as_deref(), Some("done"));
}
/// "More coming" with no cursor to follow would loop forever; stopping is right, and
/// calling it complete would not be.
#[tokio::test]
async fn more_coming_with_no_cursor_stops_and_admits_it() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"zones": [{ "records": [], "moreComing": true }]
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
let walk = client.all_records("Reminders", None).await.unwrap();
assert!(!walk.complete);
}
}
#[cfg(test)]
mod conflict_tests {
use super::*;
use wiremock::matchers::{method, path_regex};
use wiremock::{Mock, MockServer, ResponseTemplate};
/// A stale change tag is recoverable: read the current one and try again. Handing the
/// user "client oplock error" for something we can resolve is not acceptable.
#[tokio::test]
async fn a_stale_change_tag_is_retried_with_a_fresh_one() {
let server = MockServer::start().await;
// First modify: rejected as stale.
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "reason": "client oplock error updating record",
"serverErrorCode": "ATOMIC_ERROR" }]
})))
.up_to_n_times(1)
.mount(&server)
.await;
// The lookup that supplies the current tag.
Mock::given(method("POST"))
.and(path_regex(r".*/records/lookup$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "recordName": "Reminder/1", "recordChangeTag": "fresh-tag" }]
})))
.mount(&server)
.await;
// Second modify: accepted.
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "recordName": "Reminder/1", "recordChangeTag": "fresh-tag" }]
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
client
.update_record(
"Reminders",
"Reminder/1",
"Reminder",
Some("stale"),
json!({}),
)
.await
.expect("a stale tag should be recovered, not surfaced");
let requests = server.received_requests().await.unwrap();
let modifies: Vec<_> = requests
.iter()
.filter(|r| r.url.path().ends_with("/modify"))
.collect();
assert_eq!(modifies.len(), 2, "it should retry exactly once");
let retried: Value = serde_json::from_slice(&modifies[1].body).unwrap();
assert_eq!(
retried["operations"][0]["record"]["recordChangeTag"], "fresh-tag",
"the retry must carry the tag we just read, not the stale one"
);
}
/// A signed write that lost to a phone's is stamped again from the phone's version: the
/// retry resent the token map worked out from the first read, putting back every counter
/// the phone had raised in between — here the phone's title edit, which a field this
/// write never touched then lost to an older title on the next merge.
#[tokio::test]
async fn a_signed_retry_keeps_the_tokens_another_device_raised() {
let server = MockServer::start().await;
let map = |title: u64| {
json!({ "map": { "titleDocument": { "counter": title, "modificationTime": 1.0, "replicaID": "phone" } } })
.to_string()
};
// First read: the title's token at 1. Second read: the phone has raised it to 7.
Mock::given(method("POST"))
.and(path_regex(r".*/records/lookup$"))
.respond_with(
ResponseTemplate::new(200).set_body_json(json!({ "records": [{
"recordName": "Reminder/1", "recordChangeTag": "t1",
"fields": { "ResolutionTokenMap": { "type": "STRING", "value": map(1) } } }] })),
)
.up_to_n_times(1)
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/lookup$"))
.respond_with(
ResponseTemplate::new(200).set_body_json(json!({ "records": [{
"recordName": "Reminder/1", "recordChangeTag": "t2",
"fields": { "ResolutionTokenMap": { "type": "STRING", "value": map(7) } } }] })),
)
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.and(wiremock::matchers::body_string_contains("\"t1\""))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "reason": "oplock", "serverErrorCode": "CONFLICT" }] })))
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "recordName": "Reminder/1", "recordChangeTag": "t3" }] })))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
client
.update_record_signed(
"Reminders",
"Reminder/1",
"Reminder",
Some("t1"),
json!({ "Flagged": { "type": "NUMBER_INT64", "value": 1 } }),
)
.await
.unwrap();
let requests = server.received_requests().await.unwrap();
let last = requests
.iter()
.rev()
.find(|r| r.url.path().ends_with("/modify"))
.unwrap();
let body: Value = serde_json::from_slice(&last.body).unwrap();
let record = &body["operations"][0]["record"];
assert_eq!(record["recordChangeTag"], "t2");
let tokens: Value = serde_json::from_str(
record["fields"]["ResolutionTokenMap"]["value"]
.as_str()
.unwrap(),
)
.unwrap();
assert_eq!(
tokens["map"]["titleDocument"]["counter"], 7,
"the phone's raised token is kept, not put back to 1"
);
assert_eq!(tokens["map"]["flagged"]["counter"], 1);
}
/// A create whose answer was lost on the way back is found at Apple under the name it was
/// sent with and reported made, not failed — failed, it was made a second time.
#[tokio::test]
async fn a_create_whose_answer_was_lost_is_found_not_made_twice() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(
ResponseTemplate::new(200)
.set_delay(std::time::Duration::from_secs(2))
.set_body_json(
json!({ "records": [{ "recordName": "N1", "recordChangeTag": "t" }] }),
),
)
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/lookup$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "recordName": "N1", "recordChangeTag": "t" }] })))
.mount(&server)
.await;
let http = reqwest::Client::builder()
.timeout(std::time::Duration::from_millis(300))
.build()
.unwrap();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.notes", vec![]);
let made = client
.create_record("Notes", "N1", "Note", json!({}))
.await
.expect("made at Apple, so made");
assert_eq!(made["records"][0]["recordName"], "N1");
// Not there: the failure stands, for the caller to keep and try again.
let empty = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(200).set_delay(std::time::Duration::from_secs(2)))
.mount(&empty)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/lookup$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "recordName": "N1", "serverErrorCode": "NOT_FOUND" }] })))
.mount(&empty)
.await;
let client = ZoneClient::new(&http, &empty.uri(), "com.apple.notes", vec![]);
assert!(matches!(
client.create_record("Notes", "N1", "Note", json!({})).await,
Err(Error::Network(_))
));
}
/// CloudKit rejects an update with no change tag as a malformed request, not as a
/// conflict — so there is nothing to recover from afterwards. The local copy genuinely
/// may not have one: a record created a moment ago has a name before it has a tag, and
/// setting a priority on a reminder you just added hits exactly that.
#[tokio::test]
async fn a_write_without_a_local_tag_fetches_one_first() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/lookup$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "recordName": "Reminder/1", "recordChangeTag": "current" }]
})))
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "recordName": "Reminder/1" }]
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
client
.update_record("Reminders", "Reminder/1", "Reminder", None, json!({}))
.await
.expect("a missing tag should be fetched, not fatal");
let requests = server.received_requests().await.unwrap();
let modify = requests
.iter()
.find(|r| r.url.path().ends_with("/modify"))
.expect("a modify was sent");
let body: Value = serde_json::from_slice(&modify.body).unwrap();
assert_eq!(
body["operations"][0]["record"]["recordChangeTag"], "current",
"the write must carry the tag Apple currently holds"
);
}
/// A tag we already hold is used as-is: fetching one on every write would double the
/// number of requests every edit costs.
#[tokio::test]
async fn a_known_tag_is_used_without_a_lookup() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "recordName": "Reminder/1" }]
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
client
.update_record(
"Reminders",
"Reminder/1",
"Reminder",
Some("known"),
json!({}),
)
.await
.unwrap();
let requests = server.received_requests().await.unwrap();
assert_eq!(requests.len(), 1, "one request, not a lookup and a write");
}
/// If the record is gone, say so plainly rather than retrying forever.
#[tokio::test]
async fn a_vanished_record_is_reported_not_retried() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/modify$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"records": [{ "reason": "client oplock error", "serverErrorCode": "ATOMIC_ERROR" }]
})))
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/records/lookup$"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({ "records": [] })))
.mount(&server)
.await;
let http = reqwest::Client::new();
let client = ZoneClient::new(&http, &server.uri(), "com.apple.reminders", vec![]);
let err = client
.update_record(
"Reminders",
"Reminder/1",
"Reminder",
Some("stale"),
json!({}),
)
.await
.unwrap_err();
assert!(err.to_string().contains("no longer exists"), "got: {err}");
}
}
/// What CloudKit does when something is wrong with a zone or a cursor.
///
/// All of it arrives as HTTP 200 with the trouble inside the zone's own result, so a status
/// check alone says everything went fine. The payloads here are what Apple actually answered
/// when asked, not what the documentation suggests.
#[cfg(test)]
mod trouble_tests {
use super::*;
use wiremock::matchers::{method, path_regex};
use wiremock::{Mock, MockServer, ResponseTemplate};
fn zone_reply(zone: Value) -> ResponseTemplate {
ResponseTemplate::new(200).set_body_json(json!({ "zones": [zone] }))
}
fn record(name: &str, kind: &str) -> Value {
json!({ "recordName": name, "recordType": kind, "fields": {} })
}
fn client<'a>(http: &'a reqwest::Client, uri: &str, container: &str) -> ZoneClient<'a> {
ZoneClient::new(http, uri, container, vec![])
}
/// A brand new Apple ID that has never opened Notes has no Notes zone. That is an empty
/// library, not a failure, and it used to surface as a hard error on every refresh.
#[tokio::test]
async fn a_zone_the_account_has_never_had_reads_as_empty() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.respond_with(zone_reply(json!({
"reason": "Zone does not exist",
"serverErrorCode": "ZONE_NOT_FOUND"
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let uri = server.uri();
let client = client(&http, &uri, "com.apple.notes");
let walk = client.all_records("Notes", None).await.unwrap();
assert!(walk.records.is_empty());
assert!(
walk.complete,
"an account with no such zone has been read in full, not cut short"
);
}
/// CloudKit can throttle one zone inside a 200 — `THROTTLED`, `TRY_AGAIN_LATER` or
/// `ZONE_BUSY` with a `retryAfter` (timlaing/pyicloud#384). That is a wait, not a refusal:
/// waited out, the pass carries on; still busy, it says busy in words.
#[tokio::test]
async fn a_zone_throttled_inside_a_200_is_waited_out() {
for code in ["THROTTLED", "TRY_AGAIN_LATER", "ZONE_BUSY"] {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.respond_with(zone_reply(json!({
"serverErrorCode": code, "reason": "slow down", "retryAfter": 1
})))
.up_to_n_times(1)
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.respond_with(zone_reply(json!({
"records": [record("R1", "Reminder")],
"syncToken": "T1", "moreComing": false
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let uri = server.uri();
let walk = client(&http, &uri, "com.apple.reminders")
.all_records("Reminders", None)
.await
.unwrap_or_else(|e| panic!("{code}: {e}"));
assert_eq!(walk.records.len(), 1, "{code}");
assert!(walk.complete, "{code}");
}
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.respond_with(zone_reply(json!({
"serverErrorCode": "THROTTLED", "retryAfter": 1
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let uri = server.uri();
let err = client(&http, &uri, "com.apple.reminders")
.all_records("Reminders", None)
.await
.err()
.expect("still throttled");
assert!(matches!(err, Error::Busy), "{err:?}");
assert_eq!(
server.received_requests().await.unwrap().len(),
BUSY_TRIES as usize,
"asked again, a few times, then said"
);
}
/// A session the zone will not take, said inside a 200, is a sign-in — not a broken zone.
#[tokio::test]
async fn a_zone_that_wants_a_sign_in_says_so() {
for code in ["AUTHENTICATION_FAILED", "AUTHENTICATION_REQUIRED"] {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.respond_with(zone_reply(json!({ "serverErrorCode": code })))
.mount(&server)
.await;
let http = reqwest::Client::new();
let uri = server.uri();
let err = client(&http, &uri, "com.apple.notes")
.all_records("Notes", None)
.await
.err()
.expect("refused");
assert!(matches!(err, Error::ReauthRequired), "{code}: {err:?}");
}
}
/// Issue #4: an account with Advanced Data Protection, before its session is approved on
/// a device. Said as that — typed, so the approval can be asked for and the zone read again
/// once it is given — never as "iCloud sent back something unexpected" and Apple's JSON.
#[tokio::test]
async fn a_zone_kept_by_advanced_data_protection_asks_for_approval() {
for (status, body) in [
// As reported, at the HTTP level.
(
403,
json!({ "serverErrorCode": "ACCESS_DENIED",
"reason": "private db access disabled for this account" }),
),
// And inside the zone's own result, the way CloudKit answers most zone trouble.
(
200,
json!({ "zones": [{ "zoneID": { "zoneName": "Reminders" },
"serverErrorCode": "ACCESS_DENIED",
"reason": "private db access disabled for this account" }] }),
),
] {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.respond_with(ResponseTemplate::new(status).set_body_json(body))
.mount(&server)
.await;
let http = reqwest::Client::new();
let uri = server.uri();
let client = client(&http, &uri, "com.apple.reminders");
let err = client.all_records("Reminders", None).await.err();
assert!(
matches!(err, Some(Error::NeedsDeviceApproval)),
"{status}: {err:?}"
);
}
}
/// ACCESS_DENIED for anything else — a retired endpoint says it too — is not read as
/// Advanced Data Protection: approving on a phone would not help.
#[tokio::test]
async fn another_access_denied_is_not_read_as_advanced_data_protection() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.respond_with(zone_reply(json!({
"serverErrorCode": "ACCESS_DENIED", "reason": "This endpoint is deprecated."
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let uri = server.uri();
let client = client(&http, &uri, "com.apple.reminders");
let err = client.all_records("Reminders", None).await.err();
assert!(matches!(err, Some(Error::Protocol(_))), "{err:?}");
}
/// CloudKit expires cursors. An app closed for a while comes back holding one Apple will
/// not read, and answers BAD_REQUEST with the reason naming the continuation. Starting
/// over is what it expects; erroring leaves the person stuck with a token that can never
/// come good.
#[tokio::test]
async fn a_cursor_apple_will_not_read_starts_the_walk_over() {
let server = MockServer::start().await;
// The stale cursor is refused; a walk with no cursor succeeds.
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.and(wiremock::matchers::body_string_contains("stale-cursor"))
.respond_with(zone_reply(json!({
"reason": "Unknown sync continuation type",
"serverErrorCode": "BAD_REQUEST"
})))
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.respond_with(zone_reply(json!({
"records": [record("Reminder/1", "Reminder")],
"syncToken": "fresh",
"moreComing": false
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let uri = server.uri();
let client = client(&http, &uri, "com.apple.reminders");
let walk = match client.all_records("Reminders", Some("stale-cursor")).await {
Ok(walk) => walk,
Err(e) => panic!("a refused cursor is recovered from, not raised: {e}"),
};
assert_eq!(walk.records.len(), 1);
assert_eq!(walk.token.as_deref(), Some("fresh"));
assert!(walk.complete);
assert!(walk.whole(), "started over, the walk is the whole zone");
}
/// An expired change token — with Apple's reason, or as the bare code alone — is a cursor
/// to start over from, never "nothing changed". The bare code used to match nothing and
/// read as an empty, finished page, so the dead token was kept and nothing ever arrived.
#[tokio::test]
async fn an_expired_change_token_starts_the_walk_over() {
for expired in [
json!({ "serverErrorCode": "CHANGE_TOKEN_EXPIRED" }),
json!({ "serverErrorCode": "CHANGE_TOKEN_EXPIRED", "reason": "change token expired" }),
] {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.and(wiremock::matchers::body_string_contains("old-token"))
.respond_with(zone_reply(expired.clone()))
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.respond_with(zone_reply(json!({
"records": [record("Note/1", "Note")],
"syncToken": "fresh",
"moreComing": false
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let uri = server.uri();
let client = client(&http, &uri, "com.apple.notes");
let walk = client
.all_records("Notes", Some("old-token"))
.await
.unwrap_or_else(|e| panic!("{expired}: an expired token is started over: {e}"));
assert_eq!(walk.records.len(), 1, "{expired}");
assert_eq!(walk.token.as_deref(), Some("fresh"), "{expired}");
assert!(walk.whole(), "{expired}: a full read, so it may prune");
}
}
/// A cursor answered with no position at all was not taken, whatever the zone result
/// said: it is started over, not stored as "nothing changed" with no token.
#[tokio::test]
async fn a_cursor_answered_with_no_position_starts_the_walk_over() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.and(wiremock::matchers::body_string_contains("old-token"))
.respond_with(zone_reply(json!({ "records": [], "moreComing": false })))
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.respond_with(zone_reply(json!({
"records": [record("Note/1", "Note")],
"syncToken": "fresh",
"moreComing": false
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let uri = server.uri();
let client = client(&http, &uri, "com.apple.notes");
let walk = client
.all_records("Notes", Some("old-token"))
.await
.unwrap();
assert_eq!(walk.records.len(), 1);
assert!(walk.whole());
}
/// A walk from a cursor Apple took carries only changes: never whole, never pruned by.
#[tokio::test]
async fn a_walk_from_a_good_cursor_is_not_whole() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.respond_with(zone_reply(json!({
"records": [], "syncToken": "next", "moreComing": false
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let uri = server.uri();
let client = client(&http, &uri, "com.apple.notes");
let walk = client.all_records("Notes", Some("good")).await.unwrap();
assert!(walk.complete && !walk.whole());
}
/// Trouble that is not a missing zone or a bad cursor is still worth telling somebody
/// about — it must not be swallowed as an empty library.
#[tokio::test]
async fn other_trouble_is_still_raised() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.respond_with(zone_reply(json!({
"reason": "Quota exceeded",
"serverErrorCode": "QUOTA_EXCEEDED"
})))
.mount(&server)
.await;
let http = reqwest::Client::new();
let uri = server.uri();
let client = client(&http, &uri, "com.apple.reminders");
let Err(err) = client.all_records("Reminders", None).await else {
panic!("a real refusal is not an empty library");
};
assert!(err.to_string().contains("Quota exceeded"), "got: {err}");
}
/// An empty string is not a cursor. Apple answers one with a 500, so it must never be
/// sent — and absent already means "from the beginning", which is what it was for.
#[tokio::test]
async fn an_empty_cursor_is_treated_as_no_cursor() {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.and(wiremock::matchers::body_string_contains("syncToken"))
.respond_with(ResponseTemplate::new(500))
.mount(&server)
.await;
Mock::given(method("POST"))
.and(path_regex(r".*/changes/zone"))
.respond_with(zone_reply(json!({ "records": [], "moreComing": false })))
.mount(&server)
.await;
let http = reqwest::Client::new();
let uri = server.uri();
let client = client(&http, &uri, "com.apple.reminders");
for empty in ["", " "] {
client
.all_records("Reminders", Some(empty))
.await
.unwrap_or_else(|e| panic!("{empty:?} should send no cursor at all: {e}"));
}
}
}