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
Recover from stale change tags, and stop guessing which notes are locked
Yashwanth Kamireddi375ed623c17a
diff --git a/crates/quince-icloud/src/cloudkit.rs b/crates/quince-icloud/src/cloudkit.rsindex 3c9784b..d4d666a 100644--- a/crates/quince-icloud/src/cloudkit.rs+++ b/crates/quince-icloud/src/cloudkit.rs@@ -336,8 +336,35 @@ impl ZoneClient<'_> {record["recordChangeTag"] = Value::String(tag.to_string());}- self.modify(zone, json!({ "operationType": "update", "record": record }))+ 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.@@ -380,11 +407,14 @@ impl ZoneClient<'_> {.pointer("/records/0/serverErrorCode").and_then(Value::as_str).unwrap_or("");- return Err(Error::Protocol(if code == "CONFLICT" {- "this changed on another device first — refresh and try again".to_string()+ // 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 {- format!("CloudKit refused the change: {reason}")- }));+ Error::Protocol(format!("CloudKit refused the change: {reason}"))+ });}Ok(parsed)}@@ -416,6 +446,36 @@ impl ZoneClient<'_> {.await}+ /// Fetch one record, for reading its current change tag.+ pub async fn lookup_record(&self, zone: &str, record_name: &str) -> Result<Option<Value>> {+ let url = format!(+ "{}/database/1/{}/production/private/records/lookup",+ self.base, self.container+ );+ let body = json!({+ "records": [{ "recordName": record_name }],+ "zoneID": { "zoneName": zone, "zoneType": "REGULAR_CUSTOM_ZONE" },+ });+ let response = self+ .http+ .post(url)+ .query(&self.query())+ .json(&body)+ .send()+ .await?;+ if !response.status().is_success() {+ return Ok(None);+ }+ let parsed: Value =+ serde_json::from_str(&response.text().await.unwrap_or_default()).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 {@@ -474,23 +534,135 @@ mod modify_tests {assert_eq!(sent["zoneID"]["zoneName"], "Reminders");}- /// CloudKit reports a conflict inside a 200, so a success status is not success.+ /// 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_conflict_inside_a_200_is_an_error() {+ async fn a_refusal_that_is_not_a_conflict_is_reported_verbatim() {let server = server_returning(json!({- "records": [{ "reason": "change tag mismatch", "serverErrorCode": "CONFLICT" }]+ "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", None, json!({}))+ .update_record(+ "Reminders",+ "Reminder/1",+ "Reminder",+ Some("tag"),+ json!({}),+ ).await.unwrap_err();- assert!(- err.to_string().contains("another device"),- "a conflict should tell the user what to do: {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 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");}++ /// 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}");+ }}diff --git a/crates/quince-icloud/src/lib.rs b/crates/quince-icloud/src/lib.rsindex e8458de..b1a8a3e 100644--- a/crates/quince-icloud/src/lib.rs+++ b/crates/quince-icloud/src/lib.rs@@ -18,6 +18,8 @@ pub enum Error {Protocol(String),#[error("this needs a fresh sign-in")]ReauthRequired,+ #[error("this changed on another device first — refresh and try again")]+ Conflict,#[error(transparent)]Storage(#[from] quince_core::Error),}diff --git a/crates/quince-icloud/src/notes.rs b/crates/quince-icloud/src/notes.rsindex 026d4e6..0da6011 100644--- a/crates/quince-icloud/src/notes.rs+++ b/crates/quince-icloud/src/notes.rs@@ -41,7 +41,10 @@ fn note_from_record(record: &Value) -> Option<Note> {title: title.unwrap_or_else(|| "Untitled".into()),snippet: field::document_text(record, "SnippetEncrypted"),body,- locked,+ // Set from the PasswordProtectedNote records below. Inferring it from a body that+ // failed to decode would label our own parsing failures as "locked", which is a+ // claim we would not be able to stand behind.+ locked: false,pinned: false, // carried on the per-user record, applied belowcreated_at: field::timestamp_seconds(record, "CreationDate"),modified_at: field::timestamp_seconds(record, "ModificationDate"),@@ -72,6 +75,8 @@ pub async fn sync_cloudkit(// Deletion and pinning live on the per-user record, keyed by a reference to the note.let mut deleted_notes: std::collections::HashSet<String> = std::collections::HashSet::new();let mut pinned_notes: std::collections::HashSet<String> = std::collections::HashSet::new();+ // Apple names this record type outright, so locking is something we read rather than guess.+ let mut locked_notes: std::collections::HashSet<String> = std::collections::HashSet::new();for record in &records {let Some(kind) = field::record_type(record) else {@@ -98,6 +103,9 @@ pub async fn sync_cloudkit(// Per-user state. The note it refers to is what matters, not this record's name."Note_UserSpecific" | "PasswordProtectedNote_UserSpecific" => {if let Some(target) = field::reference(record, "Note") {+ if kind == "PasswordProtectedNote_UserSpecific" {+ locked_notes.insert(target.clone());+ }if removed {deleted_notes.insert(target);} else if field::flag(record, "IsPinned") {@@ -115,6 +123,7 @@ pub async fn sync_cloudkit(gone.extend(deleted_notes);for note in &mut notes {note.pinned = pinned_notes.contains(¬e.guid);+ note.locked = locked_notes.contains(¬e.guid);}// A note may reference a folder that this page did not carry; keeping the reference@@ -280,13 +289,18 @@ mod tests {assert!(library.notes_in(None).unwrap()[0].pinned);}- /// A locked note is genuinely encrypted; it should appear, marked, not vanish.+ /// Locking is read from Apple's own record type, not inferred from a body that failed+ /// to decode — otherwise our parsing failures would reach the user as "locked", a claim+ /// we could not stand behind.#[tokio::test]- async fn a_locked_note_is_kept_and_flagged() {+ async fn locking_comes_from_apples_own_record() {let server = serve(json!({ "zones": [{"records": [folder_record("Folder/f1", "Notes"),- note_record("Note/n1", "Private", None, "Folder/f1"),+ note_record("Note/n1", "Private", Some("x"), "Folder/f1"),+ { "recordName": "PPN/1", "recordType": "PasswordProtectedNote_UserSpecific",+ "fields": { "Note": { "type": "REFERENCE",+ "value": { "recordName": "Note/n1" } } } }],"syncToken": "t1", "moreComing": false }] })).await;@@ -307,6 +321,35 @@ mod tests {assert_eq!(stored[0].title, "Private", "its title is not secret");}+ /// A body that simply would not decode must NOT be reported as locked.+ #[tokio::test]+ async fn an_undecodable_body_is_not_called_locked() {+ let server = serve(json!({ "zones": [{+ "records": [+ folder_record("Folder/f1", "Notes"),+ note_record("Note/n1", "Odd one", None, "Folder/f1"),+ ],+ "syncToken": "t1", "moreComing": false }] }))+ .await;++ let mut library = Library::in_memory().unwrap();+ sync_cloudkit(+ &reqwest::Client::new(),+ &server.uri(),+ vec![],+ &mut library,+ None,+ )+ .await+ .unwrap();+ let stored = library.notes_in(None).unwrap();+ assert!(+ !stored[0].locked,+ "we must not claim Apple locked something it did not"+ );+ assert!(stored[0].body.is_none());+ }+/// A note pointing at a folder we have never seen must not break the foreign key.#[tokio::test]async fn an_unknown_folder_leaves_the_note_unfiled() {