SPB Git

Repository Public

SyncEngine.swift 64.1 KB 1,084 lines swift

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
Files main
Menu

Theme