adoor 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/CHANGELOG.md +4 -0
  2. package/README.md +2 -2
  3. package/dist/adoor.mjs +105 -84
  4. package/native/LICENSE +662 -0
  5. package/native/README.md +12 -0
  6. package/native/darwin/ADoorService.app/Contents/Info.plist +57 -0
  7. package/native/darwin/ADoorService.app/Contents/MacOS/ADoorService +0 -0
  8. package/native/darwin/ADoorService.app/Contents/PkgInfo +1 -0
  9. package/native/darwin/ADoorService.app/Contents/_CodeSignature/CodeResources +123 -0
  10. package/native/darwin/ADoorService.app/Contents/embedded.provisionprofile +0 -0
  11. package/native/source/Package.swift +6 -0
  12. package/native/source/sdk/LICENSE +21 -0
  13. package/native/source/sdk/Package.swift +14 -0
  14. package/native/source/sdk/Sources/ADoor/AdoorClient.swift +270 -0
  15. package/native/source/sdk/Sources/ADoor/AdoorError.swift +60 -0
  16. package/native/source/sdk/Sources/ADoor/Changes.swift +202 -0
  17. package/native/source/sdk/Sources/ADoor/DesktopSessionState.swift +73 -0
  18. package/native/source/sdk/Sources/ADoor/DeviceFlow.swift +70 -0
  19. package/native/source/sdk/Sources/ADoor/FolderCatalog.swift +49 -0
  20. package/native/source/sdk/Sources/ADoor/JSONValue.swift +70 -0
  21. package/native/source/sdk/Sources/ADoor/LocalStore.swift +474 -0
  22. package/native/source/sdk/Sources/ADoor/Models.swift +146 -0
  23. package/native/source/sdk/Sources/ADoor/MountModel.swift +896 -0
  24. package/native/source/sdk/Sources/ADoor/OAuth.swift +225 -0
  25. package/native/source/sdk/Sources/ADoor/Provider.swift +211 -0
  26. package/native/source/sdk/Sources/ADoor/Storage.swift +41 -0
  27. package/native/source/sdk/Sources/ADoor/SyncTree.swift +501 -0
  28. package/native/source/sdk/Sources/ADoor/Trash.swift +283 -0
  29. package/native/source/sdk/Tests/ADoorTests/ADoorTests.swift +182 -0
  30. package/native/source/sdk/Tests/ADoorTests/DesktopSessionStateTests.swift +46 -0
  31. package/native/source/sdk/Tests/ADoorTests/MountTests.swift +560 -0
  32. package/native/source/sdk/Tests/ADoorTests/RegressionTests.swift +360 -0
  33. package/native/source/service/DesktopSession.swift +241 -0
  34. package/native/source/service/DeviceClient.swift +53 -0
  35. package/native/source/service/Domains.swift +182 -0
  36. package/native/source/service/FolderRefresh.swift +37 -0
  37. package/native/source/service/KeychainStore.swift +74 -0
  38. package/native/source/service/LocalSessionSocket.swift +142 -0
  39. package/native/source/service/ServiceMain.swift +14 -0
  40. package/native/source/service/ServiceMounts.swift +34 -0
  41. package/package.json +12 -3
