Repository Public
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