SPB Git

Repository Public

VQSyncEngine.swift 26.8 KB 559 lines swift

1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Sources/VQuantKit/Sync/VQSyncEngine.swift3// Description: The sync engine: a persistent local replica of the object store, an ordered offline write queue, the4//              conflict policy of CONTRACT §1.2, and the consumption of the sync stream.5import Foundation67/// One engine per signed-in person and device.8///9/// **Model.** `replica` is the last state the server told us (tombstones included); `queue` is the ordered list of10/// writes of this device the server has not accepted yet; the **local view** an app reads is the replica with the11/// queue applied on top. A write is durable (in the queue file) before `put`/`delete` return, so the UI can show it12/// at once and a crash loses nothing.13///14/// **Determinism.** The engine does nothing by itself unless `start()` is called: `pull()` and `flush()` are plain15/// async calls, time is the injected clock. With `Configuration.autoFlush == false` a test decides every step.16public actor VQSyncEngine {17    public struct Configuration: Sendable {18        /// Entries asked per page of the change feed (≤ 1000).19        public var pageSize = 50020        /// Restrict the replica to some kinds (nil = everything, including kinds this version does not know).21        public var kinds: [VQObjectKind]?22        /// Flush after each local write and retry transient failures with back-off. Turn off in tests.23        public var autoFlush = true24        public var backoff = VQBackoff()25        /// How the non-list part of an object is reconciled (`.object` = the contract's last-writer-wins).26        public var granularity = VQMergeGranularity.object27        /// Kinds that are always reconciled whole-object, whatever `granularity` says: a workspace's layout and panels28        /// describe one arrangement and must never be mixed from two versions. Only matters with `.field`.29        public var wholeObjectKinds: Set<VQObjectKind> = [.workspace]30        /// Times one write is re-based on a newer server state before the flush gives up until the next round.31        public var maxMergeAttempts = 632        /// Conflict records kept (oldest dropped first).33        public var maxConflictRecords = 20034        public init() {}35    }3637    private let store: VQObjectStoreClient38    private let storage: any VQSyncStorage39    private let clock: any VQClock40    public let configuration: Configuration4142    private var replica: [VQObjectKey: VQObjectEnvelope] = [:]43    private var queue: [VQPendingWrite] = []44    private var cursor = 045    private var nextOp = 146    private var nextConflict = 147    private var conflictRecords: [VQConflictRecord] = []48    private var loaded = false4950    private var state = VQSyncStatus()51    private var inFlightOp: Int?52    /// This device's id as the server names it (`device` of the envelopes of our accepted writes).53    private var ownDevice: String?54    private var flushing = false55    private var pulling = false56    private var pullAgain = false57    private var flushRetryAttempt = 058    private var flushRetryTask: Task<Void, Never>?59    private var streamTask: Task<Void, Never>?60    private var eventSinks: [UUID: AsyncStream<VQSyncEvent>.Continuation] = [:]61    private var hintSinks: [UUID: AsyncStream<VQSyncHint>.Continuation] = [:]6263    public init(client: VQClient, storage: any VQSyncStorage, clock: any VQClock = VQSystemClock(), configuration: Configuration = Configuration()) {64        self.store = VQObjectStoreClient(client: client); self.storage = storage; self.clock = clock; self.configuration = configuration65    }6667    public init(transport: any VQTransport, storage: any VQSyncStorage, clock: any VQClock = VQSystemClock(), configuration: Configuration = Configuration()) {68        self.init(client: VQClient(transport: transport), storage: storage, clock: clock, configuration: configuration)69    }7071    // MARK: lifecycle7273    /// Reads the replica, the queue and the conflict records from storage. Idempotent; called by every entry point.74    /// A blob that cannot be read (corrupted, wrong key) is skipped: the replica is a cache of the server and is75    /// rebuilt by the next pull — except the queue, whose loss is reported by throwing.76    public func load() throws {77        guard !loaded else { return }78        if let d = try? storage.read("meta.json"), let j = try? VQJSON.parse(d) {79            cursor = j.int("cursor") ?? 080            nextConflict = j.int("nextConflict") ?? 181        }82        var complete = true83        for name in (try? storage.list(prefix: "objects/")) ?? [] {84            guard let d = try? storage.read(name), let j = try? VQJSON.parse(d) else { complete = false; continue }85            let e = VQObjectEnvelope(json: j)86            guard !e.id.isEmpty else { complete = false; continue }87            replica[e.key] = e88        }89        if !complete { cursor = 0 }     // something was unreadable: ask the feed again from the start90        if let d = try? storage.read("conflicts.json"), let j = try? VQJSON.parse(d) {91            conflictRecords = (j.arrayValue ?? []).map(VQConflictRecord.init(json:))92        }93        if let d = try storage.read("queue.json") {94            let j = try VQJSON.parse(d)95            queue = j.list("ops").map(VQPendingWrite.init(json:)).sorted { $0.opId < $1.opId }96            nextOp = max(j.int("nextOp") ?? 1, (queue.last?.opId ?? 0) + 1)97        }98        loaded = true99        refreshStatus(emit: false)100    }101102    /// Loads, then keeps the replica current: opens the sync stream (reconnecting with back-off), pulls on `hello`103    /// and on every `change`, replays the queue. Returns at once; follow `status` / `events()`.104    public func start() {105        try? load()106        guard streamTask == nil else { return }107        streamTask = Task { [weak self] in await self?.runStream() }108    }109110    public func stop() {111        streamTask?.cancel(); streamTask = nil112        flushRetryTask?.cancel(); flushRetryTask = nil113        setConnection(.stopped)114    }115116    /// One round: replay the queue, then pull. Throws the pull's error (the queue keeps what could not be sent).117    public func syncNow() async throws {118        await flush()119        try await pull()120    }121122    // MARK: reading the local view123124    public var status: VQSyncStatus { state }125    public var pendingWrites: [VQPendingWrite] { queue }126    public var conflicts: [VQConflictRecord] { conflictRecords }127128    /// Live objects of a kind as this device sees them (pending writes applied), newest first.129    public func objects(_ kind: VQObjectKind) -> [VQObjectEnvelope] {130        try? load()131        var keys = Set(replica.keys.filter { $0.kind == kind })132        for op in queue where op.key.kind == kind { keys.insert(op.key) }133        return keys.compactMap { view($0) }.filter { !$0.deleted }134            .sorted { ($0.updatedAt, $0.id) > ($1.updatedAt, $1.id) }135    }136137    public func object(_ kind: VQObjectKind, _ id: String) -> VQObjectEnvelope? {138        try? load()139        guard let e = view(VQObjectKey(kind: kind, id: id)), !e.deleted else { return nil }140        return e141    }142143    public func objects<T: VQSyncData>(of type: T.Type = T.self) -> [VQObject<T>] { objects(T.kind).map(VQObject<T>.init(envelope:)) }144    public func object<T: VQSyncData>(_ type: T.Type = T.self, id: String) -> VQObject<T>? { object(T.kind, id).map(VQObject<T>.init(envelope:)) }145146    /// Ids of a kind that have a write waiting for the server.147    public func pendingIDs(_ kind: VQObjectKind) -> Set<String> { Set(queue.filter { $0.key.kind == kind }.map(\.key.id)) }148149    /// The last state the server confirmed (tombstones included) — for diagnostics and tests.150    public func confirmed(_ kind: VQObjectKind, _ id: String) -> VQObjectEnvelope? { replica[VQObjectKey(kind: kind, id: id)] }151152    private func view(_ key: VQObjectKey) -> VQObjectEnvelope? {153        let confirmed = replica[key]154        guard let op = queue.last(where: { $0.key == key }) else { return confirmed }155        let created = confirmed.flatMap { $0.deleted ? nil : $0.createdAt } ?? op.createdAt156        switch op.action {157        case .put(let data):158            return VQObjectEnvelope(kind: key.kind, id: key.id, rev: confirmed?.rev ?? 0, seq: confirmed?.seq ?? 0, createdAt: created,159                                    updatedAt: op.createdAt, deleted: false, device: "local", data: data)160        case .delete:161            return VQObjectEnvelope(kind: key.kind, id: key.id, rev: confirmed?.rev ?? 0, seq: confirmed?.seq ?? 0, createdAt: created,162                                    updatedAt: op.createdAt, deleted: true, device: "local", data: .object([:]))163        }164    }165166    // MARK: writing167168    /// Saves `data` as object `kind/id` (creating it when it does not exist). Returns the local view of the object.169    /// The write is queued durably before this returns; it reaches the server at the next flush.170    /// Throws without queuing for what the server would refuse anyway: a bad id, a server-only kind, data over 256 KB.171    @discardableResult172    public func put(_ kind: VQObjectKind, _ id: String, data: VQJSON) throws -> VQObjectEnvelope {173        try load()174        guard VQObjectID.isValid(id) else { throw VQError(.rejected, status: 400, message: "Invalid object id.") }175        guard !kind.isServerOnly else { throw VQError(.forbidden, status: 403, message: "Objects of kind \(kind) are written by the server only.") }176        guard data.objectValue != nil else { throw VQError(.rejected, status: 400, message: "data must be a JSON object.") }177        guard data.data().count <= VQObjectStoreClient.maxDataBytes else { throw VQError(.tooLarge, status: 413, message: "This object is larger than 256 KB.") }178        let key = VQObjectKey(kind: kind, id: id)179        let current = view(key)180        let base = current.flatMap { $0.deleted ? nil : $0.data }181        if base == data, let current { return current }182        if let last = queue.last, last.key == key, last.opId != inFlightOp, case .put = last.action {183            queue[queue.count - 1].action = .put(data)          // typing: keep one write per burst, same place in the order184            queue[queue.count - 1].createdAt = clock.now()185        } else {186            queue.append(VQPendingWrite(opId: nextOp, key: key, action: .put(data), base: base, createdAt: clock.now()))187            nextOp += 1188        }189        try persistQueue()190        changed([kind])191        scheduleFlush()192        return view(key)!193    }194195    @discardableResult196    public func put<T: VQSyncData>(_ data: T, id: String) throws -> VQObject<T> {197        VQObject(envelope: try put(T.kind, id, data: data.json))198    }199200    /// Deletes the object (a tombstone on the server: its content and archived versions are erased there).201    public func delete(_ kind: VQObjectKind, _ id: String) throws {202        try load()203        let key = VQObjectKey(kind: kind, id: id)204        guard let current = view(key), !current.deleted else { return }205        if replica[key] == nil || replica[key]?.deleted == true, !queue.contains(where: { $0.key == key && $0.opId == inFlightOp }) {206            // never reached the server: forget the pending creation instead of creating then deleting207            queue.removeAll { $0.key == key }208        } else {209            queue.append(VQPendingWrite(opId: nextOp, key: key, action: .delete, base: current.data, createdAt: clock.now()))210            nextOp += 1211        }212        try persistQueue()213        changed([kind])214        scheduleFlush()215    }216217    // MARK: conflicts218219    public func dismissConflict(_ id: String) {220        conflictRecords.removeAll { $0.id == id }221        try? persistConflicts()222        refreshStatus()223    }224225    public func dismissAllConflicts() {226        conflictRecords.removeAll()227        try? persistConflicts()228        refreshStatus()229    }230231    /// Writes the server's version of a conflict back (the person chose "keep theirs"), then dismisses the record.232    public func restoreRemoteVersion(ofConflict id: String) throws {233        guard let record = conflictRecords.first(where: { $0.id == id }) else { return }234        if let remote = record.remote { try put(record.key.kind, record.key.id, data: remote) }235        dismissConflict(id)236    }237238    // MARK: observation239240    /// Changes of the local view, of the status, and new conflicts. Each call returns an independent stream.241    public func events() -> AsyncStream<VQSyncEvent> {242        let id = UUID()243        let (stream, continuation) = AsyncStream<VQSyncEvent>.makeStream()244        eventSinks[id] = continuation245        continuation.onTermination = { [weak self] _ in Task { await self?.removeEventSink(id) } }246        return stream247    }248249    /// `hint` events of the sync stream: a conversation, an analysis or a quant job changed — refresh that list.250    public func hints() -> AsyncStream<VQSyncHint> {251        let id = UUID()252        let (stream, continuation) = AsyncStream<VQSyncHint>.makeStream()253        hintSinks[id] = continuation254        continuation.onTermination = { [weak self] _ in Task { await self?.removeHintSink(id) } }255        return stream256    }257258    private func removeEventSink(_ id: UUID) { eventSinks[id] = nil }259    private func removeHintSink(_ id: UUID) { hintSinks[id] = nil }260    private func emit(_ event: VQSyncEvent) { for sink in eventSinks.values { sink.yield(event) } }261    private func changed(_ kinds: Set<VQObjectKind>) {262        refreshStatus()263        if !kinds.isEmpty { emit(.objectsChanged(kinds)) }264    }265266    private func refreshStatus(emit shouldEmit: Bool = true) {267        var s = state268        s.pendingWrites = queue.count269        s.cursor = cursor270        s.conflictsNeedingAttention = conflictRecords.filter(\.needsAttention).count271        guard s != state else { return }272        state = s273        if shouldEmit { emit(.statusChanged(s)) }274    }275276    private func setConnection(_ c: VQSyncStatus.Connection, error: String? = nil) {277        var s = state278        s.connection = c279        if let error { s.lastError = error } else if c == .connected { s.lastError = nil }280        guard s != state else { return }281        state = s282        emit(.statusChanged(s))283    }284285    // MARK: pull286287    /// Brings the replica up to date from the change feed (by `since`, page by page). Safe to call at any time;288    /// overlapping calls are folded into one more round.289    public func pull() async throws {290        try load()291        if pulling { pullAgain = true; return }292        pulling = true293        defer { pulling = false }294        repeat {295            pullAgain = false296            var since = cursor297            while true {298                let page = try await store.changes(since: since, kinds: configuration.kinds, limit: configuration.pageSize)299                var touched = Set<VQObjectKind>()300                for e in page.changes where apply(e) { touched.insert(e.kind) }301                // The cursor is the top-level seq once `more` is false; in between, the seq of the last entry received.302                let next = page.more ? (page.changes.last?.seq ?? page.seq) : page.seq303                if next != cursor { cursor = next; persistMeta() }304                state.lastPulledAt = clock.now()305                changed(touched)306                if !page.more || page.changes.isEmpty { break }307                since = next308            }309        } while pullAgain310    }311312    /// Takes a server envelope into the replica when it is news. Returns whether the replica changed.313    @discardableResult314    private func apply(_ e: VQObjectEnvelope) -> Bool {315        guard !e.id.isEmpty, !e.kind.rawValue.isEmpty else { return false }316        if let have = replica[e.key], have.seq > e.seq || have == e { return false }317        replica[e.key] = e318        try? storage.write(Self.objectName(e.key), e.json.data())319        return true320    }321322    // MARK: flush (offline queue replay)323324    /// Sends the queued writes in the order they were made. Stops at the first transient failure (offline, 429, 5xx)325    /// and keeps the rest; resolves conflicts as the contract prescribes. Never throws: follow `status`.326    public func flush() async {327        guard (try? load()) != nil else { return }328        guard !flushing else { return }329        flushing = true330        defer { flushing = false; inFlightOp = nil }331        while let op = queue.first {332            inFlightOp = op.opId333            let step = await send(op)334            inFlightOp = nil335            switch step {336            case .done:337                queue.removeAll { $0.opId == op.opId }338                try? persistQueue()339                flushRetryAttempt = 0340                changed([op.key.kind])341            case .later(let delay, let message):342                state.lastError = message343                refreshStatus()344                emit(.statusChanged(state))345                scheduleFlushRetry(after: delay)346                return347            case .locked:348                setConnection(.locked, error: "This device is no longer signed in.")349                return350            }351        }352        refreshStatus()353    }354355    private enum Step { case done, later(TimeInterval?, String), locked }356357    private func send(_ op: VQPendingWrite) async -> Step {358        let key = op.key359        var attempts = 0360        while true {361            attempts += 1362            if attempts > configuration.maxMergeAttempts { return .later(nil, "The object keeps changing on the server.") }363            let current = replica[key]364            let live = current.flatMap { $0.deleted ? nil : $0 }365            do {366                switch op.action {367                case .put(let local):368                    if let live, live.data == local { return .done }                 // already there (replay after a crash, or an echo)369                    var body = local370                    var outcome: VQMergeOutcome?371                    if let live, live.data != op.base {372                        let o = VQMerge.merge(kind: key.kind, base: op.base, local: local, remote: live.data, granularity: configuration.wholeObjectKinds.contains(key.kind) ? .object : configuration.granularity)373                        outcome = o; body = o.merged374                        if body == live.data { record(op, outcome: o, remote: live, result: body); return .done }375                    }376                    let accepted = try await store.put(key.kind, key.id, data: body, baseRev: live?.rev ?? 0)377                    apply(accepted)378                    advanceCursor(with: accepted)379                    if let outcome, let live { record(op, outcome: outcome, remote: live, result: body) }380                    else if let current, current.deleted, op.base != nil {381                        note(VQConflictRecord(id: "", key: key, at: clock.now(), resolution: .recreated, needsAttention: true, local: local, remote: nil, result: body,382                                              remoteRev: current.rev, remoteDevice: current.device))383                    }384                    return .done385                case .delete:386                    guard let live else { return .done }                              // already gone387                    let accepted = try await store.delete(key.kind, key.id, baseRev: live.rev)388                    apply(accepted)389                    advanceCursor(with: accepted)390                    if let base = op.base, base != live.data {391                        note(VQConflictRecord(id: "", key: key, at: clock.now(), resolution: .localDeleteWon, needsAttention: true, local: nil, remote: live.data, result: nil,392                                              remoteRev: live.rev, remoteDevice: live.device))393                    }394                    return .done395                }396            } catch let e as VQError {397                switch e.kind {398                case .conflict:399                    // The server is ahead of the replica: take its state and decide again (merge, or nothing left to do).400                    guard let stored = VQObjectStoreClient.current(of: e) else { return .later(nil, e.message) }401                    replica[key] = stored402                    try? storage.write(Self.objectName(key), stored.json.data())403                    continue404                case .notFound:405                    // The server never had (or no longer knows) what the replica holds: forget it and decide again.406                    if replica[key] == nil { if case .delete = op.action { return .done }; return reject(op, e) }407                    replica[key] = nil408                    try? storage.remove(Self.objectName(key))409                    continue410                case .unauthorized:411                    return e.isLocked ? .locked : .later(nil, e.message)412                case .network, .rateLimited, .server, .unavailable, .decoding:413                    return .later(e.retryAfter, e.message)414                case .rejected, .forbidden, .tooLarge:415                    return reject(op, e)416                }417            } catch {418                return .later(nil, String(describing: error))419            }420        }421    }422423    /// A write the server will never accept: drop it (the local view falls back to the server's state) and say so.424    private func reject(_ op: VQPendingWrite, _ e: VQError) -> Step {425        var local: VQJSON?426        if case .put(let d) = op.action { local = d }427        let current = replica[op.key]428        note(VQConflictRecord(id: "", key: op.key, at: clock.now(), resolution: .rejected, needsAttention: true, local: local,429                              remote: current.flatMap { $0.deleted ? nil : $0.data }, result: nil, remoteRev: current?.rev ?? 0, remoteDevice: current?.device ?? "",430                              message: e.message))431        return .done432    }433434    private func record(_ op: VQPendingWrite, outcome: VQMergeOutcome, remote: VQObjectEnvelope, result: VQJSON) {435        guard case .put(let local) = op.action else { return }436        let lost = !outcome.overwrittenKeys.isEmpty437        guard lost || !outcome.mergedLists.isEmpty else { return }438        note(VQConflictRecord(id: "", key: op.key, at: clock.now(), resolution: lost ? .localWon : .mergedElements, needsAttention: lost, local: local,439                              remote: remote.data, result: result, remoteRev: remote.rev, remoteDevice: remote.device,440                              differingKeys: outcome.overwrittenKeys, mergedLists: outcome.mergedLists))441    }442443    private func note(_ record: VQConflictRecord) {444        var r = record445        r.id = "c\(nextConflict)"446        nextConflict += 1447        conflictRecords.append(r)448        if conflictRecords.count > configuration.maxConflictRecords { conflictRecords.removeFirst(conflictRecords.count - configuration.maxConflictRecords) }449        try? persistConflicts()450        persistMeta()451        refreshStatus()452        emit(.conflict(r))453    }454455    /// Our own accepted write is the next entry of the feed when its seq follows the cursor: no need to pull it back.456    private func advanceCursor(with accepted: VQObjectEnvelope) {457        if !accepted.device.isEmpty { ownDevice = accepted.device }458        if accepted.seq == cursor + 1 { cursor = accepted.seq; persistMeta() }459    }460461    private func scheduleFlush() {462        guard configuration.autoFlush else { return }463        Task { await self.flush() }464    }465466    private func scheduleFlushRetry(after delay: TimeInterval?) {467        guard configuration.autoFlush, flushRetryTask == nil else { return }468        let wait = delay ?? configuration.backoff.delay(attempt: flushRetryAttempt)469        flushRetryAttempt += 1470        let clock = self.clock471        flushRetryTask = Task { [weak self] in472            do { try await clock.sleep(seconds: wait) } catch { return }473            await self?.retryFlush()474        }475    }476477    private func retryFlush() async {478        flushRetryTask = nil479        await flush()480    }481482    // MARK: stream483484    private func runStream() async {485        var attempt = 0486        while !Task.isCancelled {487            setConnection(.connecting)488            var retryAfter: TimeInterval?489            var failure: String?490            do {491                let events = try await store.stream()492                for try await event in events {493                    switch event {494                    case .hello(let seq):495                        attempt = 0496                        setConnection(.connected)497                        await flush()498                        if seq != cursor || state.lastPulledAt == nil { try? await pull() }499                    case .change(let n):500                        let key = VQObjectKey(kind: n.kind, id: n.id)501                        if let have = replica[key], have.seq == n.seq {502                            if n.seq == cursor + 1 { cursor = n.seq; persistMeta(); refreshStatus() }   // our own write, already applied503                        } else if n.device == ownDevice, inFlightOp != nil, queue.first?.key == key {504                            break                                                                       // our own write, its answer is on its way505                        } else if n.seq > cursor {506                            try? await pull()507                        }508                    case .hint(let hint):509                        for sink in hintSinks.values { sink.yield(hint) }510                    case .other:511                        break512                    }513                }514                failure = "The sync stream ended."515            } catch is CancellationError {516                return517            } catch let e as VQError {518                if e.isLocked { setConnection(.locked, error: e.message); return }519                retryAfter = e.retryAfter520                failure = e.message521            } catch {522                failure = String(describing: error)523            }524            if Task.isCancelled { return }525            let delay = retryAfter ?? configuration.backoff.delay(attempt: attempt)526            attempt += 1527            setConnection(.reconnecting(attempt: attempt, retryIn: delay), error: failure)528            do { try await clock.sleep(seconds: delay) } catch { return }529        }530    }531532    // MARK: persistence533534    static func objectName(_ key: VQObjectKey) -> String { "objects/\(key.kind.rawValue)/\(key.id).json" }535536    private func persistQueue() throws {537        let j: VQJSON = ["nextOp": .number(Double(nextOp)), "ops": .array(queue.map(\.json))]538        try storage.write("queue.json", j.data())539    }540    private func persistMeta() {541        let j: VQJSON = ["schema": 1, "cursor": .number(Double(cursor)), "nextConflict": .number(Double(nextConflict))]542        try? storage.write("meta.json", j.data())543    }544    private func persistConflicts() throws {545        try storage.write("conflicts.json", VQJSON.array(conflictRecords.map(\.json)).data())546    }547548    /// Forgets everything stored for this person on this device (sign-out). Pending writes are lost.549    public func reset() {550        stop()551        for name in (try? storage.list(prefix: "")) ?? [] { try? storage.remove(name) }552        replica = [:]; queue = []; cursor = 0; conflictRecords = []; nextOp = 1; nextConflict = 1553        loaded = true554        state = VQSyncStatus()555        emit(.objectsChanged(Set(VQObjectKind.known)))556        emit(.statusChanged(state))557    }558}559
Files main
Menu

Theme