Repository Public
1// SP Notes Core2// File: Sources/SPNotesSync/SyncEngine.swift3// Description: Synchronisation between the local store and the MacLustr backend: pushes local work (creations, edits, tags, files,4// queued actions), pulls the server change feed, merges concurrent edits block by block and records a conflict —5// keeping both copies — when a safe merge is impossible. Local work is never overwritten silently.6// Behaviour, guarantees and limits: docs/SYNC_ENGINE.md.7//8// Author: Simon-Pierre Boucher9// Contact: contact@spboucher.ai10import Foundation11import SPNotesAPI12import SPNotesDocument13import SPNotesStore1415/// Where attachment files live on this device (the apps own the directory; the engine only reads, writes and removes files in it).16public protocol AttachmentFileLocating: Sendable {17 func url(relativePath: String) -> URL18 func relativePath(id: String, filename: String) -> String19 func remove(relativePath: String)20}2122public struct SyncOptions: Sendable {23 /// Pictures and drawing sources up to this size are downloaded as soon as they are known, so notes are complete offline.24 public var autoDownloadLimit: Int64 = 25 << 2025 /// Rows of the web app's databases are not handled by the native apps and are left out of the local store.26 public var includeDatabaseRows = false27 public var feedPageSize = 20028 /// 2.0: the entity kinds read through `GET /api/sync?kinds=` when the server advertises the `entities` feature29 /// (ignored on a 2.x server). Changing the set makes the next cycle read the feed again from 0 (API-NEXT §3: a30 /// cursor is only valid for the kinds it was obtained with). Empty = never ask for entities.31 public var entityKinds: [EntityKind] = EntityKind.all32 /// 2.0: how long the answer of `GET /api/meta` is trusted before it is asked again.33 public var metaMaxAge: TimeInterval = 60034 public init() {}35}3637public struct SyncStatus: Sendable, Equatable {38 public enum Phase: Sendable, Equatable { case idle, syncing, offline, signedOut, failed(String) }39 public var phase: Phase = .idle40 public var lastSuccess: Date?41 /// Notes, files and actions waiting to be sent (notes in conflict included: they wait for a decision).42 public var pending = 043 public var conflicts = 044 /// True when a queued permanent deletion needs a fresh passkey verification.45 public var needsReauth = false46 /// Queued actions this build cannot execute (written by a newer version of the app). They are kept, not counted47 /// in `pending`, and run once a build that knows them starts (2.0).48 public var unsupported = 049 /// 2.0: entity operations (tasks) the server refused for good. They are kept with their payload50 /// (`NotesStore.entityOps(state: .rejected)`) until the user retries or discards them.51 public var rejected = 052 /// 2.0: canvases whose server copy could not be merged automatically; both copies are kept until a decision53 /// (`CanvasRepository.conflict(pageId:)`). Not counted in `conflicts` (page conflicts).54 public var canvasConflicts = 055 public init() {}56}5758/// `.offline` also covers an unreachable server (connection failures, timeouts) and a cycle stopped by `stop()`.59public enum SyncOutcome: Sendable, Equatable { case completed, offline, signedOut, failed(String) }6061public enum ConflictResolution: Sendable { case keepMine, keepTheirs, keepBoth }6263public actor SyncEngine {64 let store: NotesStore65 let api: NotesAPI66 let files: any AttachmentFileLocating67 let options: SyncOptions6869 private var status = SyncStatus()70 private var continuations: [UUID: AsyncStream<SyncStatus>.Continuation] = [:]71 private var scheduled: Task<Void, Never>?72 private var downloading = Set<String>()7374 // One runner task executes the cycles one after the other; every caller of `sync()` waits for a cycle that STARTED after its call.75 private var runner: Task<Void, Never>?76 private var cyclesStarted = 077 private var waiters: [(after: Int, epoch: Int, continuation: CheckedContinuation<SyncOutcome, Never>)] = []78 /// Incremented by `stop()`: tells the callers that were waiting when it was called from those that came after.79 private var stopEpoch = 08081 // State of the cycle in progress.82 /// What the server said it supports (`GET /api/meta`; `.legacy` for a 2.x server), and when it was asked.83 var serverMeta: ServerMeta?84 var serverMetaAt: Date?85 private var serverFailures = 086 private var reauthNeeded = false87 /// Pages whose push was refused in this cycle because the server holds them in its trash.88 private var deferredInTrash = Set<String>()89 /// Pages whose next content push must leave a snapshot of the server copy it replaces in the server history.90 private var snapshotOnPush = Set<String>()91 /// Uploads refused for good by the server (type, size…) are not sent again before this date.92 private var uploadRetryAfter: [String: Date] = [:]9394 static let maxRounds = 495 static let pushBatch = 50096 static let maxServerFailures = 397 static let maxFeedRequests = 20_00098 static let fullCopyKey = "sync.fullCopyPending"99 static let missingFile = "file missing"100101 public init(store: NotesStore, api: NotesAPI, files: any AttachmentFileLocating, options: SyncOptions = SyncOptions()) {102 self.store = store; self.api = api; self.files = files; self.options = options103 }104105 // MARK: status106107 public func currentStatus() -> SyncStatus { status }108109 public func statusUpdates() -> AsyncStream<SyncStatus> {110 let id = UUID()111 return AsyncStream { continuation in112 continuation.yield(status)113 continuations[id] = continuation114 continuation.onTermination = { [weak self] _ in Task { await self?.removeContinuation(id) } }115 }116 }117 private func removeContinuation(_ id: UUID) { continuations[id] = nil }118119 private func publish(_ change: (inout SyncStatus) -> Void) async {120 // The counters are read first: the status is then changed without any suspension in between, so two interleaved121 // calls (the cycle and `refreshCounts()` from the app) can never write back a stale phase.122 let counts = try? await store.counts()123 let ops = try? await store.opCount()124 let parked = (try? await store.parkedOpCount()) ?? 0125 let uploads = try? await store.pendingUploads(limit: 1000).filter { $0.lastError != Self.missingFile }.count126 let entityPending = (try? await store.entityOpCount(state: .pending)) ?? 0127 let entityUnsupported = (try? await store.entityOpCount(state: .unsupported)) ?? 0128 let entityRejected = (try? await store.entityOpCount(state: .rejected)) ?? 0129 let canvasesToPush = (try? await store.canvasesNeedingPush(limit: 1000).count) ?? 0130 let canvasConflicts = (try? await store.canvasConflicts().count) ?? 0131 var next = status132 change(&next)133 if let counts {134 next.pending = counts.pending + max(0, (ops ?? 0) - parked) + (uploads ?? 0) + entityPending + canvasesToPush135 next.unsupported = parked + entityUnsupported136 next.conflicts = counts.conflicts137 next.rejected = entityRejected138 next.canvasConflicts = canvasConflicts139 }140 guard next != status else { return }141 status = next142 for continuation in continuations.values { continuation.yield(next) }143 }144145 /// Refreshes the counters after local edits (no network).146 public func refreshCounts() async { await publish { _ in } }147148 // MARK: entry points149150 /// Runs a full cycle and returns its outcome. A call made while a cycle is running waits for the cycle that follows it (so the151 /// outcome always covers what was in the store when `sync()` was called); any number of such calls share that one extra cycle.152 /// When a cycle does not complete (offline, signed out, failure) every waiting caller gets that outcome and nothing is retried.153 @discardableResult154 public func sync() async -> SyncOutcome {155 let needed = cyclesStarted + 1156 return await withCheckedContinuation { continuation in157 waiters.append((needed, stopEpoch, continuation))158 if runner == nil { runner = Task { await self.runCycles() } }159 }160 }161162 private func runCycles() async {163 while !waiters.isEmpty {164 cyclesStarted += 1165 let number = cyclesStarted166 let outcome = await cycle()167 if Task.isCancelled {168 // Stopped: the callers that were waiting when `stop()` was called are answered; a `sync()` made after it is a new169 // request and gets a new runner (this task is cancelled for good and could not make a single request).170 let epoch = stopEpoch171 let served = waiters.filter { $0.epoch < epoch }172 waiters = waiters.filter { $0.epoch >= epoch }173 for waiter in served { waiter.continuation.resume(returning: outcome == .completed ? .completed : .offline) }174 runner = waiters.isEmpty ? nil : Task { await self.runCycles() }175 return176 }177 // A cycle that did not complete answers everybody: running again at once would fail the same way.178 let served = outcome == .completed ? waiters.filter { $0.after <= number } : waiters179 waiters = outcome == .completed ? waiters.filter { $0.after > number } : []180 for waiter in served { waiter.continuation.resume(returning: outcome) }181 }182 runner = nil183 }184185 /// Requests a cycle after a short quiet period (called after each local edit; successive calls push the deadline back).186 public func schedule(after delay: Duration = .seconds(2)) {187 scheduled?.cancel()188 scheduled = Task { [weak self] in189 try? await Task.sleep(for: delay)190 guard !Task.isCancelled else { return }191 await self?.sync()192 }193 }194195 /// Cancels the scheduled cycle and interrupts the running one (sign-out, app going away). Nothing is lost: whatever was not196 /// acknowledged stays pending and the next `sync()` resumes. Callers waiting in `sync()` get `.offline`.197 public func stop() {198 scheduled?.cancel()199 scheduled = nil200 stopEpoch += 1201 runner?.cancel()202 }203204 // MARK: one cycle205206 private func cycle() async -> SyncOutcome {207 guard await api.client.hasSession else {208 await publish { $0.phase = .signedOut }209 return .signedOut210 }211 await publish { $0.phase = .syncing }212 serverFailures = 0213 deferredInTrash = []214 do {215 try Task.checkCancellation()216 try await store.releaseAllOpLeases()217 // Actions set aside by an older build that this one knows how to run go back in line.218 try await store.unparkOps(kinds: Self.supportedOpKinds)219 try await store.resetTransientAttachmentStates()220 try await refreshServerMeta()221 // What a round merged locally (or could not fit in one batch) is pushed by the next one; the number of rounds is bounded.222 var round = 0223 while true {224 round += 1225 let morePush = try await push()226 let merged = try await pull()227 // A note the server holds in its trash while this device, fully up to date, shows it live (it was restored here228 // together with a folder it had been moved into, which the server does not know yet): the next round restores it.229 var liveHere = false230 for id in deferredInTrash where !liveHere {231 if let page = try await store.page(id: id), page.deletedAt == nil { liveHere = true }232 }233 guard morePush || merged || liveHere, round < Self.maxRounds else { break }234 }235 await downloadWanted()236 let reauth = reauthNeeded237 await publish { $0.phase = .idle; $0.lastSuccess = Date(); $0.needsReauth = reauth }238 return .completed239 } catch {240 // Uploads interrupted half-way go back to "waiting" at once rather than at the next cycle.241 try? await store.resetTransientAttachmentStates()242 let reauth = reauthNeeded243 if error is CancellationError || (error as? APIError)?.isCancelled == true {244 await publish { $0.phase = .idle; $0.needsReauth = reauth }245 return .offline246 }247 if let api = error as? APIError {248 if api.isUnauthenticated {249 await publish { $0.phase = .signedOut; $0.needsReauth = reauth }250 return .signedOut251 }252 switch api {253 case .offline, .transport, .timeout:254 await publish { $0.phase = .offline; $0.needsReauth = reauth }255 return .offline256 default: break257 }258 }259 let message = Self.describe(error)260 await publish { $0.phase = .failed(message); $0.needsReauth = reauth }261 return .failed(message)262 }263 }264265 /// Errors that stop the whole cycle: no session, no network, an unreachable or overloaded server, a closed store, a cancellation.266 /// Anything else concerns one item only: it is recorded on the item and the cycle goes on with the next one.267 func stopsCycle(_ error: Error) -> Bool {268 if error is CancellationError || error is SyncFailure { return true }269 if let store = error as? StoreError, store == .closed { return true }270 guard let api = error as? APIError else { return false }271 switch api {272 case .offline, .cancelled, .transport, .timeout: return true273 default: break274 }275 if api.isUnauthenticated || api.isRateLimited { return true }276 if api.isRetryable {277 // 5xx: one bad note must not block the others, but a server that keeps failing is left alone.278 serverFailures += 1279 return serverFailures >= Self.maxServerFailures280 }281 return false282 }283284 /// The item cannot be pushed now and that is not an error (it is retried by a later cycle).285 private enum Deferral: Error { case inServerTrash, parentNotCreated }286287 /// A server that does not follow the contract (the cycle fails instead of looping).288 struct SyncFailure: Error, CustomStringConvertible { var description: String }289290 // MARK: push291292 /// Returns true when another round is useful (a divergence was merged locally, the batch was full, a restore unblocked a note).293 private func push() async throws -> Bool {294 var again = false295 var waitingForRestore = false296 let pending = try await store.pagesNeedingPush(limit: Self.pushBatch)297 if pending.count >= Self.pushBatch { again = true }298299 // 1. creations first (parents before children), so that files and children have something to attach to300 for item in pending where item.page.needsCreate {301 do {302 try await requireParentOnServer(item.page)303 if try await create(item.page) { again = true }304 } catch {305 if try await pushFailed(item.page.id, error) { waitingForRestore = true }306 }307 }308 // 2. files (a page must exist on the server before a file can be attached to it)309 try await uploadPending()310 // 3. edits of existing pages311 for item in pending where !item.page.needsCreate {312 do {313 if try await pushChanges(item.page) { again = true }314 } catch {315 if try await pushFailed(item.page.id, error) { waitingForRestore = true }316 }317 }318 // 4. queued actions and reminders319 let restored = try await runQueue()320 try await pushReminders()321 // 5. (2.0) the entity outbox — tasks — and the canvases, when the server has them322 try await pushEntityOps()323 if try await pushCanvases() { again = true }324 // A note that waited because it was in the server's trash can go now that its restore went through.325 if waitingForRestore, restored { again = true }326 return again327 }328329 /// Sorts out the failure of one page: rethrows what stops the cycle, records the rest on the page. Returns true when the page330 /// only waits for the server's trash to give it back.331 private func pushFailed(_ id: String, _ error: Error) async throws -> Bool {332 if let deferral = error as? Deferral {333 if deferral == .inServerTrash { deferredInTrash.insert(id) }334 return deferral == .inServerTrash335 }336 if stopsCycle(error) { throw error }337 try? await store.markPushFailed(id: id, error: Self.describe(error))338 return false339 }340341 /// A page whose parent is still waiting for its own creation is not sent: the server would silently file it at the top level.342 private func requireParentOnServer(_ page: PageRecord) async throws {343 guard let parentId = page.parentId, let parent = try await store.page(id: parentId), parent.needsCreate else { return }344 throw Deferral.parentNotCreated345 }346347 private static func serverCopy(_ page: Page) -> ServerCopy {348 ServerCopy(version: page.version, title: page.title, content: page.content.data, properties: page.properties.data, updatedAt: page.updatedAt)349 }350351 private static func serverCopy(_ conflict: PageConflict) -> ServerCopy {352 ServerCopy(version: conflict.version, title: conflict.title, content: conflict.content.data, properties: conflict.properties.data, updatedAt: conflict.updatedAt)353 }354355 /// Creates the page under its local id. Returns true when a divergence was merged locally.356 ///357 /// No idempotency key on purpose: the client-chosen id already makes the request safe to repeat, whereas a key would make the358 /// server replay the stored answer of the FIRST attempt (old content, or a page purged since) as if it were current.359 /// Whatever the server says about the id, the returned row is compared with the local one: the answer may describe an earlier360 /// attempt of this device (answer lost, note edited since) or a page somebody else changed.361 private func create(_ page: PageRecord) async throws -> Bool {362 let draft = PageDraft(id: page.id, title: page.title, parentId: page.parentId, section: PageSection(rawValue: page.section), type: PageType(rawValue: page.type),363 content: RawJSON(data: page.content), icon: page.icon, properties: RawJSON(data: page.properties),364 inboxAt: page.inboxAt, captureKind: page.captureKind) // a capture made offline stays a capture on the server365 // Remembered on disk: if the answer is lost, version 1 carrying this exact text is this device's own copy.366 try await rememberSent(page, asVersion: 1)367 let created = try await api.createPage(draft)368 let server = created.value369 if server.deletedAt != nil, created.existing {370 // The id is in the server's trash: the server refuses every write there. The local work waits (restore, or purge → re-creation).371 try await leaveServerTrash(page)372 }373 let sameContent = Self.sameJSON(server.content.data, page.content)374 // The server gives ids to the blocks that had none: that is its normalisation of what was sent, not a difference.375 let normalised = !sameContent && Self.sameIgnoringBlockIds(server.content.data, page.content)376 let same = Self.sameTitle(server.title, page.title) && (sameContent || normalised) && Self.sameJSON(server.properties.data, page.properties)377378 // What a creation cannot carry (flags, cover, order) and what differs on a row that already existed. Not version-guarded.379 var meta = PagePatch()380 if page.pinned != server.pinned { meta.pinned = page.pinned }381 if page.archived != server.archived { meta.archived = page.archived }382 if page.cover != server.cover { meta.cover = PatchValue(page.cover) }383 if page.position != server.position { meta.position = page.position }384 if page.icon != server.icon { meta.icon = PatchValue(page.icon) }385 if page.section != server.section { meta.section = PageSection(rawValue: page.section) }386 if page.parentId != server.parentId { meta.parentId = PatchValue(page.parentId) }387 if !meta.isEmpty { _ = try await api.patchPage(id: page.id, meta) }388 if !page.tags.isEmpty || page.tagsDirty { _ = try await api.setPageTags(pageID: page.id, tags: page.tags) }389390 guard same else {391 // The stored text is not the local one. Either it is what this device sent earlier (recognised by `reconcile`: the local392 // text then goes on top of it in the next round), or somebody else wrote it: a divergence without a common ancestor,393 // recorded as a conflict — never an overwrite.394 return try await reconcile(pageId: page.id, server: Self.serverCopy(server), baseOverride: .some(nil), force: true)395 }396 do {397 try await store.markPushed(id: page.id, serverVersion: server.version, updatedAt: server.updatedAt, pushedEditSeq: page.editSeq,398 pushed: PushedCopy(title: page.title, content: page.content, properties: page.properties),399 serverContent: normalised ? server.content.data : nil)400 try? await store.setMeta(Self.sentKey(page.id), nil)401 } catch StoreError.notFound {402 // Purged on this device while the creation was in flight: the server copy must not come back as a live note.403 try? await store.setMeta(Self.sentKey(page.id), nil)404 _ = try? await api.trashPage(id: page.id)405 _ = try? await store.enqueueOp(kind: OpKind.purge, targetId: page.id)406 }407 return false408 }409410 /// Pushes the pending changes of a page the server knows. Returns true when a divergence was merged locally.411 private func pushChanges(_ page: PageRecord) async throws -> Bool {412 do {413 return try await sendChanges(page)414 } catch let error as APIError where error.isNotFound {415 return try await handleMissing(page, error: error)416 }417 }418419 private func sendChanges(_ page: PageRecord) async throws -> Bool {420 // meta fields are not version-guarded: they always apply421 if !page.dirtyMeta.isEmpty {422 var meta = PagePatch()423 for field in page.dirtyMeta {424 switch field {425 case .parentId:426 try await requireParentOnServer(page)427 meta.parentId = PatchValue(page.parentId)428 case .section: meta.section = PageSection(rawValue: page.section)429 case .position: meta.position = page.position430 case .pinned: meta.pinned = page.pinned431 case .archived: meta.archived = page.archived432 case .icon: meta.icon = PatchValue(page.icon)433 case .cover: meta.cover = PatchValue(page.cover)434 case .inboxAt: break // leaving the inbox is a queued triage action435 }436 }437 if !meta.isEmpty { _ = try await api.patchPage(id: page.id, meta) }438 }439 if page.tagsDirty { _ = try await api.setPageTags(pageID: page.id, tags: page.tags) }440 var version = page.serverVersion441 var updatedAt = page.updatedAt442 var pushed: PushedCopy?443 if page.dirtyContent {444 var patch = PagePatch(title: page.title, content: RawJSON(data: page.content), properties: RawJSON(data: page.properties))445 patch.baseVersion = page.serverVersion446 if snapshotOnPush.contains(page.id) { patch.versionReason = "sync · copy replaced by a device" }447 // Remembered (on disk) until the answer arrives: if the answer is lost, the server copy that carries this exact text at448 // the next version is recognised as this device's own write, not as somebody else's change.449 try await rememberSent(page, asVersion: page.serverVersion + 1)450 do {451 let result = try await api.patchPage(id: page.id, patch)452 version = result.version; updatedAt = result.updatedAt453 pushed = PushedCopy(title: page.title, content: page.content, properties: page.properties)454 snapshotOnPush.remove(page.id)455 try? await store.setMeta(Self.sentKey(page.id), nil)456 } catch let error as APIError where error.isConflict {457 guard let server = error.serverCopy else { throw error }458 // The tags and flags above went through (sending them again is harmless); only the guarded fields are in question.459 return try await reconcile(pageId: page.id, server: Self.serverCopy(server), force: true)460 }461 }462 do {463 try await store.markPushed(id: page.id, serverVersion: version, updatedAt: updatedAt, pushedEditSeq: page.editSeq, pushed: pushed)464 } catch StoreError.notFound {465 // Purged on this device during the push: the store queued the permanent deletion, there is nothing to acknowledge.466 }467 return false468 }469470 /// Notes on disk the text about to be sent, and the version it will be on the server. Several attempts against the same version (answers471 /// lost more than once, with typing in between) are all remembered: any of them may be the one the server applied.472 private func rememberSent(_ page: PageRecord, asVersion version: Int) async throws {473 let target = String(version)474 let print = Self.fingerprint(title: page.title, content: page.content, properties: page.properties)475 var prints: [Substring] = []476 if let existing = try await store.meta(Self.sentKey(page.id)) {477 let parts = existing.split(separator: ":")478 if parts.count == 2, parts[0] == target { prints = Array(parts[1].split(separator: ",").suffix(7)) }479 }480 guard !prints.contains(Substring(print)) || prints.isEmpty else { return }481 try await store.setMeta(Self.sentKey(page.id), target + ":" + (prints.map(String.init) + [print]).joined(separator: ","))482 }483484 /// The server answered 404 to a write on a page this device holds: it is in the server's trash (writes are refused there) or it485 /// was purged.486 private func handleMissing(_ page: PageRecord, error: APIError) async throws -> Bool {487 let head: PageHead488 do { head = try await api.pageHead(id: page.id) } catch let missing as APIError where missing.isNotFound {489 if page.dirtyContent {490 // Purged on the server while this device holds text the server never saw: created again under the same id.491 return try await create(page)492 }493 // Only flags, tags or a move were waiting: the permanent deletion wins (the feed's tombstone then removes the local row).494 try? await store.markPushed(id: page.id, serverVersion: page.serverVersion, updatedAt: page.updatedAt, pushedEditSeq: page.editSeq)495 return false496 }497 guard head.deletedAt != nil else { throw error }498 try await leaveServerTrash(page)499 return try await sendChanges(page)500 }501502 /// The server holds the page in its trash. Normally the local work waits (`Deferral`): the feed read later in the cycle puts the503 /// note in the trash here too, and the user decides. But when the feed has been read since and the note is still live on this504 /// device, the two sides will never agree by themselves: what the user sees wins and the note is restored on the server.505 private func leaveServerTrash(_ page: PageRecord) async throws {506 guard deferredInTrash.contains(page.id), page.deletedAt == nil else { throw Deferral.inServerTrash }507 _ = try await api.restorePage(id: page.id)508 deferredInTrash.remove(page.id)509 }510511 /// Local edits meet another server copy. Identical → adopt; mergeable block by block → merge and keep it to push; otherwise a512 /// conflict is recorded: the local copy stays as it is on the device, the server copy is stored beside it, the user decides.513 /// The local row is read again here, so the decision is always made on what the user sees now, not on what was read before a514 /// network call. Returns true when the device now holds something new to push.515 ///516 /// - Parameters:517 /// - baseOverride: `.some(nil)` = there is no common ancestor (a page never acknowledged); default = the stored base copy.518 /// - force: the server refused a write (409) or returned the row itself; without it only a strictly newer server version counts.519 private func reconcile(pageId: String, server: ServerCopy, baseOverride: PageBase?? = nil, force: Bool = false) async throws -> Bool {520 guard let page = try await store.page(id: pageId) else { return false }521 // A clean page has nothing to reconcile (for instance a conflict settled by the user while the feed was being read).522 guard page.dirtyContent, force || server.version > page.serverVersion else { return false }523 let base: PageBase?524 if let baseOverride { base = baseOverride } else { base = try await store.pageBase(id: pageId) }525526 if Self.sameTitle(server.title, page.title), Self.sameJSON(server.content, page.content), Self.sameJSON(server.properties, page.properties) {527 // The server already holds this text (a push whose answer was lost).528 try? await store.setMeta(Self.sentKey(pageId), nil)529 try await store.resolveConflictUsingCopy(id: pageId, copy: Self.contentCopy(title: server.title, content: server.content, properties: server.properties),530 version: server.version, updatedAt: server.updatedAt)531 return false532 }533 if let sent = try await store.meta(Self.sentKey(pageId)) {534 try? await store.setMeta(Self.sentKey(pageId), nil)535 let parts = sent.split(separator: ":")536 if parts.count == 2, parts[0] == String(server.version),537 parts[1].split(separator: ",").contains(Substring(Self.fingerprint(title: server.title, content: server.content, properties: server.properties))) {538 // The server copy is a text this device sent before the answer was lost; what was typed since simply comes on top.539 try await store.resolveConflictKeepingLocal(id: pageId, server: server)540 return true541 }542 }543 if !page.needsCreate, server.version < page.serverVersion {544 // The server went back in time (database restored): its copy is an ancestor of the local one, which is sent again on top545 // of it. No block merge here — "their changes" would be the loss itself.546 snapshotOnPush.insert(pageId)547 try await store.resolveConflictKeepingLocal(id: pageId, server: server)548 return true549 }550 if let base, let merged = Self.merge(base: base, mine: page, theirs: server) {551 if Self.sameTitle(merged.title, server.title), Self.sameJSON(merged.content, server.content), Self.sameJSON(merged.properties, server.properties) {552 try await store.resolveConflictUsingCopy(id: pageId, copy: Self.contentCopy(title: server.title, content: server.content, properties: server.properties),553 version: server.version, updatedAt: server.updatedAt)554 return false555 }556 try await store.resolveConflictKeepingLocal(id: pageId, server: server, merged: merged)557 return true558 }559 try await store.recordConflict(pageId: pageId, server: server)560 return false561 }562563 private func uploadPending() async throws {564 for attachment in try await store.pendingUploads(limit: 100) {565 guard let path = attachment.localPath, FileManager.default.fileExists(atPath: files.url(relativePath: path).path) else {566 // Recorded once; the row stays (the app may put the file back) and never blocks the others.567 if attachment.lastError != Self.missingFile { try? await store.markAttachmentFailed(id: attachment.id, error: Self.missingFile) }568 continue569 }570 if let wait = uploadRetryAfter[attachment.id], wait > Date() { continue }571 // The page of the file must exist on the server first.572 var pageExists = false573 if let pageId = attachment.pageId, let page = try await store.page(id: pageId) {574 if page.needsCreate { continue }575 pageExists = true576 }577 do {578 try await store.markAttachmentUploading(id: attachment.id)579 let uploaded = try await api.uploadAttachment(fileURL: files.url(relativePath: path), id: attachment.id, pageID: pageExists ? attachment.pageId : nil,580 filename: attachment.filename, mimeType: attachment.mime)581 try await store.markAttachmentUploaded(id: attachment.id, size: uploaded.value.size, pageCount: uploaded.value.pages)582 uploadRetryAfter[attachment.id] = nil583 } catch {584 // An interruption is not a failure of the file: its row goes back to "waiting" (see `cycle`).585 if stopsCycle(error) { throw error }586 if case StoreError.notFound = error { continue } // removed on this device meanwhile587 try? await store.markAttachmentFailed(id: attachment.id, error: Self.describe(error))588 if let api = error as? APIError, let status = api.status, (400..<500).contains(status) {589 // Refused for what it is (type, size): sending 200 MB again at every cycle would be pointless.590 uploadRetryAfter[attachment.id] = Date().addingTimeInterval(NotesStore.backoffDelay(attempts: attachment.uploadAttempts + 1))591 }592 }593 }594 }595596 /// The queue kinds `runQueue` executes. Any other kind is parked, never dropped.597 public static let supportedOpKinds: Set<String> = [OpKind.trash, OpKind.restore, OpKind.purge, OpKind.deleteAttachment, OpKind.triage]598599 static func unsupportedOpReason(_ kind: String) -> String { "unsupported op kind: \(kind)" }600601 /// Runs the queued actions. Returns true when a restore went through.602 private func runQueue() async throws -> Bool {603 var needsReauth = false604 var restored = false605 defer { reauthNeeded = needsReauth }606 for op in try await store.nextOps(limit: 100) {607 do {608 // An action on a page the server does not have yet waits for its creation (it would be acknowledged for nothing).609 if [OpKind.trash, OpKind.restore, OpKind.triage].contains(op.kind), let id = op.targetId, let page = try await store.page(id: id), page.needsCreate {610 try await store.releaseOp(id: op.id)611 continue612 }613 switch op.kind {614 case OpKind.trash:615 if let id = op.targetId { _ = try await api.trashPage(id: id, idempotencyKey: op.idempotencyKey) }616 case OpKind.restore:617 if let id = op.targetId { _ = try await api.restorePage(id: id, idempotencyKey: op.idempotencyKey); restored = true }618 case OpKind.purge:619 if let id = op.targetId { _ = try await api.purgePage(id: id) }620 case OpKind.deleteAttachment:621 if let id = op.targetId { _ = try await api.deleteAttachment(id: id, idempotencyKey: op.idempotencyKey) }622 case OpKind.triage:623 if let id = op.targetId, let payload = op.payload, let action = try? JSONDecoder().decode(QueuedTriage.self, from: payload) {624 _ = try await api.triageInboxItem(id: id, action.inboxAction, idempotencyKey: op.idempotencyKey)625 }626 default:627 // An action this build cannot execute (written by a newer version of the app): it is set aside and628 // surfaced (`SyncStatus.unsupported`, `NotesStore.parkedOps()`), never dropped, and does not block the queue.629 try await store.parkOp(id: op.id, reason: Self.unsupportedOpReason(op.kind))630 continue631 }632 try await store.completeOp(id: op.id)633 } catch let error as APIError where error.isNotFound || error.status == 409 && error.code == "not_in_inbox" {634 try await store.completeOp(id: op.id) // already gone on the server: the action has nothing left to do635 } catch let error as APIError where error.needsReauth {636 // Not a failed attempt: the action stays first in line and goes as soon as the user has confirmed with the passkey.637 needsReauth = true638 try? await store.releaseOp(id: op.id)639 } catch {640 if stopsCycle(error) {641 try? await store.releaseOp(id: op.id)642 throw error643 }644 _ = try? await store.failOp(id: op.id, error: Self.describe(error))645 }646 }647 return restored648 }649650 private func pushReminders() async throws {651 for reminder in try await store.dirtyReminders() {652 do {653 if reminder.deleted {654 if let taskId = reminder.serverTaskId { do { _ = try await api.deleteTask(id: taskId) } catch let error as APIError where error.isNotFound {} }655 try await store.markReminderSynced(id: reminder.id, serverTaskId: nil, pushedEditSeq: reminder.editSeq)656 continue657 }658 if let taskId = reminder.serverTaskId {659 do {660 _ = try await api.updateTask(TaskPatch(id: taskId, title: reminder.title, dueAt: PatchValue(reminder.dueAt), status: reminder.done ? .done : .todo))661 try await store.markReminderSynced(id: reminder.id, serverTaskId: taskId, pushedEditSeq: reminder.editSeq)662 continue663 } catch let error as APIError where error.isNotFound {664 // The task was deleted on the server; the reminder edited here is the newer intention: it is created again below.665 }666 }667 // the page of a reminder must exist on the server668 if let pageId = reminder.pageId, let page = try await store.page(id: pageId), page.needsCreate { continue }669 // Tasks have no client-chosen id: the key is what prevents a duplicate after a lost answer. A replayed answer describes670 // the FIRST attempt, so the returned task is compared with the reminder and the difference is sent.671 let key = "spn-task-" + reminder.id + (reminder.serverTaskId == nil ? "" : "-r" + String(reminder.editSeq))672 let task = try await api.createTask(TaskDraft(title: reminder.title, dueAt: reminder.dueAt, pageId: reminder.pageId), idempotencyKey: key)673 var taskId = task.id674 if task.title != reminder.title || !Self.sameInstant(task.dueAt, reminder.dueAt) || task.isDone != reminder.done {675 let patch = TaskPatch(id: task.id, title: reminder.title, dueAt: PatchValue(reminder.dueAt), status: reminder.done ? .done : .todo)676 do { _ = try await api.updateTask(patch) } catch let error as APIError where error.isNotFound {677 // The replayed answer described a task deleted since: a really new one is created (another key).678 let fresh = try await api.createTask(TaskDraft(title: reminder.title, dueAt: reminder.dueAt, pageId: reminder.pageId), idempotencyKey: key + "-n" + String(reminder.editSeq))679 taskId = fresh.id680 if reminder.done { _ = try await api.updateTask(TaskPatch(id: fresh.id, status: .done)) }681 }682 }683 try await store.markReminderSynced(id: reminder.id, serverTaskId: taskId, pushedEditSeq: reminder.editSeq)684 } catch {685 if stopsCycle(error) { throw error }686 }687 }688 }689690 // MARK: pull691692 /// Reads the change feed to its end. Returns true when a divergence was merged locally (there is something new to push).693 private func pull() async throws -> Bool {694 var cursor = try await store.syncCursor()695 // After a server reset only a COMPLETE copy tells which pages the server no longer has: an interrupted one starts again.696 var afterReset = try await store.meta(Self.fullCopyKey) != nil697 if afterReset, cursor != 0 {698 try await store.setSyncCursor(0)699 cursor = 0700 }701 // (2.0) The entity kinds asked with the feed. A cursor is only valid for the set of kinds it was obtained with: when the702 // set changes (first run of 2.0 against a 3.0 server, a server that gains or loses the feature) the feed is read from 0.703 let kinds = feedKinds()704 let kindsKey = kinds.joined(separator: ",")705 if (try await store.meta(Self.kindsKey) ?? "") != kindsKey {706 if cursor != 0 {707 try await store.setSyncCursor(0)708 cursor = 0709 }710 try await store.setMeta(Self.kindsKey, kindsKey.isEmpty ? nil : kindsKey)711 }712 var fullCopyIDs: Set<String>? = cursor == 0 ? [] : nil713 var fullCopyEntities: [EntityKind: Set<String>]? = cursor == 0 && !kinds.isEmpty ? [:] : nil714 var mergedSomething = false715 var requests = 0716 var resets = 0717 while true {718 try Task.checkCancellation()719 requests += 1720 guard requests <= Self.maxFeedRequests else { throw SyncFailure(description: "The change feed does not end.") }721 let feed = kinds.isEmpty ? try await api.sync(since: cursor, limit: options.feedPageSize)722 : try await api.sync(since: cursor, limit: options.feedPageSize, kinds: kinds)723 if feed.reset {724 // The server database was restored to an earlier state: read everything again; local work is kept.725 resets += 1726 guard resets <= 2, cursor != 0 else { throw SyncFailure(description: "The server keeps asking for a full copy.") }727 try await store.setMeta(Self.fullCopyKey, "1")728 try await store.resetSyncState()729 if !kinds.isEmpty { try await store.resetEntitySync() }730 afterReset = true731 cursor = 0732 fullCopyIDs = []733 fullCopyEntities = kinds.isEmpty ? nil : [:]734 continue735 }736 guard feed.cursor >= cursor, !feed.more || feed.cursor > cursor else { throw SyncFailure(description: "The change feed does not advance.") }737 let pages = feed.pages.filter { options.includeDatabaseRows || $0.databaseId == nil }.map(Self.remotePage)738 let attachments = feed.attachments.map { RemoteAttachment(id: $0.id, pageId: $0.pageId, filename: $0.filename, mime: $0.mime, size: $0.size, sha256: $0.sha256, pageCount: $0.pageCount, createdAt: $0.createdAt, deletedAt: $0.deletedAt, rev: $0.rev) }739 let tombstones = feed.tombstones.compactMap { stone -> SPNotesStore.Tombstone? in740 guard let kind = SPNotesStore.Tombstone.Kind(rawValue: stone.kind) else { return nil }741 return SPNotesStore.Tombstone(id: stone.id, kind: kind)742 }743 // (2.0) Entities first: their rows are skipped by revision when a window is applied twice, so a crash between the two744 // transactions (the cursor moves with the pages) only replays this one.745 if !kinds.isEmpty, try await applyEntityWindow(feed, kinds: kinds, collecting: &fullCopyEntities) { mergedSomething = true }746 let summary = try await store.applyRemote(pages: pages, attachments: attachments, tombstones: tombstones,747 tags: feed.tags.map { RemoteTag(name: $0.name, color: $0.color) }, cursor: feed.cursor)748 fullCopyIDs?.formUnion(pages.map(\.id))749 for path in summary.orphanedFiles { files.remove(relativePath: path) }750 // A file deleted on the server (soft delete: the row stays, flagged) leaves the device too.751 for id in summary.changedAttachmentIds {752 guard let record = try await store.attachment(id: id), record.deletedAt != nil, record.uploaded, let path = record.localPath else { continue }753 files.remove(relativePath: path)754 try? await store.markAttachmentEvicted(id: id)755 }756 for diverged in summary.diverged {757 let remote = diverged.remote758 let server = ServerCopy(version: remote.version, title: remote.title, content: remote.content, properties: remote.properties, updatedAt: remote.updatedAt)759 if try await reconcile(pageId: diverged.id, server: server) { mergedSomething = true }760 }761 if afterReset {762 // A restored server may hold an OLDER version of a note this device has in a newer, already acknowledged state:763 // the local state is the one to keep, so it is queued to be sent again on top of the restored copy.764 for remote in pages {765 guard let local = try await store.page(id: remote.id), !local.needsCreate, !local.dirtyContent, local.serverVersion > remote.version else { continue }766 let server = ServerCopy(version: remote.version, title: remote.title, content: remote.content, properties: remote.properties, updatedAt: remote.updatedAt)767 if Self.sameTitle(local.title, remote.title), Self.sameJSON(local.content, remote.content), Self.sameJSON(local.properties, remote.properties) {768 try await store.resolveConflictUsingCopy(id: local.id, copy: Self.contentCopy(title: remote.title, content: remote.content, properties: remote.properties),769 version: remote.version, updatedAt: remote.updatedAt)770 } else {771 snapshotOnPush.insert(local.id)772 try await store.resolveConflictKeepingLocal(id: local.id, server: server)773 mergedSomething = true774 }775 }776 }777 if try await store.meta("workspace.name") != feed.workspace.name { try await store.setMeta("workspace.name", feed.workspace.name) }778 if let name = feed.user.displayName, try await store.meta("user.displayName") != name { try await store.setMeta("user.displayName", name) }779 cursor = feed.cursor780 if !feed.more { break }781 }782 if let ids = fullCopyIDs {783 if afterReset {784 // A restored server has lost what was created after its backup: the notes this device still holds are given back785 // to it. (Deleting them here would destroy what may be the only copy.)786 try await recreateMissing(notIn: ids)787 } else {788 // After a complete copy, synced pages the server no longer has were purged while this device was away.789 let removed = try await store.removeSyncedPages(notIn: ids)790 for path in removed.orphanedFiles { files.remove(relativePath: path) }791 // Same rule for the entities: clean rows absent from a complete copy were deleted while this device was away.792 if let seen = fullCopyEntities {793 for kind in kinds where kind != SyncKind.canvas {794 try await store.removeSyncedEntities(kind: EntityKind(kind), notIn: seen[EntityKind(kind)] ?? [])795 }796 }797 }798 }799 if afterReset { try await store.setMeta(Self.fullCopyKey, nil) }800 return mergedSomething801 }802803 /// After a server reset: creates again, under their ids, the synced pages of this device that the restored server does not have.804 private func recreateMissing(notIn ids: Set<String>) async throws {805 var missing: [String: PageRecord] = [:]806 for list in [SmartList.all, .archived, .trash] {807 var offset = 0808 while true {809 let batch = try await store.summaries(list: list, limit: 500, offset: offset)810 for summary in batch where summary.syncState == .synced && !ids.contains(summary.id) {811 if let page = try await store.page(id: summary.id), !page.isDirty, page.serverVersion > 0 { missing[page.id] = page }812 }813 if batch.count < 500 { break }814 offset += 500815 }816 }817 func depth(_ page: PageRecord) -> Int {818 var depth = 0819 var parent = page.parentId820 while let id = parent, let next = missing[id], depth < 256 { depth += 1; parent = next.parentId }821 return depth822 }823 for page in missing.values.sorted(by: { (depth($0), $0.createdAt) < (depth($1), $1.createdAt) }) {824 do {825 let draft = PageDraft(id: page.id, title: page.title, parentId: page.parentId, section: PageSection(rawValue: page.section), type: PageType(rawValue: page.type),826 content: RawJSON(data: page.content), icon: page.icon, properties: RawJSON(data: page.properties),827 inboxAt: page.inboxAt, captureKind: page.captureKind) // a capture made offline stays a capture on the server828 let created = try await api.createPage(draft)829 guard !created.existing else { continue } // it came back meanwhile: the feed will say how830 var meta = PagePatch()831 if page.pinned { meta.pinned = true }832 if page.archived { meta.archived = true }833 if let cover = page.cover { meta.cover = .value(cover) }834 if page.position != created.value.position { meta.position = page.position }835 if !meta.isEmpty { _ = try await api.patchPage(id: page.id, meta) }836 if !page.tags.isEmpty { _ = try await api.setPageTags(pageID: page.id, tags: page.tags) }837 if page.deletedAt != nil { _ = try await api.trashPage(id: page.id) }838 // The local row is now based on the version the server just assigned.839 if let current = try await store.page(id: page.id), !current.dirtyContent {840 try await store.resolveConflictUsingCopy(id: page.id, copy: Self.contentCopy(title: current.title, content: current.content, properties: current.properties),841 version: created.value.version, updatedAt: created.value.updatedAt)842 }843 } catch {844 if stopsCycle(error) { throw error }845 }846 }847 }848849 // MARK: attachments850851 /// Downloads one attachment now (opening a file that is not on the device yet). Returns its local URL.852 /// Throws `APIError.cancelled` when the same file is already being downloaded by another call.853 @discardableResult854 public func download(attachmentId: String) async throws -> URL {855 guard let record = try await store.attachment(id: attachmentId) else { throw StoreError.notFound("attachment \(attachmentId)") }856 if let path = record.localPath, FileManager.default.fileExists(atPath: files.url(relativePath: path).path) { return files.url(relativePath: path) }857 guard !downloading.contains(attachmentId) else { throw APIError.cancelled }858 downloading.insert(attachmentId)859 defer { downloading.remove(attachmentId) }860 let relative = files.relativePath(id: record.id, filename: record.filename)861 let destination = files.url(relativePath: relative)862 try FileManager.default.createDirectory(at: destination.deletingLastPathComponent(), withIntermediateDirectories: true)863 try await store.markAttachmentDownloading(id: attachmentId)864 do {865 _ = try await api.downloadFile(id: attachmentId, to: destination)866 } catch {867 try? await store.markAttachmentFailed(id: attachmentId, error: Self.describe(error))868 throw error869 }870 do {871 try await store.markAttachmentDownloaded(id: attachmentId, localPath: relative)872 } catch {873 // The row disappeared during the download (deleted on the server): the file must not stay behind.874 files.remove(relativePath: relative)875 throw error876 }877 return destination878 }879880 /// Pictures and drawing sources that notes need to be complete offline.881 private func downloadWanted() async {882 guard let wanted = try? await store.attachmentsWantedOffline(maxSize: options.autoDownloadLimit, limit: 40) else { return }883 for record in wanted where !downloading.contains(record.id) {884 do { try await download(attachmentId: record.id) } catch { if stopsCycle(error) { return } }885 }886 }887888 // MARK: conflicts decided by the user889890 /// Settles a recorded conflict. Needs the network: the server keeps both copies in its history whatever the choice.891 /// Returns the id of the copy created by `keepBoth`. Throws the `APIError` of the server; on `409 conflict` (the note moved892 /// again while the user was deciding) the newer server copy has been recorded: show it and ask again.893 @discardableResult894 public func resolveConflict(pageId: String, choice: ConflictResolution) async throws -> String? {895 guard let conflict = try await store.conflict(pageId: pageId), let page = try await store.page(id: pageId) else { return nil }896 let mine = ConflictMine(title: page.title, content: RawJSON(data: page.content))897 let apiChoice: ConflictChoice = switch choice { case .keepMine: .mine; case .keepTheirs: .theirs; case .keepBoth: .both }898 // The key covers exactly this decision on exactly this text: a retry after a lost answer is replayed (no second "conflict899 // copy"), a decision on a text edited since is a new request.900 let key = "spn-res-\(pageId)-\(conflict.server.version)-\(apiChoice.rawValue)-\(Self.fingerprint(Data(page.title.utf8) + [0] + page.content))"901 do {902 let resolved = try await api.resolveConflict(pageID: pageId, choice: apiChoice, serverVersion: conflict.server.version, mine: mine, idempotencyKey: key)903 let server = ServerCopy(version: resolved.version, title: resolved.title, content: resolved.content.data, properties: resolved.properties.data, updatedAt: resolved.updatedAt)904 let current = try await store.page(id: pageId)905 let editedMeanwhile = current.map { $0.editSeq != page.editSeq } ?? false906 if choice == .keepMine, editedMeanwhile || !Self.sameJSON(page.properties, server.properties) {907 // "Mine" on the server is the title and the text; the local properties (favourite, folder…) and whatever was typed908 // during the request stay on the device and go with the next push, on top of the version just written.909 try await store.resolveConflictKeepingLocal(id: pageId, server: server)910 } else {911 // The replaced local text (if any) is kept as a local version by the store.912 try await store.resolveConflictUsingCopy(id: pageId, copy: Self.contentCopy(title: server.title, content: server.content, properties: server.properties),913 version: server.version, updatedAt: server.updatedAt)914 }915 schedule(after: .milliseconds(200))916 return resolved.copyId917 } catch let error as APIError where error.isConflict {918 // The page moved again while the user was deciding: show the new server copy instead of guessing.919 if let copy = error.serverCopy {920 let server = Self.serverCopy(copy)921 if Self.sameTitle(server.title, page.title), Self.sameJSON(server.content, page.content), Self.sameJSON(server.properties, page.properties) {922 // …unless the server now holds exactly the local text: there is nothing left to decide.923 try await store.resolveConflictUsingCopy(id: pageId, copy: Self.contentCopy(title: server.title, content: server.content, properties: server.properties),924 version: server.version, updatedAt: server.updatedAt)925 return nil926 }927 try await store.recordConflict(pageId: pageId, server: server)928 }929 throw error930 }931 }932933 // MARK: helpers934935 static func describe(_ error: Error) -> String { (error as? APIError)?.message ?? String(describing: error) }936937 static func remotePage(_ page: Page) -> RemotePage {938 let digest = ContentDigest(content: page.content.data)939 return RemotePage(id: page.id, parentId: page.parentId, databaseId: page.databaseId, type: page.type, section: page.section, title: page.title, icon: page.icon, cover: page.cover,940 content: page.content.data, properties: page.properties.data, position: page.position, pinned: page.pinned, archived: page.archived, version: page.version,941 wordCount: digest.wordCount, createdAt: page.createdAt, updatedAt: page.updatedAt, lastOpenedAt: page.lastOpenedAt, deletedAt: page.deletedAt, inboxAt: page.inboxAt,942 captureKind: page.captureKind, rev: page.rev ?? 0, tags: page.tags ?? [], plainText: digest.plainText, preview: digest.preview)943 }944945 static func contentCopy(title: String, content: Data, properties: Data) -> ContentCopy {946 let digest = ContentDigest(content: content)947 return ContentCopy(title: title, content: content, properties: properties, plainText: digest.plainText, wordCount: digest.wordCount, preview: digest.preview)948 }949950 /// Key-order independent JSON equality (what the server compares with).951 static func sameJSON(_ a: Data, _ b: Data) -> Bool {952 if a == b { return true }953 guard let x = try? JSONValue(data: a), let y = try? JSONValue(data: b) else { return false }954 return x.semanticallyEquals(y)955 }956957 /// A document without its block ids (an `attrs` left empty counts as no `attrs`).958 static func withoutBlockIds(_ value: JSONValue) -> JSONValue {959 switch value {960 case .array(let items): return .array(items.map(withoutBlockIds))961 case .object(var object):962 if case .object(var attrs)? = object["attrs"] {963 attrs["id"] = nil964 object["attrs"] = attrs.isEmpty ? nil : .object(attrs)965 }966 return .object(object.mapValues(withoutBlockIds))967 default: return value968 }969 }970971 /// Equality of two documents once the block ids are left out.972 static func sameIgnoringBlockIds(_ a: Data, _ b: Data) -> Bool {973 guard let x = try? JSONValue(data: a), let y = try? JSONValue(data: b) else { return false }974 return withoutBlockIds(x).semanticallyEquals(withoutBlockIds(y))975 }976977 /// The server trims titles and stores an empty one as "Untitled": two titles it would store identically are the same title.978 static func storedTitle(_ title: String) -> String {979 let trimmed = title.trimmingCharacters(in: .whitespacesAndNewlines)980 return trimmed.isEmpty ? "Untitled" : trimmed981 }982983 static func sameTitle(_ a: String, _ b: String) -> Bool { a == b || storedTitle(a) == storedTitle(b) }984985 static func sameInstant(_ a: Date?, _ b: Date?) -> Bool {986 switch (a, b) {987 case (nil, nil): return true988 case (let x?, let y?): return abs(x.timeIntervalSince(y)) < 0.002989 default: return false990 }991 }992993 static func sentKey(_ pageId: String) -> String { "sync.sent." + pageId }994 /// Store meta: the `kinds` parameter the stored cursor was obtained with ("" / absent = none, the 2.x feed).995 static let kindsKey = "sync.kinds"996997 /// Fingerprint of the version-guarded fields as the server stores them (title trimmed, JSON in canonical form).998 static func fingerprint(title: String, content: Data, properties: Data) -> String {999 func canonical(_ data: Data, strippingIds: Bool) -> Data {1000 guard let value = try? JSONValue(data: data) else { return data }1001 return (strippingIds ? withoutBlockIds(value) : value).canonicalData()1002 }1003 // Block ids are left out: the server adds the missing ones, and that must not hide a text this device sent.1004 return fingerprint(Data(storedTitle(title).utf8) + [0] + canonical(content, strippingIds: true) + [0] + canonical(properties, strippingIds: false))1005 }10061007 /// FNV-1a (64 bit) of some bytes, in hexadecimal: a stable fingerprint for idempotency keys.1008 static func fingerprint(_ data: Data) -> String {1009 var hash: UInt64 = 0xcbf29ce4842223251010 for byte in data { hash = (hash ^ UInt64(byte)) &* 0x100000001b3 }1011 return String(hash, radix: 16)1012 }10131014 /// Three-way merge of the version-guarded fields. Nil when the two sides changed the same thing differently.1015 static func merge(base: PageBase, mine: PageRecord, theirs: ServerCopy) -> ContentCopy? {1016 // title1017 let title: String1018 if sameTitle(mine.title, theirs.title) || sameTitle(theirs.title, base.title) { title = mine.title }1019 else if sameTitle(mine.title, base.title) { title = theirs.title }1020 else { return nil }1021 // content, block by block1022 let content: Data1023 if sameJSON(mine.content, theirs.content) || sameJSON(theirs.content, base.content) { content = mine.content }1024 else if sameJSON(mine.content, base.content) { content = theirs.content }1025 else {1026 guard let b = try? NoteDocument(json: base.content), let m = try? NoteDocument(json: mine.content), let t = try? NoteDocument(json: theirs.content),1027 case .merged(var merged) = NoteDocument.merge(base: b, mine: m, theirs: t) else { return nil }1028 merged.ensureBlockIds()1029 guard let data = try? merged.jsonData() else { return nil }1030 content = data1031 }1032 // properties, key by key1033 guard let properties = mergeObjects(base: base.properties, mine: mine.properties, theirs: theirs.properties) else { return nil }1034 return contentCopy(title: title, content: content, properties: properties)1035 }10361037 static func mergeObjects(base: Data, mine: Data, theirs: Data) -> Data? {1038 if sameJSON(mine, theirs) || sameJSON(theirs, base) { return mine }1039 if sameJSON(mine, base) { return theirs }1040 guard case .object(let b)? = try? JSONValue(data: base), case .object(let m)? = try? JSONValue(data: mine), case .object(let t)? = try? JSONValue(data: theirs) else { return nil }1041 var out: [String: JSONValue] = [:]1042 for key in Set(b.keys).union(m.keys).union(t.keys) {1043 let bv = b[key], mv = m[key], tv = t[key]1044 let value: JSONValue?1045 if mv == tv || tv == bv { value = mv } else if mv == bv { value = tv } else { return nil }1046 if let value { out[key] = value }1047 }1048 return JSONValue.object(out).canonicalData()1049 }1050}10511052/// Plain text, word count and preview of a stored document (what lists and the search index need).1053public struct ContentDigest: Sendable {1054 public let plainText: String1055 public let wordCount: Int1056 public let preview: String10571058 public init(content: Data) {1059 // An unreadable document (never produced by the apps or the server) simply has no text.1060 self.init(document: (try? NoteDocument(json: content)) ?? NoteDocument())1061 }1062 public init(document: NoteDocument) {1063 plainText = document.plainText()1064 wordCount = document.wordCount1065 preview = document.preview(maxLength: 180)1066 }1067}10681069/// Payload of a queued inbox triage action.1070public struct QueuedTriage: Codable, Sendable {1071 public var action: String1072 public var section: String?1073 public var parentId: String?1074 public init(action: String, section: String? = nil, parentId: String? = nil) { self.action = action; self.section = section; self.parentId = parentId }10751076 var inboxAction: InboxAction {1077 switch action {1078 case "archive": return .archive1079 case "trash": return .trash1080 default: return .keep(section: section.flatMap(PageSection.init(rawValue:)), parentId: parentId.map { .value($0) })1081 }1082 }1083}1084