@@ -0,0 +1,474 @@
1
+ import Foundation
2
+ import CryptoKit
3
+
4
+ /// A SELECT the store keeps current. Tables default to those named after FROM and JOIN.
5
+ public struct CollectionSpec: Sendable {
6
+ public var sql: String
7
+ public var params: [JSONValue]
8
+ public var spaceId: String?
9
+ public var tables: [String]?
10
+ public init(sql: String, params: [JSONValue] = [], spaceId: String? = nil, tables: [String]? = nil) {
11
+ self.sql = sql
12
+ self.params = params
13
+ self.spaceId = spaceId
14
+ self.tables = tables
15
+ }
16
+ }
17
+
18
+ /// A write applied locally at once and sent with an idempotency key, so a retry never duplicates it.
19
+ public struct Mutation: Sendable {
20
+ public var sql: String
21
+ public var params: [JSONValue]
22
+ public var spaceId: String?
23
+ /// Defaults to a fresh UUID. Reuse one to make an application-level retry idempotent too.
24
+ public var idempotencyKey: String?
25
+ /// Optimistic projections per collection, replaced by server rows once the change is confirmed.
26
+ public var apply: [String: @Sendable ([Row]) -> [Row]]
27
+ /// Compare-and-set guard: put the values you read into the WHERE clause; the server rolls back a write that
28
+ /// would change a different number of rows and answers CONFLICT.
29
+ public var expectRowCount: Int?
30
+ public init(sql: String, params: [JSONValue] = [], spaceId: String? = nil, idempotencyKey: String? = nil, apply: [String: @Sendable ([Row]) -> [Row]] = [:], expectRowCount: Int? = nil) {
31
+ self.sql = sql
32
+ self.params = params
33
+ self.spaceId = spaceId
34
+ self.idempotencyKey = idempotencyKey
35
+ self.apply = apply
36
+ self.expectRowCount = expectRowCount
37
+ }
38
+ }
39
+
40
+ /// What the outbox persists about a queued write.
41
+ public struct PersistedMutation: Codable, Equatable, Sendable {
42
+ public let id: String
43
+ public let sql: String
44
+ public let params: [JSONValue]
45
+ public let spaceId: String?
46
+ public let idempotencyKey: String
47
+ public let expectRowCount: Int?
48
+ }
49
+
50
+ public enum Status: String, Sendable { case idle, syncing, live, offline, blocked }
51
+
52
+ public struct LocalStoreOptions: Sendable {
53
+ public var collections: [String: CollectionSpec]
54
+ public var storage: Storage?
55
+ /// App key prefix; identity isolation is added automatically. Legacy keys are left untouched.
56
+ public var namespace: String
57
+ /// The server rejected a queued write for good: permissions, validation, a conflict, a changed retry.
58
+ public var onRejected: (@Sendable (PersistedMutation, AdoorError) -> Void)?
59
+ /// Transient failures and refetch errors; the store keeps retrying.
60
+ public var onError: (@Sendable (AdoorError) -> Void)?
61
+ public var initialRetry: TimeInterval = 0.5
62
+ public var maxRetry: TimeInterval = 10
63
+ public init(collections: [String: CollectionSpec], storage: Storage? = nil, namespace: String = "adoor", onRejected: (@Sendable (PersistedMutation, AdoorError) -> Void)? = nil, onError: (@Sendable (AdoorError) -> Void)? = nil) {
64
+ self.collections = collections
65
+ self.storage = storage
66
+ self.namespace = namespace
67
+ self.onRejected = onRejected
68
+ self.onError = onError
69
+ }
70
+ }
71
+
72
+ /// A local-first view over ADoor: collections are SELECTs kept current from the durable change feed, writes
73
+ /// apply locally first and reach the server through an idempotent outbox that survives restarts. Authority
74
+ /// stays with the server: a rejected write is rolled back and reported, never retried.
75
+ public actor LocalStore {
76
+ private struct Pending {
77
+ let persisted: PersistedMutation
78
+ let apply: [String: @Sendable ([Row]) -> [Row]]
79
+ let continuation: CheckedContinuation<SqlResult, Error>?
80
+ }
81
+ private struct CollectionState {
82
+ var spec: CollectionSpec
83
+ var tables: [String]
84
+ var base: [Row] = []
85
+ var synced = false
86
+ var listeners: [UUID: @Sendable ([Row]) -> Void] = [:]
87
+ }
88
+
89
+ private let client: AdoorClient
90
+ private let options: LocalStoreOptions
91
+ private let storage: Storage
92
+ private let identity: LocalIdentity?
93
+ private let scope: String
94
+ private var collections: [String: CollectionState] = [:]
95
+ private var pending: [Pending] = []
96
+ private var flushTask: Task<Void, Never>?
97
+ private var syncTask: Task<Void, Error>?
98
+ private var loading: Task<Void, Error>?
99
+ private var storageTail: Task<Void, Never>?
100
+ private var closed = false
101
+ private var started = false
102
+ private var refreshScheduled: Set<String> = []
103
+ private var refreshTask: Task<Void, Never>?
104
+ private var statusListeners: [UUID: @Sendable (Status) -> Void] = [:]
105
+ public private(set) var status: Status = .idle
106
+ public var pendingCount: Int { pending.count }
107
+
108
+ public init(client: AdoorClient, options: LocalStoreOptions) {
109
+ self.client = client
110
+ self.options = options
111
+ self.storage = options.storage ?? MemoryStorage()
112
+ // Validation is performed by load/refresh before any storage or network use.
113
+ let identity = client.boundIdentity
114
+ self.identity = identity
115
+ if let identity {
116
+ let server = client.url.absoluteURL.absoluteString.trimmingCharacters(in: CharacterSet(charactersIn: "/"))
117
+ let parts = [options.namespace, server, identity.accountId, identity.workspaceId, identity.spaceId]
118
+ let data = try! JSON.encode(parts)
119
+ self.scope = "adoor:v2:" + CryptoKit.SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()
120
+ } else { self.scope = options.namespace }
121
+ for (name, spec) in options.collections {
122
+ var selected = spec
123
+ if selected.spaceId == nil { selected.spaceId = identity?.spaceId }
124
+ collections[name] = CollectionState(spec: selected, tables: spec.tables ?? LocalStore.tables(in: spec.sql))
125
+ }
126
+ }
127
+
128
+ static func tables(in sql: String) -> [String] {
129
+ var names: [String] = []
130
+ let pattern = try! NSRegularExpression(pattern: #"\b(?:from|join)\s+"?([a-z_][a-z0-9_]*)"?"#, options: [.caseInsensitive])
131
+ for match in pattern.matches(in: sql, range: NSRange(sql.startIndex..., in: sql)) {
132
+ if let range = Range(match.range(at: 1), in: sql) {
133
+ let name = sql[range].lowercased()
134
+ if !names.contains(name) { names.append(name) }
135
+ }
136
+ }
137
+ return names
138
+ }
139
+
140
+ private func key(_ part: String) -> String {
141
+ if identity != nil, part.hasPrefix("rows:"), let spaceId = collections[String(part.dropFirst(5))]?.spec.spaceId {
142
+ return "\(scope):\(spaceId):\(part)"
143
+ }
144
+ return "\(scope):\(part)"
145
+ }
146
+ private func report(_ error: Error) {
147
+ options.onError?(error as? AdoorError ?? AdoorError(code: "CLIENT", message: error.localizedDescription, status: 0))
148
+ }
149
+ private func setStatus(_ next: Status) {
150
+ guard status != next else { return }
151
+ status = next
152
+ for listener in statusListeners.values { listener(next) }
153
+ }
154
+
155
+ // MARK: Reading
156
+
157
+ /// Server rows with pending optimistic projections applied, or the cached rows before the first sync.
158
+ public func rows(of name: String) -> [Row] {
159
+ guard (try? checkIdentity()) != nil, let state = collections[name] else { return [] }
160
+ return pending.reduce(state.base) { rows, mutation in mutation.apply[name].map { $0(rows) } ?? rows }
161
+ }
162
+
163
+ public func isSynced(_ name: String) -> Bool { (try? checkIdentity()) != nil && (collections[name]?.synced ?? false) }
164
+
165
+ /// The listener receives the current rows at once and after every change. Keep the token to unsubscribe.
166
+ @discardableResult
167
+ public func subscribe(_ name: String, _ listener: @escaping @Sendable ([Row]) -> Void) -> UUID {
168
+ let token = UUID()
169
+ collections[name]?.listeners[token] = listener
170
+ listener(rows(of: name))
171
+ return token
172
+ }
173
+ public func unsubscribe(_ name: String, _ token: UUID) { collections[name]?.listeners.removeValue(forKey: token) }
174
+
175
+ /// Rows as an async sequence, for `for await rows in store.observe("notes")`.
176
+ public func observe(_ name: String) -> AsyncStream<[Row]> {
177
+ AsyncStream { continuation in
178
+ let token = subscribe(name) { rows in continuation.yield(rows) }
179
+ continuation.onTermination = { [weak self] _ in Task { await self?.unsubscribe(name, token) } }
180
+ }
181
+ }
182
+
183
+ @discardableResult
184
+ public func onStatus(_ listener: @escaping @Sendable (Status) -> Void) -> UUID {
185
+ let token = UUID()
186
+ statusListeners[token] = listener
187
+ listener(status)
188
+ return token
189
+ }
190
+ public func removeStatusListener(_ token: UUID) { statusListeners.removeValue(forKey: token) }
191
+
192
+ private func notify(_ name: String) {
193
+ guard let state = collections[name] else { return }
194
+ let current = rows(of: name)
195
+ for listener in state.listeners.values { listener((try? checkIdentity()) != nil ? current : []) }
196
+ }
197
+
198
+ // MARK: Storage and lifecycle
199
+
200
+ // Actors are reentrant across await. Serialize storage explicitly so an old
201
+ // write cannot complete after a newer outbox or after sign-out cleanup.
202
+ private func storageWork<T: Sendable>(_ operation: @escaping @Sendable () async throws -> T) async throws -> T {
203
+ let previous = storageTail
204
+ let task = Task { _ = await previous?.value; return try await operation() }
205
+ storageTail = Task { _ = try? await task.value }
206
+ return try await task.value
207
+ }
208
+
209
+ private func persistOutbox() async throws {
210
+ guard !closed else { return }
211
+ let storage = self.storage, outboxKey = key("outbox")
212
+ let encoded = String(decoding: try JSON.encode(pending.map(\.persisted)), as: UTF8.self)
213
+ try await storageWork { try await storage.set(outboxKey, encoded) }
214
+ }
215
+
216
+ private func load() async throws {
217
+ if let loading { try await loading.value; return }
218
+ let task = Task { try await self.hydrate() }
219
+ loading = task
220
+ try await task.value
221
+ }
222
+
223
+ private func checkIdentity() throws {
224
+ let current = try client.localIdentity()
225
+ if options.storage != nil && identity == nil {
226
+ throw AdoorError(code: "IDENTITY_REQUIRED", message: "Storage requires a client identity with accountId, workspaceId and spaceId.", status: 400)
227
+ }
228
+ guard current == identity else { throw AdoorError(code: "IDENTITY_CHANGED", message: "The app session changed. Use a new client and local store for this identity.", status: 401) }
229
+ }
230
+
231
+ private func hydrate() async throws {
232
+ try checkIdentity()
233
+ if identity != nil, let legacy = try await storage.get("\(options.namespace):outbox"), legacy != "[]" {
234
+ throw AdoorError(code: "LEGACY_LOCAL_STATE", message: "An unbound legacy outbox exists. Export it and verify its owner before removing its old key; it will not be replayed or cleared automatically.", status: 409)
235
+ }
236
+ for name in collections.keys {
237
+ let cached = try await storage.get(key("rows:\(name)"))
238
+ guard !closed else { return }
239
+ try checkIdentity()
240
+ if let cached, let rows = try? JSON.decode([Row].self, from: Data(cached.utf8)) { collections[name]?.base = rows }
241
+ }
242
+ let outbox = try await storage.get(key("outbox"))
243
+ guard !closed else { return }
244
+ try checkIdentity()
245
+ if let outbox {
246
+ guard let entries = try? JSON.decode([PersistedMutation].self, from: Data(outbox.utf8)), Set(entries.map(\.id)).count == entries.count else {
247
+ throw AdoorError(code: "OUTBOX_CORRUPT", message: "The saved outbox is unreadable. Preserve it for recovery before reconnecting.", status: 409)
248
+ }
249
+ pending = entries.map { Pending(persisted: $0, apply: [:], continuation: nil) }
250
+ }
251
+ for name in collections.keys { notify(name) }
252
+ }
253
+
254
+ private func ensureOpen() throws {
255
+ if closed { throw AdoorError(code: "STORE_CLOSED", message: "This store is closed. Reconnect with a new instance.", status: 409) }
256
+ }
257
+
258
+ private func halt(_ error: AdoorError, status next: Status, rejected: PersistedMutation? = nil) async throws {
259
+ guard !closed else { return }
260
+ closed = true
261
+ syncTask?.cancel(); flushTask?.cancel(); refreshTask?.cancel()
262
+ refreshScheduled.removeAll()
263
+ let retained = pending.map(\.persisted)
264
+ for mutation in pending { mutation.continuation?.resume(throwing: error) }
265
+ pending.removeAll()
266
+ for name in collections.keys { collections[name]?.base = []; collections[name]?.synced = false; notify(name) }
267
+ setStatus(next)
268
+ if let rejected { options.onRejected?(rejected, error) }
269
+ let storage = self.storage, outboxKey = key("outbox"), cacheKeys = collections.keys.map { key("rows:\($0)") }
270
+ let encoded = String(decoding: try JSON.encode(retained), as: UTF8.self)
271
+ try await storageWork {
272
+ // Never overwrite a corrupt or as-yet-unread outbox with an empty list.
273
+ if !retained.isEmpty { try await storage.set(outboxKey, encoded) }
274
+ for key in cacheKeys { try await storage.delete(key) }
275
+ }
276
+ }
277
+
278
+ // MARK: Syncing
279
+
280
+ public func refresh(_ name: String) async throws {
281
+ try ensureOpen()
282
+ guard let state = collections[name] else { throw AdoorError(code: "UNKNOWN_COLLECTION", message: "No collection is named \(name).", status: 400) }
283
+ do {
284
+ try checkIdentity()
285
+ let result = try await client.query(state.spec.sql, params: state.spec.params, spaceId: state.spec.spaceId)
286
+ guard !closed else { return }
287
+ try checkIdentity()
288
+ guard case .single(let single) = result else { throw AdoorError(code: "SINGLE_STATEMENT", message: "A collection is one SELECT statement.", status: 400) }
289
+ let storage = self.storage, cacheKey = key("rows:\(name)")
290
+ let encoded = String(decoding: try JSON.encode(single.rows), as: UTF8.self)
291
+ try await storageWork { try await storage.set(cacheKey, encoded) }
292
+ guard !closed else { return }
293
+ try checkIdentity()
294
+ collections[name]?.base = single.rows
295
+ collections[name]?.synced = true
296
+ notify(name)
297
+ } catch {
298
+ if let typed = error as? AdoorError, typed.authority { try await halt(typed, status: .blocked) }
299
+ throw error
300
+ }
301
+ }
302
+
303
+ private func schedule(_ names: [String]) {
304
+ guard !closed else { return }
305
+ refreshScheduled.formUnion(names)
306
+ guard refreshTask == nil else { return }
307
+ refreshTask = Task { [weak self] in
308
+ await Task.yield()
309
+ await self?.runScheduledRefresh()
310
+ }
311
+ }
312
+ private func runScheduledRefresh() async {
313
+ refreshTask = nil
314
+ guard !closed else { return }
315
+ let names = refreshScheduled
316
+ refreshScheduled = []
317
+ await withTaskGroup(of: Void.self) { group in
318
+ for name in names { group.addTask { [self] in do { try await self.refresh(name) } catch { await self.report(error) } } }
319
+ }
320
+ }
321
+ private func affected(by change: ChangeEvent) -> [String] {
322
+ collections.compactMap { (name, state) -> String? in
323
+ guard let table = change.table?.lowercased() else { return name }
324
+ return state.tables.isEmpty || state.tables.contains(table) ? name : nil
325
+ }
326
+ }
327
+
328
+ /// Start once. Cancellation stops this instance and retains requests for a new instance to recover.
329
+ public func start() async throws {
330
+ try ensureOpen()
331
+ guard !started else { throw AdoorError(code: "STORE_LIFECYCLE", message: "Start a fresh store instance once per connection.", status: 409) }
332
+ started = true
333
+ let task = Task { try await self.runSync() }
334
+ syncTask = task
335
+ do {
336
+ try await withTaskCancellationHandler { try await task.value } onCancel: { task.cancel() }
337
+ } catch {
338
+ if !closed, task.isCancelled {
339
+ try await halt(AdoorError(code: "STORE_STOPPED", message: "Sync stopped. Pending requests were retained.", status: 409), status: .idle)
340
+ return
341
+ }
342
+ throw error
343
+ }
344
+ }
345
+
346
+ private func runSync() async throws {
347
+ setStatus(.syncing)
348
+ try await load()
349
+ while !closed {
350
+ try Task.checkCancellation()
351
+ do {
352
+ let head = try await client.changesHead()
353
+ for name in collections.keys { try await refresh(name) }
354
+ guard !closed else { return }
355
+ setStatus(.live)
356
+ if !pending.isEmpty { flush() }
357
+ for try await frame in client.subscribeChanges(SubscribeOptions(after: head)) {
358
+ try Task.checkCancellation()
359
+ guard !closed else { return }
360
+ if case .change(let change) = frame { setStatus(.live); schedule(affected(by: change)) }
361
+ }
362
+ try Task.checkCancellation()
363
+ } catch {
364
+ if let typed = error as? AdoorError, typed.authority { try await halt(typed, status: .blocked); throw typed }
365
+ if closed { return }
366
+ try Task.checkCancellation()
367
+ report(error); setStatus(.offline)
368
+ try await Task.sleep(nanoseconds: retryNanoseconds(options.initialRetry))
369
+ }
370
+ }
371
+ }
372
+
373
+ private func retryNanoseconds(_ interval: TimeInterval) -> UInt64 {
374
+ // Public retry options must not trap on negative, infinite or huge values.
375
+ UInt64(min(3600, max(0.001, interval.isFinite ? interval : 10)) * 1_000_000_000)
376
+ }
377
+
378
+ // MARK: Writing
379
+
380
+ public func mutate(_ input: Mutation) async throws -> SqlResult {
381
+ try ensureOpen()
382
+ try await load()
383
+ try ensureOpen()
384
+ try checkIdentity()
385
+ let persisted = PersistedMutation(id: UUID().uuidString, sql: input.sql, params: input.params, spaceId: input.spaceId ?? identity?.spaceId, idempotencyKey: input.idempotencyKey ?? "\(options.namespace):\(UUID().uuidString)", expectRowCount: input.expectRowCount)
386
+ return try await withCheckedThrowingContinuation { continuation in
387
+ pending.append(Pending(persisted: persisted, apply: input.apply, continuation: continuation))
388
+ for name in input.apply.keys { notify(name) }
389
+ // This also saves later queued edits while the head waits for retry.
390
+ Task {
391
+ do { try await persistOutbox(); flush() }
392
+ catch { report(error); flush() } // drain retries storage before any HTTP request
393
+ }
394
+ }
395
+ }
396
+
397
+ private func flush() {
398
+ guard !closed, flushTask == nil else { return }
399
+ flushTask = Task { [weak self] in await self?.drain() }
400
+ }
401
+
402
+ private func settle(_ mutation: Pending, _ outcome: Result<SqlResult, AdoorError>) async throws {
403
+ guard !closed, pending.first?.persisted.id == mutation.persisted.id else { return }
404
+ let storage = self.storage, outboxKey = key("outbox")
405
+ let encoded = String(decoding: try JSON.encode(pending.dropFirst().map(\.persisted)), as: UTF8.self)
406
+ try await storageWork { try await storage.set(outboxKey, encoded) }
407
+ guard !closed, pending.first?.persisted.id == mutation.persisted.id else { return }
408
+ try checkIdentity()
409
+ pending.removeFirst()
410
+ switch outcome {
411
+ case .success(let result): mutation.continuation?.resume(returning: result)
412
+ case .failure(let error):
413
+ mutation.continuation?.resume(throwing: error)
414
+ options.onRejected?(mutation.persisted, error)
415
+ }
416
+ schedule(mutation.apply.isEmpty ? Array(collections.keys) : Array(mutation.apply.keys))
417
+ }
418
+
419
+ private func drain() async {
420
+ defer { flushTask = nil }
421
+ var delay = options.initialRetry
422
+ while let mutation = pending.first, !Task.isCancelled, !closed {
423
+ do {
424
+ try await persistOutbox()
425
+ guard !closed, !Task.isCancelled else { return }
426
+ try checkIdentity()
427
+ let result = try await client.execute(mutation.persisted.sql, params: mutation.persisted.params, spaceId: mutation.persisted.spaceId, idempotencyKey: mutation.persisted.idempotencyKey, expectRowCount: mutation.persisted.expectRowCount)
428
+ guard !closed, !Task.isCancelled else { return }
429
+ try checkIdentity()
430
+ if case .batch(let batch) = result, let failedAt = batch.failedAt {
431
+ guard batch.results.indices.contains(failedAt) else { throw AdoorError(code: "INVALID_RESPONSE", message: "The batch failure index is invalid.", status: 502) }
432
+ var cause = AdoorError(code: "BATCH_FAILED", message: "A statement did not run.", status: 500)
433
+ if case .error(_, _, let error, _, _, _, _) = batch.results[failedAt] { cause = AdoorError(code: error.code, message: error.message, status: error.status, details: error.details) }
434
+ if cause.authority { throw cause }
435
+ if cause.retryable { throw cause }
436
+ try await settle(mutation, .failure(AdoorError(code: "BATCH_FAILED", message: "Statement \(failedAt + 1) failed with \(cause.code); \(batch.completed) earlier statements committed and later ones were skipped. Send a corrected script under a new idempotency key.", status: cause.status)))
437
+ continue
438
+ }
439
+ delay = options.initialRetry
440
+ if status == .offline { setStatus(.live) }
441
+ try await settle(mutation, .success(result))
442
+ } catch {
443
+ guard !closed, !Task.isCancelled else { return }
444
+ let typed = error as? AdoorError ?? AdoorError.network(error)
445
+ if typed.authority {
446
+ do { try await halt(typed, status: .blocked, rejected: mutation.persisted) } catch { report(error) }
447
+ report(typed); return
448
+ }
449
+ if typed.retryable {
450
+ setStatus(.offline); report(typed)
451
+ try? await Task.sleep(nanoseconds: retryNanoseconds(delay))
452
+ delay = min(options.maxRetry, delay * 2)
453
+ } else {
454
+ do { try await settle(mutation, .failure(typed)) }
455
+ catch { report(error); try? await Task.sleep(nanoseconds: retryNanoseconds(delay)) }
456
+ }
457
+ }
458
+ }
459
+ }
460
+
461
+ /// Terminal sign-out/discard. An already committed server write cannot be recalled.
462
+ public func clear() async throws {
463
+ if options.storage != nil && identity == nil { try checkIdentity() }
464
+ closed = true
465
+ syncTask?.cancel(); flushTask?.cancel(); refreshTask?.cancel()
466
+ refreshScheduled.removeAll()
467
+ for mutation in pending { mutation.continuation?.resume(throwing: AdoorError(code: "STORE_CLOSED", message: "The local store was cleared.", status: 409)) }
468
+ pending.removeAll()
469
+ for name in collections.keys { collections[name]?.base = []; collections[name]?.synced = false; notify(name) }
470
+ setStatus(.idle)
471
+ let storage = self.storage, keys = [key("outbox")] + collections.keys.map { key("rows:\($0)") }
472
+ try await storageWork { for key in keys { try await storage.delete(key) } }
473
+ }
474
+ }
@@ -0,0 +1,146 @@
1
+ import Foundation
2
+
3
+ public struct Column: Codable, Equatable, Sendable {
4
+ public let name: String
5
+ public let type: String?
6
+ }
7
+
8
+ /// The result of one statement.
9
+ public struct QueryResult: Codable, Equatable, Sendable {
10
+ public let rows: [Row]
11
+ public let columns: [Column]
12
+ public let rowCount: Int
13
+ public let command: String
14
+ public let schemaVersion: Int
15
+ public let eventId: String?
16
+ /// True when the server replayed a retained result for an idempotency key instead of running the write again.
17
+ public let replayed: Bool?
18
+ }
19
+
20
+ public struct StatementError: Codable, Equatable, Sendable {
21
+ public let code: String
22
+ public let message: String
23
+ public let status: Int
24
+ public let details: JSONValue?
25
+ }
26
+
27
+ /// One statement of a script. Statements commit independently; a failed one stops the script and later ones are skipped.
28
+ public enum BatchStatement: Equatable, Sendable {
29
+ case success(index: Int, sql: String, result: QueryResult)
30
+ case error(index: Int, sql: String, error: StatementError, executed: Bool, committed: Bool, rowCount: Int?, eventId: String?)
31
+ case skipped(index: Int, sql: String)
32
+
33
+ public var index: Int {
34
+ switch self {
35
+ case .success(let index, _, _), .error(let index, _, _, _, _, _, _), .skipped(let index, _): return index
36
+ }
37
+ }
38
+ }
39
+
40
+ public struct BatchResult: Equatable, Sendable {
41
+ public let results: [BatchStatement]
42
+ public let completed: Int
43
+ public let failedAt: Int?
44
+ }
45
+
46
+ /// `query` and `execute` return one result for a single statement and a batch for a script.
47
+ public enum SqlResult: Equatable, Sendable {
48
+ case single(QueryResult)
49
+ case batch(BatchResult)
50
+
51
+ public var single: QueryResult? { if case .single(let result) = self { return result }; return nil }
52
+ public var batch: BatchResult? { if case .batch(let result) = self { return result }; return nil }
53
+
54
+ init(json: JSONValue, data: Data) throws {
55
+ if json["batch"]?.boolValue == true {
56
+ self = .batch(try BatchResult(json: json))
57
+ } else {
58
+ self = .single(try JSON.decode(QueryResult.self, from: data))
59
+ }
60
+ }
61
+ }
62
+
63
+ extension BatchResult {
64
+ init(json: JSONValue) throws {
65
+ let statements = json["results"]?.arrayValue ?? []
66
+ var results: [BatchStatement] = []
67
+ for statement in statements {
68
+ let index = statement["index"]?.intValue ?? results.count
69
+ let sql = statement["sql"]?.stringValue ?? ""
70
+ switch statement["status"]?.stringValue {
71
+ case "success":
72
+ var object = statement.objectValue ?? [:]
73
+ for key in ["index", "sql", "kind", "status"] { object.removeValue(forKey: key) }
74
+ let result = try JSON.decode(QueryResult.self, from: try JSON.encode(JSONValue.object(object)))
75
+ results.append(.success(index: index, sql: sql, result: result))
76
+ case "error":
77
+ let error = try JSON.decode(StatementError.self, from: try JSON.encode(statement["error"] ?? .object([:])))
78
+ results.append(.error(index: index, sql: sql, error: error, executed: statement["executed"]?.boolValue ?? false, committed: statement["committed"]?.boolValue ?? false, rowCount: statement["rowCount"]?.intValue, eventId: statement["eventId"]?.stringValue))
79
+ default:
80
+ results.append(.skipped(index: index, sql: sql))
81
+ }
82
+ }
83
+ self.init(results: results, completed: json["completed"]?.intValue ?? 0, failedAt: json["failedAt"]?.intValue)
84
+ }
85
+ }
86
+
87
+ public struct TableColumn: Codable, Equatable, Sendable {
88
+ public let name: String
89
+ public let type: String
90
+ public let nullable: Bool
91
+ public let primaryKey: Bool
92
+ }
93
+
94
+ public struct TableDescription: Codable, Equatable, Sendable {
95
+ public let id: String
96
+ public let name: String
97
+ public let spaceId: String
98
+ public let spaceName: String
99
+ public let spaceSlug: String
100
+ public let system: Bool?
101
+ public let systemKind: String?
102
+ public let displayName: String?
103
+ public let columns: [TableColumn]
104
+ public let permissions: [String]
105
+ }
106
+
107
+ public struct Workspace: Codable, Equatable, Sendable {
108
+ public let id: String
109
+ public let name: String
110
+ public let kind: String
111
+ }
112
+
113
+ /// What `describe()` returns: the connection, the visible tables and the read-only catalog views.
114
+ public struct Description: Codable, Sendable {
115
+ public let backend: String
116
+ public let label: String
117
+ public let workspace: Workspace
118
+ public let schemaVersion: Int
119
+ public let connection: JSONValue
120
+ public let tables: [TableDescription]
121
+ public let catalogs: JSONValue
122
+ }
123
+
124
+ /// An authorized invalidation: which table changed, never the row values. A scoped
125
+ /// connection sees `table_changed` for data it may read; a workspace owner sees the mutation kind.
126
+ public struct ChangeEvent: Codable, Equatable, Sendable {
127
+ public let cursor: String
128
+ public let eventId: String
129
+ public let type: String
130
+ public let table: String?
131
+ public let spaceId: String?
132
+ public let inodeId: String?
133
+ public let at: String
134
+ }
135
+
136
+ public struct ChangePage: Codable, Sendable {
137
+ public let changes: [ChangeEvent]
138
+ public let nextCursor: String
139
+ public let hasMore: Bool
140
+ }
141
+
142
+ /// Frames of a change subscription. A checkpoint confirms everything up to its cursor; persist it to resume later.
143
+ public enum ChangeFrame: Equatable, Sendable {
144
+ case change(ChangeEvent)
145
+ case checkpoint(cursor: String)
146
+ }