Repository Public
1import Foundation2import Testing3@testable import VQuantKit4import VQuantKitTesting56private func wl(_ name: String, _ symbols: [String], extra: VQJSONObject = [:]) -> VQJSON {7 var o: VQJSONObject = ["name": .string(name), "symbols": VQJSON(symbols)]8 for (k, v) in extra { o[k] = v }9 return .object(o)10}11private func note(_ title: String, _ body: String) -> VQJSON { ["title": .string(title), "body": .string(body)] }1213@Suite struct SyncEnginePullTests {14 @Test func pullsByPagesAndKeepsTheCursor() async throws {15 let server = VQFakeServer()16 let web = server.transport(device: "web")17 let store = VQObjectStoreClient(transport: web)18 for i in 1...5 { _ = try await store.put(.watchlist, "w\(i)", data: wl("W\(i)", ["S\(i)"]), baseRev: 0) }19 let (engine, _, _) = makeEngine(server, device: "A") { $0.pageSize = 2 }20 try await engine.pull()21 #expect(server.requestCount(.get, pathPrefix: "/api/v2/sync/changes") == 3) // 2 + 2 + 122 let sinces = server.requests.filter { $0.request.path == "/api/v2/sync/changes" }.map { $0.request.query.first { $0.name == "since" }!.value }23 #expect(sinces == ["0", "2", "4"]) // since = seq of the last entry received24 #expect(await engine.status.cursor == 5)25 #expect(await engine.objects(.watchlist).map(\.id) == ["w5", "w4", "w3", "w2", "w1"]) // newest first2627 _ = try await store.put(.watchlist, "w2", data: wl("W2b", ["S2", "X"]), baseRev: 1)28 try await engine.pull()29 let last = server.requests.last { $0.request.path == "/api/v2/sync/changes" }!.request30 #expect(last.query.first { $0.name == "since" }?.value == "5")31 #expect(await engine.object(.watchlist, "w2")?.rev == 2)32 #expect(await engine.status.cursor == 6)33 try await engine.pull() // nothing new: one request, no change34 #expect(await engine.status.cursor == 6)35 }3637 @Test func tombstonesRemoveObjectsAndAllowRecreation() async throws {38 let server = VQFakeServer()39 let store = VQObjectStoreClient(transport: server.transport(device: "web"))40 _ = try await store.put(.note, "n1", data: note("t", "b"), baseRev: 0)41 let (engine, _, _) = makeEngine(server, device: "A")42 try await engine.pull()43 #expect(await engine.object(.note, "n1") != nil)44 let tomb = try await store.delete(.note, "n1", baseRev: 1)45 #expect(tomb.deleted && tomb.rev == 2 && tomb.data == .object([:]))46 try await engine.pull()47 #expect(await engine.object(.note, "n1") == nil)48 #expect(await engine.objects(.note).isEmpty)49 #expect(await engine.confirmed(.note, "n1")?.deleted == true) // the marker stays in the replica50 // re-created over the tombstone with baseRev 0: the revision count continues51 try await engine.put(.note, "n1", data: note("again", "b2"))52 await engine.flush()53 #expect(server.stored(.note, "n1")?.rev == 3 && server.stored(.note, "n1")?.deleted == false)54 #expect(await engine.conflicts.isEmpty)55 #expect(await engine.status.pendingWrites == 0)56 }5758 @Test func replicatesKindsItDoesNotKnow() async throws {59 let server = VQFakeServer()60 server.kinds.insert("auto_research")61 server.serverWrite("auto_research", "r1", data: ["goal": "watch AAPL", "cycle": 3])62 let (engine, _, _) = makeEngine(server, device: "A")63 try await engine.pull()64 #expect(await engine.objects("auto_research").first?.data["cycle"] == .number(3))65 #expect(await engine.objects("auto_research").first?.device == "server")66 }6768 @Test func kindFilterIsSentToTheFeed() async throws {69 let server = VQFakeServer()70 server.serverWrite(.note, "n", data: note("t", "b"))71 server.serverWrite(.watchlist, "w", data: wl("W", []))72 let (engine, _, _) = makeEngine(server, device: "A") { $0.kinds = [.note] }73 try await engine.pull()74 #expect(await engine.objects(.note).count == 1)75 #expect(await engine.objects(.watchlist).isEmpty)76 }77}7879@Suite struct SyncEngineWriteTests {80 @Test func aLocalWriteShowsAtOnceThenIsAccepted() async throws {81 let server = VQFakeServer()82 let (engine, _, _) = makeEngine(server, device: "A")83 let local = try await engine.put(.watchlist, "w1", data: wl("Tech", ["AAPL"]))84 #expect(local.rev == 0 && local.device == "local")85 #expect(await engine.objects(.watchlist).count == 1)86 #expect(await engine.pendingIDs(.watchlist) == ["w1"])87 #expect(server.stored(.watchlist, "w1") == nil)88 await engine.flush()89 #expect(server.stored(.watchlist, "w1")?.rev == 1 && server.stored(.watchlist, "w1")?.device == "A")90 #expect(await engine.object(.watchlist, "w1")?.rev == 1)91 #expect(await engine.status.pendingWrites == 0)92 #expect(await engine.status.cursor == 1) // our own write: no pull needed93 // an identical save is not a write94 try await engine.put(.watchlist, "w1", data: wl("Tech", ["AAPL"]))95 #expect(await engine.status.pendingWrites == 0)96 }9798 @Test func unknownKeysReachTheServerThroughATypedEdit() async throws {99 let server = VQFakeServer()100 server.serverWrite(.watchlist, "w1", data: wl("Tech", ["AAPL"], extra: ["kitFutureField": ["a": [1, 2, ["b": .null]]], "note": .null]))101 let (engine, _, _) = makeEngine(server, device: "A")102 try await engine.pull()103 var w = try #require(await engine.object(VQWatchlist.self, id: "w1")).data104 w.add("MSFT")105 try await engine.put(w, id: "w1")106 await engine.flush()107 let stored = try #require(server.stored(.watchlist, "w1"))108 #expect(stored.rev == 2 && stored.data["symbols"] == ["AAPL", "MSFT"])109 #expect(stored.data["kitFutureField"] == ["a": [1, 2, ["b": .null]]] && stored.data["note"] == .null)110 }111112 @Test func refusesBeforeQueuingWhatTheServerWouldRefuse() async throws {113 let server = VQFakeServer()114 let (engine, _, _) = makeEngine(server, device: "A")115 func kind(_ body: () async throws -> Void) async -> VQError.Kind? { do { try await body(); return nil } catch { return (error as? VQError)?.kind } }116 #expect(await kind { try await engine.put(.note, "bad id", data: note("t", "b")) } == .rejected)117 #expect(await kind { try await engine.put(.review, "r1", data: ["status": "done"]) } == .forbidden)118 #expect(await kind { try await engine.put(.note, "big", data: note("t", String(repeating: "x", count: 300_000))) } == .tooLarge)119 #expect(await kind { try await engine.put(.note, "n", data: "scalar") } == .rejected)120 #expect(await engine.status.pendingWrites == 0)121 }122123 @Test func aWriteTheServerRejectsIsDroppedAndReported() async throws {124 let server = VQFakeServer()125 server.serverWrite(.watchlist, "w1", data: wl("Tech", ["AAPL"]))126 let (engine, _, _) = makeEngine(server, device: "A")127 try await engine.pull()128 try await engine.put(.watchlist, "w1", data: ["name": "no symbols"]) // 400 on the server129 try await engine.put(.note, "n1", data: note("ok", "b"))130 await engine.flush()131 #expect(await engine.status.pendingWrites == 0)132 #expect(await engine.object(.watchlist, "w1")?.data["name"] == "Tech") // back to the server's state133 #expect(server.stored(.note, "n1") != nil) // the queue went on134 let c = try #require(await engine.conflicts.first)135 #expect(c.resolution == .rejected && c.needsAttention && c.message == "symbols is required." && c.local?["name"] == "no symbols")136 #expect(await engine.status.conflictsNeedingAttention == 1)137 await engine.dismissConflict(c.id)138 #expect(await engine.conflicts.isEmpty)139 }140141 @Test func offlineQueueIsReplayedInOrder() async throws {142 let server = VQFakeServer()143 server.serverWrite(.note, "n0", data: note("zero", "b"))144 let (engine, transport, _) = makeEngine(server, device: "A")145 try await engine.pull()146 transport.offline = true147 try await engine.put(.watchlist, "w1", data: wl("one", ["A"])) // 1 create w1148 try await engine.put(.note, "n1", data: note("n1", "v1")) // 2 create n1149 try await engine.put(.watchlist, "w1", data: wl("one", ["A", "B"])) // 3 update w1 (not adjacent to op 1: kept apart)150 try await engine.delete(.note, "n0") // 4 delete n0151 try await engine.put(.note, "n1", data: note("n1", "v2")) // 5 update n1152 try await engine.put(.note, "n1", data: note("n1", "v3")) // …folded into 5 (same object, tail of the queue)153 #expect(await engine.pendingWrites.map(\.opId) == [1, 2, 3, 4, 5])154 #expect(await engine.object(.note, "n0") == nil) // the local view already shows the deletion155 #expect(await engine.object(.note, "n1")?.data["body"] == "v3")156 await engine.flush() // offline: nothing leaves, nothing is lost157 #expect(await engine.status.pendingWrites == 5)158 #expect(await engine.status.lastError != nil)159 #expect(server.currentSeq == 1)160161 transport.offline = false162 await engine.flush()163 let writes = server.requests.filter { $0.device == "A" && $0.request.method != .get }.map { "\($0.request.method.rawValue) \($0.request.path)" }164 #expect(writes == ["PUT /api/v2/objects/watchlist/w1", "PUT /api/v2/objects/note/n1", "PUT /api/v2/objects/watchlist/w1",165 "DELETE /api/v2/objects/note/n0", "PUT /api/v2/objects/note/n1"])166 // it never invents a rev: each write carried the rev the server had given167 let revs = server.requests.filter { $0.device == "A" && $0.request.method == .put }.map { (try? VQJSON.parse($0.request.body!))?["baseRev"]?.intValue }168 #expect(revs == [0, 0, 1, 1])169 #expect(server.stored(.watchlist, "w1")?.rev == 2 && server.stored(.note, "n1")?.data["body"] == "v3" && server.stored(.note, "n0")?.deleted == true)170 #expect(await engine.status.pendingWrites == 0)171 #expect((await engine.conflicts).isEmpty)172 #expect(await engine.status.cursor == server.currentSeq)173 }174175 @Test func deletingSomethingNeverSentCancelsItsCreation() async throws {176 let server = VQFakeServer()177 let (engine, transport, _) = makeEngine(server, device: "A")178 transport.offline = true179 try await engine.put(.note, "draft", data: note("d", "x"))180 try await engine.delete(.note, "draft")181 #expect(await engine.status.pendingWrites == 0)182 #expect((await engine.object(.note, "draft")) == nil)183 transport.offline = false184 await engine.flush()185 #expect(server.requestCount(.put, pathPrefix: "/api/v2/objects") == 0)186 }187188 @Test func rateLimitAndServerErrorsKeepTheQueue() async throws {189 let server = VQFakeServer()190 let (engine, transport, _) = makeEngine(server, device: "A")191 try await engine.put(.note, "n1", data: note("t", "b"))192 transport.failNext(.status(429, retryAfter: 9))193 await engine.flush()194 #expect(await engine.status.pendingWrites == 1)195 transport.failNext(.status(503))196 await engine.flush()197 #expect(await engine.status.pendingWrites == 1)198 await engine.flush()199 #expect(await engine.status.pendingWrites == 0)200 #expect(server.stored(.note, "n1")?.rev == 1)201 }202203 @Test func aDeadSessionStopsTheFlush() async throws {204 let server = VQFakeServer()205 let (engine, transport, _) = makeEngine(server, device: "A")206 try await engine.put(.note, "n1", data: note("t", "b"))207 transport.failNext(.status(401, locked: true))208 await engine.flush()209 #expect(await engine.status.connection == .locked)210 #expect(await engine.status.pendingWrites == 1) // kept for after the next sign-in211 }212}213214/// The conflict policy of CONTRACT §1.2, exercised through two devices and the fake server.215@Suite struct SyncEngineConflictTests {216 private func pair() async throws -> (VQFakeServer, VQSyncEngine, VQSyncEngine) {217 let server = VQFakeServer()218 let (a, _, _) = makeEngine(server, device: "A")219 let (b, _, _) = makeEngine(server, device: "B")220 return (server, a, b)221 }222223 @Test func watchlistMergesElementWise() async throws {224 let (server, a, b) = try await pair()225 server.serverWrite(.watchlist, "w", data: wl("W", ["AAPL", "MSFT", "NVDA"]))226 try await a.pull(); try await b.pull()227 try await b.put(.watchlist, "w", data: wl("W", ["AAPL", "NVDA", "TSLA"])) // B: − MSFT, + TSLA228 await b.flush()229 try await a.put(.watchlist, "w", data: wl("W", ["AAPL", "MSFT", "AMZN"])) // A (stale): − NVDA, + AMZN230 await a.flush() // 409 → merge → retry with the new baseRev231 let stored = try #require(server.stored(.watchlist, "w"))232 #expect(stored.data["symbols"] == ["AAPL", "AMZN", "TSLA"]) // union; each side's removals hold233 #expect(stored.rev == 3 && stored.device == "A")234 #expect(server.requestCount(.put, pathPrefix: "/api/v2/objects/watchlist/w") == 4) // server, B, A (409), A (accepted)235 let c = try #require(await a.conflicts.first)236 #expect(c.resolution == .mergedElements && !c.needsAttention && c.mergedLists == ["symbols"] && c.remoteDevice == "B" && c.remoteRev == 2)237 #expect(await a.status.conflictsNeedingAttention == 0)238 try await b.pull()239 #expect(await b.object(.watchlist, "w")?.data == stored.data)240 }241242 @Test func portfolioPositionsLocalEditWinsPerElement() async throws {243 let (server, a, b) = try await pair()244 let p0: VQJSON = ["name": "Main", "baseCurrency": "USD", "positions": [["symbol": "AAPL", "quantity": 10, "updatedAt": 1], ["symbol": "MSFT", "quantity": 5, "updatedAt": 1]]]245 server.serverWrite(.portfolio, "main", data: p0)246 try await a.pull(); try await b.pull()247 var pb = try #require(await b.object(VQPortfolio.self, id: "main")).data248 pb.upsert(.init(symbol: "MSFT", quantity: 9)); pb.upsert(.init(symbol: "NVDA", quantity: 1)); pb.upsert(.init(symbol: "AAPL", quantity: 99))249 try await b.put(pb, id: "main"); await b.flush()250 var pa = try #require(await a.object(VQPortfolio.self, id: "main")).data251 pa.upsert(.init(symbol: "AAPL", quantity: 12, note: "mine")); pa.upsert(.init(symbol: "GLD", quantity: 2))252 try await a.put(pa, id: "main"); await a.flush()253 let merged = VQPortfolio(json: try #require(server.stored(.portfolio, "main")).data)254 #expect(merged.positions.map(\.symbol) == ["AAPL", "MSFT", "GLD", "NVDA"])255 #expect(merged.position("AAPL")?.quantity == 12 && merged.position("AAPL")?.note == "mine") // edited on both: local edit wins256 #expect(merged.position("AAPL")?.raw["updatedAt"] == .number(1)) // the unknown key travelled with it257 #expect(merged.position("MSFT")?.quantity == 9 && merged.position("NVDA")?.quantity == 1) // untouched here: the server's258 #expect(await a.conflicts.first?.resolution == .mergedElements)259 }260261 @Test func aNewClientNeverCreatesMainOverTheBridgedPortfolio() async throws {262 // CONTRACT §1.4: PUT baseRev 0 on portfolio/main gets a 409 carrying the copied portfolio263 let (server, a, _) = try await pair()264 try await a.put(VQPortfolio(name: "Mon portefeuille", positions: [.init(symbol: "SHOP.TO", quantity: 4)]), id: "main")265 server.serverWrite(.portfolio, "main", data: ["name": "Portefeuille principal", "baseCurrency": "USD", "positions": [["symbol": "AAPL", "quantity": 10, "updatedAt": 7]]])266 await a.flush()267 let merged = VQPortfolio(json: try #require(server.stored(.portfolio, "main")).data)268 #expect(Set(merged.positions.map(\.symbol)) == ["AAPL", "SHOP.TO"] && merged.position("AAPL")?.raw["updatedAt"] == .number(7))269 #expect(server.stored(.portfolio, "main")?.rev == 2)270 }271272 @Test func projectItemsMergeAndTheTitleConflictIsSurfaced() async throws {273 let (server, a, b) = try await pair()274 server.serverWrite(.project, "p", data: ["title": "Study", "items": [["id": "i1", "type": "note", "ref": "n1"]]])275 try await a.pull(); try await b.pull()276 var pb = try #require(await b.object(VQProject.self, id: "p")).data277 pb.title = "Study (B)"; pb.items += [.init(id: "iB", type: .quantJob, ref: "job-b")]278 try await b.put(pb, id: "p"); await b.flush()279 var pa = try #require(await a.object(VQProject.self, id: "p")).data280 pa.title = "Study (A)"; pa.items += [.init(id: "iA", type: .conversation, ref: "s-a")]281 try await a.put(pa, id: "p"); await a.flush()282 let merged = VQProject(json: try #require(server.stored(.project, "p")).data)283 #expect(merged.items.map(\.id) == ["i1", "iA", "iB"] && merged.title == "Study (A)")284 let c = try #require(await a.conflicts.first)285 #expect(c.resolution == .localWon && c.needsAttention && c.differingKeys == ["title"] && c.mergedLists == ["items"])286 #expect(c.local?["title"] == "Study (A)" && c.remote?["title"] == "Study (B)") // both versions for the UI287 }288289 @Test func chartDrawingsMerge() async throws {290 let (server, a, b) = try await pair()291 server.serverWrite(.chart, "c", data: ["symbol": "AAPL", "drawings": [["id": "d1", "type": "line"]]])292 try await a.pull(); try await b.pull()293 var cb = try #require(await b.object(VQChart.self, id: "c")).data294 cb.drawings += [.init(id: "dB", type: "ray", points: [.init(t: 1, p: 2)])]295 try await b.put(cb, id: "c"); await b.flush()296 var ca = try #require(await a.object(VQChart.self, id: "c")).data297 ca.drawings = [.init(id: "dA", type: "fib", points: [])] // A removed d1, added dA298 try await a.put(ca, id: "c"); await a.flush()299 #expect(VQChart(json: server.stored(.chart, "c")!.data).drawings.map(\.id) == ["dA", "dB"])300 }301302 @Test func notesAreLastWriterWinsAndBothVersionsAreKeptForTheUser() async throws {303 let (server, a, b) = try await pair()304 server.serverWrite(.note, "n", data: note("Title", "original"))305 try await a.pull(); try await b.pull()306 try await b.put(.note, "n", data: note("Title", "B wrote this")); await b.flush()307 try await a.put(.note, "n", data: note("Title", "A wrote this")); await a.flush()308 #expect(server.stored(.note, "n")?.data["body"] == "A wrote this" && server.stored(.note, "n")?.rev == 3)309 let c = try #require(await a.conflicts.first)310 #expect(c.resolution == .localWon && c.needsAttention && c.differingKeys == ["body"])311 #expect(c.local?["body"] == "A wrote this" && c.remote?["body"] == "B wrote this" && c.result?["body"] == "A wrote this")312 #expect(await a.status.conflictsNeedingAttention == 1)313 // "keep theirs": the other version is written back, the record goes away314 try await a.restoreRemoteVersion(ofConflict: c.id)315 await a.flush()316 #expect(server.stored(.note, "n")?.data["body"] == "B wrote this")317 #expect((await a.conflicts).isEmpty)318 // the server archived the replaced revisions of a note319 let versions = try await VQObjectStoreClient(transport: server.transport(device: "x")).versions(.note, "n")320 #expect(versions.map(\.rev) == [3, 2, 1])321 }322323 @Test func sameTextOnBothSidesIsNotAConflict() async throws {324 let (server, a, b) = try await pair()325 server.serverWrite(.note, "n", data: note("T", "v0"))326 try await a.pull(); try await b.pull()327 try await b.put(.note, "n", data: note("T", "same")); await b.flush()328 try await a.put(.note, "n", data: note("T", "same")); await a.flush()329 #expect(server.stored(.note, "n")?.rev == 2) // nothing to write330 #expect(await a.conflicts.isEmpty)331 #expect((await a.status.pendingWrites) == 0)332 }333334 @Test(arguments: [VQObjectKind.workspace, .preference])335 func otherKindsAreLastWriterWins(_ kind: VQObjectKind) async throws {336 let (server, a, b) = try await pair()337 let v0: VQJSON = ["name": "v0", "layout": ["type": "panel", "panelId": "p"], "panels": ["p": ["type": "chart"]], "theme": "dark"]338 server.serverWrite(kind, "default", data: v0)339 try await a.pull(); try await b.pull()340 var vb = v0.objectValue!; vb["theme"] = "light"; vb["name"] = "vB"341 try await b.put(kind, "default", data: .object(vb)); await b.flush()342 var va = v0.objectValue!; va["name"] = "vA"343 try await a.put(kind, "default", data: .object(va)); await a.flush()344 #expect(server.stored(kind, "default")?.data == .object(va)) // A's object, whole345 #expect(Set(try #require(await a.conflicts.first).differingKeys) == ["name", "theme"])346 }347348 @Test func fieldGranularityKeepsWhatThisDeviceDidNotTouch() async throws {349 let server = VQFakeServer()350 let (a, _, _) = makeEngine(server, device: "A") { $0.granularity = .field }351 let (b, _, _) = makeEngine(server, device: "B")352 server.serverWrite(.note, "n", data: note("Title", "body"))353 try await a.pull(); try await b.pull()354 try await b.put(.note, "n", data: note("Title", "body by B")); await b.flush()355 try await a.put(.note, "n", data: note("Title by A", "body")); await a.flush()356 #expect(server.stored(.note, "n")?.data == note("Title by A", "body by B"))357 #expect(await a.conflicts.isEmpty) // nothing was lost358 }359360 @Test func aStaleReplicaIsMergedBeforeAnythingIsSent() async throws {361 // the pull arrived before the flush: no 409 round trip is needed362 let (server, a, b) = try await pair()363 server.serverWrite(.watchlist, "w", data: wl("W", ["A"]))364 try await a.pull(); try await b.pull()365 try await a.put(.watchlist, "w", data: wl("W", ["A", "L"]))366 try await b.put(.watchlist, "w", data: wl("W", ["A", "R"])); await b.flush()367 try await a.pull()368 #expect(await a.object(.watchlist, "w")?.data["symbols"] == ["A", "L"]) // the pending edit stays on top369 await a.flush()370 #expect(server.stored(.watchlist, "w")?.data["symbols"] == ["A", "L", "R"])371 #expect(server.requests.filter { $0.device == "A" && $0.request.method == .put }.count == 1)372 }373374 @Test func localDeletionWinsOverARemoteEditAndSaysSo() async throws {375 let (server, a, b) = try await pair()376 server.serverWrite(.note, "n", data: note("T", "v0"))377 try await a.pull(); try await b.pull()378 try await b.put(.note, "n", data: note("T", "B's important edit")); await b.flush()379 try await a.delete(.note, "n"); await a.flush()380 #expect(server.stored(.note, "n")?.deleted == true && server.stored(.note, "n")?.rev == 3)381 let c = try #require(await a.conflicts.first)382 #expect(c.resolution == .localDeleteWon && c.needsAttention && c.remote?["body"] == "B's important edit")383 try await a.restoreRemoteVersion(ofConflict: c.id); await a.flush() // the person can bring it back384 #expect(server.stored(.note, "n")?.deleted == false && server.stored(.note, "n")?.data["body"] == "B's important edit")385 }386387 @Test func anEditOfSomethingDeletedElsewhereRecreatesIt() async throws {388 let (server, a, b) = try await pair()389 server.serverWrite(.note, "n", data: note("T", "v0"))390 try await a.pull(); try await b.pull()391 try await b.delete(.note, "n"); await b.flush()392 try await a.put(.note, "n", data: note("T", "A kept writing")); await a.flush()393 let stored = try #require(server.stored(.note, "n"))394 #expect(!stored.deleted && stored.rev == 3 && stored.data["body"] == "A kept writing")395 #expect(await a.conflicts.first?.resolution == .recreated)396 // both deleted: nothing to do, no conflict397 try await a.pull(); try await b.pull()398 try await b.delete(.note, "n"); await b.flush()399 try await a.delete(.note, "n"); await a.flush()400 #expect(server.stored(.note, "n")?.rev == 4)401 #expect((await a.conflicts).count == 1)402 #expect((await a.status.pendingWrites) == 0)403 }404405 @Test func queuedWritesOnOneObjectRebaseOnTheMergedResult() async throws {406 let (server, a, b) = try await pair()407 server.serverWrite(.watchlist, "w", data: wl("W", ["A"]))408 server.serverWrite(.note, "n", data: note("t", "b"))409 try await a.pull(); try await b.pull()410 try await a.put(.watchlist, "w", data: wl("W", ["A", "L1"]))411 try await a.put(.note, "n", data: note("t", "b2")) // separates the two watchlist writes412 try await a.put(.watchlist, "w", data: wl("W", ["A", "L1", "L2"]))413 try await b.put(.watchlist, "w", data: wl("W", ["A", "R"])); await b.flush()414 await a.flush()415 #expect(server.stored(.watchlist, "w")?.data["symbols"] == ["A", "L1", "L2", "R"]) // R survives both of A's writes416 #expect(await a.status.pendingWrites == 0)417 }418}419420@Suite struct SyncEnginePersistenceTests {421 /// A cipher that makes plaintext unrecognisable (stands in for the apps' AES-GCM sealing).422 struct XorCipher: VQSyncCipher {423 func seal(_ plaintext: Data) throws -> Data { Data([0xA7]) + Data(plaintext.map { $0 ^ 0x5C }) }424 func open(_ sealed: Data) throws -> Data {425 guard sealed.first == 0xA7 else { throw CocoaError(.fileReadCorruptFile) }426 return Data(sealed.dropFirst().map { $0 ^ 0x5C })427 }428 }429430 private func tempDir() -> URL { FileManager.default.temporaryDirectory.appendingPathComponent("vqkit-test-\(UUID().uuidString)") }431432 @Test func theQueueAndReplicaSurviveARestart() async throws {433 let server = VQFakeServer()434 server.serverWrite(.note, "n0", data: note("zero", "b"))435 let storage = VQMemorySyncStorage()436 do {437 let (engine, transport, _) = makeEngine(server, device: "A", storage: storage)438 try await engine.pull()439 transport.offline = true440 try await engine.put(.note, "n1", data: note("offline", "draft"))441 try await engine.delete(.note, "n0")442 } // the process dies here443 let (engine, _, _) = makeEngine(server, device: "A", storage: storage)444 try await engine.load()445 #expect(await engine.status.pendingWrites == 2)446 #expect((await engine.status.cursor) == 1)447 #expect(await engine.object(.note, "n1")?.data["body"] == "draft")448 #expect((await engine.object(.note, "n0")) == nil)449 await engine.flush()450 #expect(server.stored(.note, "n1")?.rev == 1 && server.stored(.note, "n0")?.deleted == true)451 // new writes do not reuse an operation number452 try await engine.put(.note, "n2", data: note("x", "y"))453 #expect(await engine.pendingWrites.first?.opId == 3)454 }455456 @Test func killedBetweenWriteAndAckDoesNotWriteTwice() async throws {457 let server = VQFakeServer()458 server.serverWrite(.note, "n", data: note("t", "v0"))459 let storage = VQMemorySyncStorage()460 do {461 let (engine, transport, _) = makeEngine(server, device: "A", storage: storage)462 try await engine.pull()463 try await engine.put(.note, "n", data: note("t", "v1"))464 try await engine.put(.watchlist, "w", data: wl("new", ["A"]))465 transport.failNext(.lostResponse) // the server applies the write; the answer never arrives466 await engine.flush()467 #expect(await engine.status.pendingWrites == 2) // it cannot know: both stay queued468 #expect(server.stored(.note, "n")?.rev == 2)469 } // …and the process is killed470 let (engine, transport, _) = makeEngine(server, device: "A", storage: storage)471 try await engine.load()472 #expect(await engine.status.pendingWrites == 2)473 await engine.flush()474 #expect(server.stored(.note, "n")?.rev == 2) // not written a second time475 #expect(server.stored(.note, "n")?.data["body"] == "v1" && server.stored(.watchlist, "w")?.rev == 1)476 #expect(await engine.status.pendingWrites == 0)477 #expect((await engine.conflicts).isEmpty)478 #expect(await engine.object(.note, "n")?.rev == 2)479 }480481 @Test func aLostAckOfACreationAndOfADeletion() async throws {482 let server = VQFakeServer()483 server.serverWrite(.note, "gone", data: note("t", "b"))484 let (engine, transport, _) = makeEngine(server, device: "A")485 try await engine.pull()486 try await engine.put(.watchlist, "w", data: wl("W", ["A"]))487 transport.failNext(.lostResponse)488 await engine.flush()489 await engine.flush() // create again → 409 with identical data → done490 #expect(server.stored(.watchlist, "w")?.rev == 1)491 #expect((await engine.status.pendingWrites) == 0)492 #expect((await engine.conflicts).isEmpty)493 try await engine.delete(.note, "gone")494 transport.failNext(.lostResponse)495 await engine.flush()496 await engine.flush() // delete again → 409 with the tombstone → done497 #expect(server.stored(.note, "gone")?.rev == 2)498 #expect((await engine.status.pendingWrites) == 0)499 #expect((await engine.conflicts).isEmpty)500 }501502 @Test func fileStorageIsAtomicNamedAndSealed() async throws {503 let dir = tempDir()504 defer { try? FileManager.default.removeItem(at: dir) }505 let server = VQFakeServer()506 server.serverWrite(.note, "n1", data: note("Secret title", "Secret body"))507 do {508 let storage = try VQFileSyncStorage(directory: dir, cipher: XorCipher())509 let (engine, transport, _) = makeEngine(server, device: "A", storage: storage)510 try await engine.pull()511 transport.offline = true512 try await engine.put(.note, "n2", data: note("Pending secret", "x"))513 #expect(try storage.list(prefix: "") == ["meta.json", "objects/note/n1.json", "queue.json"])514 for name in try storage.list(prefix: "") {515 let raw = try Data(contentsOf: dir.appendingPathComponent(name))516 #expect(String(decoding: raw, as: UTF8.self).contains("ecret") == false, "\(name) is stored in clear")517 }518 #expect(try FileManager.default.contentsOfDirectory(atPath: dir.path).allSatisfy { !$0.hasPrefix(".") && !$0.contains("tmp") }) // no temporary file left behind519 #expect(throws: (any Error).self) { try storage.write("../escape.json", Data()) }520 #expect(throws: (any Error).self) { try storage.write("objects/a b.json", Data()) }521 }522 // a second process with the same directory and key523 let (engine, _, _) = makeEngine(server, device: "A", storage: try VQFileSyncStorage(directory: dir, cipher: XorCipher()))524 try await engine.load()525 #expect(await engine.object(.note, "n1")?.data["title"] == "Secret title")526 #expect((await engine.status.pendingWrites) == 1)527 await engine.flush()528 #expect(server.stored(.note, "n2") != nil)529 }530531 @Test func anUnreadableReplicaFileIsRebuiltFromTheFeed() async throws {532 let dir = tempDir()533 defer { try? FileManager.default.removeItem(at: dir) }534 let server = VQFakeServer()535 server.serverWrite(.note, "n1", data: note("one", "b"))536 server.serverWrite(.note, "n2", data: note("two", "b"))537 let storage = try VQFileSyncStorage(directory: dir)538 do {539 let (engine, _, _) = makeEngine(server, device: "A", storage: storage)540 try await engine.pull()541 }542 try Data("{ truncated".utf8).write(to: dir.appendingPathComponent("objects/note/n1.json")) // half-written by something else543 let (engine, _, _) = makeEngine(server, device: "A", storage: storage)544 try await engine.load()545 #expect(await engine.objects(.note).map(\.id) == ["n2"])546 #expect((await engine.status.cursor) == 0) // the cursor goes back to the start547 try await engine.pull()548 #expect(await engine.objects(.note).count == 2)549 }550551 @Test func aCrashBetweenAcceptanceAndQueueRemovalIsHarmless() async throws {552 // the object file holds the accepted state but queue.json still lists the write553 let server = VQFakeServer()554 let storage = VQMemorySyncStorage()555 let (first, _, _) = makeEngine(server, device: "A", storage: storage)556 try await first.put(.note, "n", data: note("t", "v1"))557 let queueBefore = try #require(try storage.read("queue.json"))558 await first.flush()559 try storage.write("queue.json", queueBefore) // as if the last write never hit the disk560 let (second, _, _) = makeEngine(server, device: "A", storage: storage)561 try await second.load()562 #expect(await second.status.pendingWrites == 1)563 await second.flush()564 #expect(server.stored(.note, "n")?.rev == 1)565 #expect((await second.status.pendingWrites) == 0)566 #expect(server.requestCount(.put, pathPrefix: "/api/v2/objects/note/n") == 1) // decided from the replica: nothing was sent567 }568569 @Test func resetForgetsEverything() async throws {570 let server = VQFakeServer()571 server.serverWrite(.note, "n", data: note("t", "b"))572 let storage = VQMemorySyncStorage()573 let (engine, _, _) = makeEngine(server, device: "A", storage: storage)574 try await engine.pull()575 await engine.reset()576 #expect(try storage.list(prefix: "").isEmpty)577 #expect((await engine.objects(.note)).isEmpty)578 #expect((await engine.status.cursor) == 0)579 }580}581582@Suite struct SyncEngineStreamTests {583 @Test func theStreamKeepsTheReplicaCurrentAndExposesHints() async throws {584 let server = VQFakeServer()585 server.serverWrite(.note, "n0", data: note("zero", "b"))586 let clock = VQManualClock()587 let (a, _, _) = makeEngine(server, device: "A", clock: clock)588 let (b, _, _) = makeEngine(server, device: "B")589 let hints = await a.hints()590 await a.start()591 #expect(await vqWaitUntil { await a.object(.note, "n0") != nil }) // hello → pull592 #expect(await a.status.connection == .connected)593 // a change made by another device arrives without polling594 try await b.put(.watchlist, "w", data: wl("from B", ["X"])); await b.flush()595 #expect(await vqWaitUntil { await a.object(.watchlist, "w")?.data["name"] == "from B" })596 try await b.pull()597 try await b.delete(.note, "n0"); await b.flush()598 #expect(await vqWaitUntil { await a.object(.note, "n0") == nil })599 // hints: conversations, analyses and jobs are not objects600 server.sendHeartbeat()601 server.sendRaw("event: later_event\ndata: {\"type\":\"later_event\"}\n\ndata: garbage\n\n") // unknown and malformed frames are ignored602 server.sendHint(topic: "quant_jobs", id: "job-1")603 server.sendHint(topic: "sessions", id: "s-1")604 var got: [VQSyncHint] = []605 for await h in hints { got.append(h); if got.count == 2 { break } }606 #expect(got == [VQSyncHint(topic: .quantJobs, id: "job-1"), VQSyncHint(topic: .sessions, id: "s-1")])607 // our own write, announced back on the stream, costs no extra pull608 try await a.put(.note, "first", data: note("f", "b")); await a.flush() // (the engine learns its device id from its first accepted write)609 #expect(await vqWaitUntil { await a.status.cursor == server.currentSeq })610 let pullsBefore = server.requestCount(.get, pathPrefix: "/api/v2/sync/changes")611 try await a.put(.note, "mine", data: note("m", "b")); await a.flush()612 #expect(await vqWaitUntil { await a.status.cursor == server.currentSeq })613 #expect(server.requestCount(.get, pathPrefix: "/api/v2/sync/changes") == pullsBefore)614 await a.stop()615 #expect(await a.status.connection == .stopped)616 #expect(await vqWaitUntil { server.openStreams == 0 })617 }618619 @Test func reconnectsWithBackoffAndCatchesUp() async throws {620 let server = VQFakeServer()621 let clock = VQManualClock()622 let (a, transport, _) = makeEngine(server, device: "A", clock: clock)623 await a.start()624 #expect(await vqWaitUntil { await a.status.connection == .connected })625626 // the network goes away: the stream drops and every new attempt fails627 transport.offline = true628 server.dropStreams(error: URLError(.networkConnectionLost))629 #expect(await clock.waitForSleepers(1))630 #expect(await a.status.connection == .reconnecting(attempt: 1, retryIn: 1))631 clock.advance(by: 1)632 #expect(await vqWaitUntil { clock.recordedSleeps.count == 2 })633 #expect(await clock.waitForSleepers(1))634 #expect(await a.status.connection == .reconnecting(attempt: 2, retryIn: 2))635 clock.advance(by: 1) // not yet636 try await Task.sleep(nanoseconds: 20_000_000)637 #expect(clock.recordedSleeps == [1, 2])638 clock.advance(by: 1)639 #expect(await vqWaitUntil { clock.recordedSleeps.count == 3 })640 #expect(clock.recordedSleeps == [1, 2, 4])641642 // meanwhile another device writes, and this one edits offline643 server.serverWrite(.note, "while-away", data: note("missed", "b"))644 try await a.put(.note, "offline-edit", data: note("o", "b"))645 #expect(await a.object(.note, "while-away") == nil)646647 transport.offline = false648 #expect(await clock.waitForSleepers(1))649 clock.advance(by: 4)650 #expect(await vqWaitUntil { await a.status.connection == .connected })651 #expect(await vqWaitUntil { await a.object(.note, "while-away") != nil }) // caught up from the cursor652 #expect(await vqWaitUntil { server.stored(.note, "offline-edit") != nil }) // and the queue was replayed on hello653 // the back-off starts over after a successful hello654 server.dropStreams()655 #expect(await vqWaitUntil { clock.recordedSleeps.count == 4 })656 #expect(clock.recordedSleeps.last == 1)657 await a.stop()658 }659660 @Test func honoursRetryAfterAndStopsWhenLocked() async throws {661 let server = VQFakeServer()662 let clock = VQManualClock()663 let (a, transport, _) = makeEngine(server, device: "A", clock: clock)664 transport.failNextStream(.status(429, retryAfter: 30), .status(401, locked: true)) // too many open streams, then a dead session665 await a.start()666 #expect(await clock.waitForSleepers(1))667 #expect(clock.recordedSleeps == [30])668 #expect(await a.status.connection == .reconnecting(attempt: 1, retryIn: 30))669 clock.advance(by: 30)670 #expect(await vqWaitUntil { await a.status.connection == .locked })671 try await Task.sleep(nanoseconds: 20_000_000)672 #expect(clock.recordedSleeps == [30] && server.openStreams == 0) // no further attempt673 await a.stop()674 }675676 @Test func eventsAnnounceChangesStatusAndConflicts() async throws {677 let server = VQFakeServer()678 let (a, _, _) = makeEngine(server, device: "A")679 let (b, _, _) = makeEngine(server, device: "B")680 server.serverWrite(.note, "n", data: note("t", "v0"))681 try await a.pull(); try await b.pull()682 let events = await a.events()683 try await b.put(.note, "n", data: note("t", "B")); await b.flush()684 try await a.put(.note, "n", data: note("t", "A")); await a.flush()685 var sawChange = false, sawPending = false, sawConflict = false686 for await e in events {687 switch e {688 case .objectsChanged(let kinds): if kinds.contains(.note) { sawChange = true }689 case .statusChanged(let s): if s.pendingWrites == 1 { sawPending = true }690 case .conflict(let c): sawConflict = c.resolution == .localWon691 }692 if sawChange && sawPending && sawConflict { break }693 }694 #expect(sawChange && sawPending && sawConflict)695 }696}697698@Suite struct SyncConvergenceTests {699 /// Two devices edit the same objects with interleaved offline periods; after a final round both local views and700 /// the server agree — whatever the interleaving (deterministic pseudo-random scripts).701 @Test(arguments: [1, 2, 3, 4, 5, 6, 7, 8])702 func twoDevicesConverge(seed: UInt64) async throws {703 var rng = SplitMix(seed: seed)704 let server = VQFakeServer()705 let (a, ta, _) = makeEngine(server, device: "A")706 let (b, tb, _) = makeEngine(server, device: "B")707 let devices = [(a, ta), (b, tb)]708 server.serverWrite(.watchlist, "w", data: wl("W", ["S0"]))709 server.serverWrite(.portfolio, "main", data: ["name": "P", "baseCurrency": "USD", "positions": [["symbol": "S0", "quantity": 1]]])710 server.serverWrite(.note, "n", data: note("T", "v0"))711 for (e, _) in devices { try await e.pull() }712713 for step in 0..<60 {714 let (engine, transport) = devices[Int(rng.next() % 2)]715 switch rng.next() % 9 {716 case 0: transport.offline.toggle()717 case 1: await engine.flush()718 case 2: try? await engine.pull()719 case 3:720 if var w = await engine.object(VQWatchlist.self, id: "w")?.data { w.add("S\(rng.next() % 6)"); try await engine.put(w, id: "w") }721 case 4:722 if var w = await engine.object(VQWatchlist.self, id: "w")?.data { w.remove("S\(rng.next() % 6)"); try await engine.put(w, id: "w") }723 case 5:724 if var p = await engine.object(VQPortfolio.self, id: "main")?.data { p.upsert(.init(symbol: "S\(rng.next() % 4)", quantity: Double(step))); try await engine.put(p, id: "main") }725 case 6:726 if var p = await engine.object(VQPortfolio.self, id: "main")?.data { p.removePosition("S\(rng.next() % 4)"); try await engine.put(p, id: "main") }727 case 7:728 try await engine.put(.note, "n", data: note("T", "step \(step)"))729 default:730 if await engine.object(.note, "extra") == nil { try await engine.put(.note, "extra", data: note("E", "step \(step)")) } else { try await engine.delete(.note, "extra") }731 }732 }733 // everyone comes back online and settles734 for (_, t) in devices { t.offline = false }735 for _ in 0..<3 { for (e, _) in devices { await e.flush(); try await e.pull() } }736737 for kind in [VQObjectKind.watchlist, .portfolio, .note] {738 let va = await a.objects(kind).map { [$0.id: $0.data] }739 let vb = await b.objects(kind).map { [$0.id: $0.data] }740 #expect(va == vb, "seed \(seed) kind \(kind)")741 for e in await a.objects(kind) {742 #expect(server.stored(kind, e.id)?.data == e.data && server.stored(kind, e.id)?.rev == e.rev)743 }744 }745 #expect(await a.status.pendingWrites == 0)746 #expect((await b.status.pendingWrites) == 0)747 #expect(await a.status.cursor == server.currentSeq)748 #expect((await b.status.cursor) == server.currentSeq)749 // revisions never skip: rev equals the number of accepted writes on each object750 for (id, kind) in [("w", VQObjectKind.watchlist), ("main", .portfolio), ("n", .note)] {751 let accepted = server.requests.filter { $0.request.path == "/api/v2/objects/\(kind.rawValue)/\(id)" && $0.request.method != .get }.count752 #expect((server.stored(kind, id)?.rev ?? 0) <= accepted)753 }754 }755756 struct SplitMix {757 var state: UInt64758 init(seed: UInt64) { state = seed &* 0x9E3779B97F4A7C15 }759 mutating func next() -> UInt64 {760 state &+= 0x9E3779B97F4A7C15761 var z = state762 z = (z ^ (z >> 30)) &* 0xBF58476D1CE4E5B9763 z = (z ^ (z >> 27)) &* 0x94D049BB133111EB764 return z ^ (z >> 31)765 }766 }767}768769@Suite @MainActor struct SyncedCollectionTests {770 @Test func collectionFollowsTheEngine() async throws {771 let server = VQFakeServer()772 server.serverWrite(.watchlist, "w0", data: wl("Zero", ["A"]))773 let (engine, _, _) = makeEngine(server, device: "A")774 try await engine.pull()775 let collection = VQSyncedCollection<VQWatchlist>(engine: engine)776 let task = Task { await collection.observe() }777 #expect(await vqWaitUntil { await MainActor.run { collection.isLoaded && collection.items.count == 1 } })778 let id = await collection.create(VQWatchlist(name: "New", symbols: ["MSFT"]))779 #expect(collection.items.count == 2 && collection.pendingIDs == [id] && collection[id]?.data.name == "New")780 await collection.update(id) { $0.add("NVDA") }781 #expect(collection[id]?.data.symbols == ["MSFT", "NVDA"])782 await engine.flush()783 #expect(await vqWaitUntil { await MainActor.run { collection.pendingIDs.isEmpty && collection[id]?.rev == 1 } })784 server.serverWrite(.watchlist, "w9", data: wl("Remote", [])) // from elsewhere785 try await engine.pull()786 #expect(await vqWaitUntil { await MainActor.run { collection.items.count == 3 } })787 await collection.delete("w0")788 #expect(collection["w0"] == nil)789 await collection.save(VQWatchlist(name: "bad"), id: "bad id")790 #expect(collection.lastError?.kind == .rejected)791792 let status = VQSyncStatusStore(engine: engine)793 let statusTask = Task { await status.observe() }794 #expect(await vqWaitUntil { await MainActor.run { status.status.pendingWrites == 1 } })795 task.cancel(); statusTask.cancel()796 }797}798