@terreno/syncdb 56.0.0-beta.0

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 (317) hide show
  1. package/README.md +419 -0
  2. package/dist/auth/betterAuthAdapter.d.ts +22 -0
  3. package/dist/auth/betterAuthAdapter.d.ts.map +1 -0
  4. package/dist/auth/betterAuthAdapter.js +181 -0
  5. package/dist/auth/betterAuthAdapter.js.map +1 -0
  6. package/dist/auth/betterAuthAdapter.test.d.ts +2 -0
  7. package/dist/auth/betterAuthAdapter.test.d.ts.map +1 -0
  8. package/dist/auth/betterAuthAdapter.test.js +350 -0
  9. package/dist/auth/betterAuthAdapter.test.js.map +1 -0
  10. package/dist/auth/types.d.ts +42 -0
  11. package/dist/auth/types.d.ts.map +1 -0
  12. package/dist/auth/types.js +9 -0
  13. package/dist/auth/types.js.map +1 -0
  14. package/dist/client.d.ts +246 -0
  15. package/dist/client.d.ts.map +1 -0
  16. package/dist/client.js +1415 -0
  17. package/dist/client.js.map +1 -0
  18. package/dist/client.test.d.ts +2 -0
  19. package/dist/client.test.d.ts.map +1 -0
  20. package/dist/client.test.js +2310 -0
  21. package/dist/client.test.js.map +1 -0
  22. package/dist/crypto/aesGcmCodec.d.ts +33 -0
  23. package/dist/crypto/aesGcmCodec.d.ts.map +1 -0
  24. package/dist/crypto/aesGcmCodec.js +80 -0
  25. package/dist/crypto/aesGcmCodec.js.map +1 -0
  26. package/dist/crypto/aesGcmCodec.test.d.ts +2 -0
  27. package/dist/crypto/aesGcmCodec.test.d.ts.map +1 -0
  28. package/dist/crypto/aesGcmCodec.test.js +83 -0
  29. package/dist/crypto/aesGcmCodec.test.js.map +1 -0
  30. package/dist/crypto/identityCodec.d.ts +7 -0
  31. package/dist/crypto/identityCodec.d.ts.map +1 -0
  32. package/dist/crypto/identityCodec.js +9 -0
  33. package/dist/crypto/identityCodec.js.map +1 -0
  34. package/dist/crypto/keyProviders.d.ts +34 -0
  35. package/dist/crypto/keyProviders.d.ts.map +1 -0
  36. package/dist/crypto/keyProviders.js +102 -0
  37. package/dist/crypto/keyProviders.js.map +1 -0
  38. package/dist/crypto/keyProviders.test.d.ts +2 -0
  39. package/dist/crypto/keyProviders.test.d.ts.map +1 -0
  40. package/dist/crypto/keyProviders.test.js +189 -0
  41. package/dist/crypto/keyProviders.test.js.map +1 -0
  42. package/dist/crypto/types.d.ts +24 -0
  43. package/dist/crypto/types.d.ts.map +1 -0
  44. package/dist/crypto/types.js +8 -0
  45. package/dist/crypto/types.js.map +1 -0
  46. package/dist/debug/debugChannel.d.ts +52 -0
  47. package/dist/debug/debugChannel.d.ts.map +1 -0
  48. package/dist/debug/debugChannel.js +73 -0
  49. package/dist/debug/debugChannel.js.map +1 -0
  50. package/dist/debug/debugChannel.test.d.ts +2 -0
  51. package/dist/debug/debugChannel.test.d.ts.map +1 -0
  52. package/dist/debug/debugChannel.test.js +105 -0
  53. package/dist/debug/debugChannel.test.js.map +1 -0
  54. package/dist/debug/debugLog.d.ts +111 -0
  55. package/dist/debug/debugLog.d.ts.map +1 -0
  56. package/dist/debug/debugLog.js +150 -0
  57. package/dist/debug/debugLog.js.map +1 -0
  58. package/dist/debug/debugLog.test.d.ts +2 -0
  59. package/dist/debug/debugLog.test.d.ts.map +1 -0
  60. package/dist/debug/debugLog.test.js +121 -0
  61. package/dist/debug/debugLog.test.js.map +1 -0
  62. package/dist/index.d.ts +46 -0
  63. package/dist/index.d.ts.map +1 -0
  64. package/dist/index.js +51 -0
  65. package/dist/index.js.map +1 -0
  66. package/dist/isolated/defaultPersisterFactoryNative.isolated.d.ts +2 -0
  67. package/dist/isolated/defaultPersisterFactoryNative.isolated.d.ts.map +1 -0
  68. package/dist/isolated/defaultPersisterFactoryNative.isolated.js +38 -0
  69. package/dist/isolated/defaultPersisterFactoryNative.isolated.js.map +1 -0
  70. package/dist/mutations/conflicts.d.ts +31 -0
  71. package/dist/mutations/conflicts.d.ts.map +1 -0
  72. package/dist/mutations/conflicts.js +73 -0
  73. package/dist/mutations/conflicts.js.map +1 -0
  74. package/dist/mutations/outbox.d.ts +174 -0
  75. package/dist/mutations/outbox.d.ts.map +1 -0
  76. package/dist/mutations/outbox.js +385 -0
  77. package/dist/mutations/outbox.js.map +1 -0
  78. package/dist/mutations/outbox.test.d.ts +2 -0
  79. package/dist/mutations/outbox.test.d.ts.map +1 -0
  80. package/dist/mutations/outbox.test.js +643 -0
  81. package/dist/mutations/outbox.test.js.map +1 -0
  82. package/dist/mutations/resolveConflict.d.ts +32 -0
  83. package/dist/mutations/resolveConflict.d.ts.map +1 -0
  84. package/dist/mutations/resolveConflict.js +101 -0
  85. package/dist/mutations/resolveConflict.js.map +1 -0
  86. package/dist/mutations/resolveConflict.test.d.ts +2 -0
  87. package/dist/mutations/resolveConflict.test.d.ts.map +1 -0
  88. package/dist/mutations/resolveConflict.test.js +282 -0
  89. package/dist/mutations/resolveConflict.test.js.map +1 -0
  90. package/dist/persisters/defaultPersisterFactory.d.ts +9 -0
  91. package/dist/persisters/defaultPersisterFactory.d.ts.map +1 -0
  92. package/dist/persisters/defaultPersisterFactory.js +9 -0
  93. package/dist/persisters/defaultPersisterFactory.js.map +1 -0
  94. package/dist/persisters/defaultPersisterFactory.native.d.ts +10 -0
  95. package/dist/persisters/defaultPersisterFactory.native.d.ts.map +1 -0
  96. package/dist/persisters/defaultPersisterFactory.native.js +44 -0
  97. package/dist/persisters/defaultPersisterFactory.native.js.map +1 -0
  98. package/dist/persisters/defaultPersisterFactory.test.d.ts +2 -0
  99. package/dist/persisters/defaultPersisterFactory.test.d.ts.map +1 -0
  100. package/dist/persisters/defaultPersisterFactory.test.js +177 -0
  101. package/dist/persisters/defaultPersisterFactory.test.js.map +1 -0
  102. package/dist/persisters/defaultPersisterFactory.web.d.ts +17 -0
  103. package/dist/persisters/defaultPersisterFactory.web.d.ts.map +1 -0
  104. package/dist/persisters/defaultPersisterFactory.web.js +65 -0
  105. package/dist/persisters/defaultPersisterFactory.web.js.map +1 -0
  106. package/dist/persisters/encryptedIndexedDbPersister.d.ts +46 -0
  107. package/dist/persisters/encryptedIndexedDbPersister.d.ts.map +1 -0
  108. package/dist/persisters/encryptedIndexedDbPersister.js +171 -0
  109. package/dist/persisters/encryptedIndexedDbPersister.js.map +1 -0
  110. package/dist/persisters/encryptedIndexedDbPersister.test.d.ts +2 -0
  111. package/dist/persisters/encryptedIndexedDbPersister.test.d.ts.map +1 -0
  112. package/dist/persisters/encryptedIndexedDbPersister.test.js +352 -0
  113. package/dist/persisters/encryptedIndexedDbPersister.test.js.map +1 -0
  114. package/dist/persisters/memoryPersister.d.ts +19 -0
  115. package/dist/persisters/memoryPersister.d.ts.map +1 -0
  116. package/dist/persisters/memoryPersister.js +31 -0
  117. package/dist/persisters/memoryPersister.js.map +1 -0
  118. package/dist/persisters/memoryPersister.test.d.ts +2 -0
  119. package/dist/persisters/memoryPersister.test.d.ts.map +1 -0
  120. package/dist/persisters/memoryPersister.test.js +113 -0
  121. package/dist/persisters/memoryPersister.test.js.map +1 -0
  122. package/dist/persisters/types.d.ts +65 -0
  123. package/dist/persisters/types.d.ts.map +1 -0
  124. package/dist/persisters/types.js +2 -0
  125. package/dist/persisters/types.js.map +1 -0
  126. package/dist/react/hooks.d.ts +132 -0
  127. package/dist/react/hooks.d.ts.map +1 -0
  128. package/dist/react/hooks.js +269 -0
  129. package/dist/react/hooks.js.map +1 -0
  130. package/dist/react/hooks.test.d.ts +2 -0
  131. package/dist/react/hooks.test.d.ts.map +1 -0
  132. package/dist/react/hooks.test.js +645 -0
  133. package/dist/react/hooks.test.js.map +1 -0
  134. package/dist/react/index.d.ts +11 -0
  135. package/dist/react/index.d.ts.map +1 -0
  136. package/dist/react/index.js +11 -0
  137. package/dist/react/index.js.map +1 -0
  138. package/dist/react/provider.d.ts +11 -0
  139. package/dist/react/provider.d.ts.map +1 -0
  140. package/dist/react/provider.js +17 -0
  141. package/dist/react/provider.js.map +1 -0
  142. package/dist/storage/idb.d.ts +27 -0
  143. package/dist/storage/idb.d.ts.map +1 -0
  144. package/dist/storage/idb.js +72 -0
  145. package/dist/storage/idb.js.map +1 -0
  146. package/dist/storage/idb.test.d.ts +2 -0
  147. package/dist/storage/idb.test.d.ts.map +1 -0
  148. package/dist/storage/idb.test.js +100 -0
  149. package/dist/storage/idb.test.js.map +1 -0
  150. package/dist/storage/purgeUnknownStream.test.d.ts +2 -0
  151. package/dist/storage/purgeUnknownStream.test.d.ts.map +1 -0
  152. package/dist/storage/purgeUnknownStream.test.js +64 -0
  153. package/dist/storage/purgeUnknownStream.test.js.map +1 -0
  154. package/dist/storage/schema.d.ts +33 -0
  155. package/dist/storage/schema.d.ts.map +1 -0
  156. package/dist/storage/schema.js +92 -0
  157. package/dist/storage/schema.js.map +1 -0
  158. package/dist/storage/store.d.ts +136 -0
  159. package/dist/storage/store.d.ts.map +1 -0
  160. package/dist/storage/store.js +275 -0
  161. package/dist/storage/store.js.map +1 -0
  162. package/dist/storage/store.test.d.ts +2 -0
  163. package/dist/storage/store.test.d.ts.map +1 -0
  164. package/dist/storage/store.test.js +357 -0
  165. package/dist/storage/store.test.js.map +1 -0
  166. package/dist/storage/types.d.ts +146 -0
  167. package/dist/storage/types.d.ts.map +1 -0
  168. package/dist/storage/types.js +32 -0
  169. package/dist/storage/types.js.map +1 -0
  170. package/dist/storage/wipe.d.ts +22 -0
  171. package/dist/storage/wipe.d.ts.map +1 -0
  172. package/dist/storage/wipe.js +43 -0
  173. package/dist/storage/wipe.js.map +1 -0
  174. package/dist/storage/wipe.test.d.ts +2 -0
  175. package/dist/storage/wipe.test.d.ts.map +1 -0
  176. package/dist/storage/wipe.test.js +95 -0
  177. package/dist/storage/wipe.test.js.map +1 -0
  178. package/dist/sync/bootstrap.d.ts +64 -0
  179. package/dist/sync/bootstrap.d.ts.map +1 -0
  180. package/dist/sync/bootstrap.js +160 -0
  181. package/dist/sync/bootstrap.js.map +1 -0
  182. package/dist/sync/bootstrap.test.d.ts +2 -0
  183. package/dist/sync/bootstrap.test.d.ts.map +1 -0
  184. package/dist/sync/bootstrap.test.js +447 -0
  185. package/dist/sync/bootstrap.test.js.map +1 -0
  186. package/dist/sync/cursor.d.ts +67 -0
  187. package/dist/sync/cursor.d.ts.map +1 -0
  188. package/dist/sync/cursor.js +74 -0
  189. package/dist/sync/cursor.js.map +1 -0
  190. package/dist/sync/cursor.test.d.ts +2 -0
  191. package/dist/sync/cursor.test.d.ts.map +1 -0
  192. package/dist/sync/cursor.test.js +73 -0
  193. package/dist/sync/cursor.test.js.map +1 -0
  194. package/dist/sync/deltaApplier.d.ts +30 -0
  195. package/dist/sync/deltaApplier.d.ts.map +1 -0
  196. package/dist/sync/deltaApplier.js +61 -0
  197. package/dist/sync/deltaApplier.js.map +1 -0
  198. package/dist/sync/deltaApplier.test.d.ts +2 -0
  199. package/dist/sync/deltaApplier.test.d.ts.map +1 -0
  200. package/dist/sync/deltaApplier.test.js +212 -0
  201. package/dist/sync/deltaApplier.test.js.map +1 -0
  202. package/dist/sync/entityRepair.d.ts +45 -0
  203. package/dist/sync/entityRepair.d.ts.map +1 -0
  204. package/dist/sync/entityRepair.js +91 -0
  205. package/dist/sync/entityRepair.js.map +1 -0
  206. package/dist/sync/entityRepair.test.d.ts +2 -0
  207. package/dist/sync/entityRepair.test.d.ts.map +1 -0
  208. package/dist/sync/entityRepair.test.js +146 -0
  209. package/dist/sync/entityRepair.test.js.map +1 -0
  210. package/dist/sync/httpChannel.d.ts +74 -0
  211. package/dist/sync/httpChannel.d.ts.map +1 -0
  212. package/dist/sync/httpChannel.js +123 -0
  213. package/dist/sync/httpChannel.js.map +1 -0
  214. package/dist/sync/httpChannel.test.d.ts +2 -0
  215. package/dist/sync/httpChannel.test.d.ts.map +1 -0
  216. package/dist/sync/httpChannel.test.js +215 -0
  217. package/dist/sync/httpChannel.test.js.map +1 -0
  218. package/dist/sync/replayCoordinator.d.ts +212 -0
  219. package/dist/sync/replayCoordinator.d.ts.map +1 -0
  220. package/dist/sync/replayCoordinator.js +1110 -0
  221. package/dist/sync/replayCoordinator.js.map +1 -0
  222. package/dist/sync/replayCoordinator.test.d.ts +2 -0
  223. package/dist/sync/replayCoordinator.test.d.ts.map +1 -0
  224. package/dist/sync/replayCoordinator.test.js +1496 -0
  225. package/dist/sync/replayCoordinator.test.js.map +1 -0
  226. package/dist/sync/socketTransport.d.ts +56 -0
  227. package/dist/sync/socketTransport.d.ts.map +1 -0
  228. package/dist/sync/socketTransport.js +292 -0
  229. package/dist/sync/socketTransport.js.map +1 -0
  230. package/dist/sync/socketTransport.test.d.ts +2 -0
  231. package/dist/sync/socketTransport.test.d.ts.map +1 -0
  232. package/dist/sync/socketTransport.test.js +346 -0
  233. package/dist/sync/socketTransport.test.js.map +1 -0
  234. package/dist/sync/transport.d.ts +80 -0
  235. package/dist/sync/transport.d.ts.map +1 -0
  236. package/dist/sync/transport.js +5 -0
  237. package/dist/sync/transport.js.map +1 -0
  238. package/dist/testing/fakeTransport.d.ts +55 -0
  239. package/dist/testing/fakeTransport.d.ts.map +1 -0
  240. package/dist/testing/fakeTransport.js +139 -0
  241. package/dist/testing/fakeTransport.js.map +1 -0
  242. package/dist/testing/fakeTransport.test.d.ts +2 -0
  243. package/dist/testing/fakeTransport.test.d.ts.map +1 -0
  244. package/dist/testing/fakeTransport.test.js +112 -0
  245. package/dist/testing/fakeTransport.test.js.map +1 -0
  246. package/dist/testing/index.d.ts +13 -0
  247. package/dist/testing/index.d.ts.map +1 -0
  248. package/dist/testing/index.js +13 -0
  249. package/dist/testing/index.js.map +1 -0
  250. package/dist/types.d.ts +271 -0
  251. package/dist/types.d.ts.map +1 -0
  252. package/dist/types.js +9 -0
  253. package/dist/types.js.map +1 -0
  254. package/package.json +71 -0
  255. package/src/auth/betterAuthAdapter.test.ts +455 -0
  256. package/src/auth/betterAuthAdapter.ts +214 -0
  257. package/src/auth/types.ts +49 -0
  258. package/src/client.test.ts +2670 -0
  259. package/src/client.ts +1748 -0
  260. package/src/crypto/aesGcmCodec.test.ts +103 -0
  261. package/src/crypto/aesGcmCodec.ts +98 -0
  262. package/src/crypto/identityCodec.ts +10 -0
  263. package/src/crypto/keyProviders.test.ts +228 -0
  264. package/src/crypto/keyProviders.ts +153 -0
  265. package/src/crypto/types.ts +23 -0
  266. package/src/debug/debugChannel.test.ts +121 -0
  267. package/src/debug/debugChannel.ts +112 -0
  268. package/src/debug/debugLog.test.ts +139 -0
  269. package/src/debug/debugLog.ts +272 -0
  270. package/src/index.ts +157 -0
  271. package/src/isolated/defaultPersisterFactoryNative.isolated.ts +45 -0
  272. package/src/mutations/conflicts.ts +108 -0
  273. package/src/mutations/outbox.test.ts +754 -0
  274. package/src/mutations/outbox.ts +585 -0
  275. package/src/mutations/resolveConflict.test.ts +338 -0
  276. package/src/mutations/resolveConflict.ts +115 -0
  277. package/src/persisters/defaultPersisterFactory.native.ts +53 -0
  278. package/src/persisters/defaultPersisterFactory.test.ts +207 -0
  279. package/src/persisters/defaultPersisterFactory.ts +12 -0
  280. package/src/persisters/defaultPersisterFactory.web.ts +78 -0
  281. package/src/persisters/encryptedIndexedDbPersister.test.ts +381 -0
  282. package/src/persisters/encryptedIndexedDbPersister.ts +218 -0
  283. package/src/persisters/memoryPersister.test.ts +136 -0
  284. package/src/persisters/memoryPersister.ts +52 -0
  285. package/src/persisters/types.ts +71 -0
  286. package/src/react/hooks.test.tsx +761 -0
  287. package/src/react/hooks.ts +409 -0
  288. package/src/react/index.ts +11 -0
  289. package/src/react/provider.tsx +27 -0
  290. package/src/storage/idb.test.ts +116 -0
  291. package/src/storage/idb.ts +112 -0
  292. package/src/storage/purgeUnknownStream.test.ts +74 -0
  293. package/src/storage/schema.ts +103 -0
  294. package/src/storage/store.test.ts +424 -0
  295. package/src/storage/store.ts +461 -0
  296. package/src/storage/types.ts +159 -0
  297. package/src/storage/wipe.test.ts +111 -0
  298. package/src/storage/wipe.ts +58 -0
  299. package/src/sync/bootstrap.test.ts +486 -0
  300. package/src/sync/bootstrap.ts +217 -0
  301. package/src/sync/cursor.test.ts +84 -0
  302. package/src/sync/cursor.ts +113 -0
  303. package/src/sync/deltaApplier.test.ts +237 -0
  304. package/src/sync/deltaApplier.ts +84 -0
  305. package/src/sync/entityRepair.test.ts +161 -0
  306. package/src/sync/entityRepair.ts +124 -0
  307. package/src/sync/httpChannel.test.ts +265 -0
  308. package/src/sync/httpChannel.ts +220 -0
  309. package/src/sync/replayCoordinator.test.ts +1709 -0
  310. package/src/sync/replayCoordinator.ts +1370 -0
  311. package/src/sync/socketTransport.test.ts +413 -0
  312. package/src/sync/socketTransport.ts +379 -0
  313. package/src/sync/transport.ts +76 -0
  314. package/src/testing/fakeTransport.test.ts +125 -0
  315. package/src/testing/fakeTransport.ts +206 -0
  316. package/src/testing/index.ts +18 -0
  317. package/src/types.ts +284 -0
@@ -0,0 +1,84 @@
1
+ import type {SyncStore} from "../storage/store";
2
+ import type {SyncDelta} from "../types";
3
+ import {getCursor, setCursor} from "./cursor";
4
+
5
+ export interface ApplyDeltaResult {
6
+ /** True when the delta changed local entity state (false = idempotent skip). */
7
+ applied: boolean;
8
+ /**
9
+ * True when the delta's seq jumped past cursor + 1 (measured BEFORE
10
+ * applying). A reconcile hint, not an error: permission-filtered deltas
11
+ * legitimately skip seqs, so downstream rate-limits the reconcile.
12
+ */
13
+ seqJump: boolean;
14
+ }
15
+
16
+ /**
17
+ * Apply a server delta to the local store, idempotently:
18
+ *
19
+ * - a delta at or below the entity's applied seq is skipped (duplicate /
20
+ * out-of-order delivery);
21
+ * - an entity with a pending outbox mutation is never overwritten — its
22
+ * optimistic state is protected until conflict resolution decides;
23
+ * - create/update writes data + seq; tombstones set `deleted: true` (keeping
24
+ * the last known data for conflict UIs);
25
+ * - the cursor for `delta.stream` advances in every case (including skips), so
26
+ * a skipped delta is never re-fetched on catch-up.
27
+ */
28
+ export const applyDelta = ({
29
+ store,
30
+ delta,
31
+ now,
32
+ }: {
33
+ store: SyncStore;
34
+ delta: SyncDelta;
35
+ now?: () => string;
36
+ }): ApplyDeltaResult =>
37
+ // E4: one transaction per delta — the entity upsert and cursor advance land
38
+ // as a single store commit (one listener notification, one autosave
39
+ // attempt) instead of two, and the two writes can never be observed
40
+ // half-applied by a listener firing between them.
41
+ store.raw.transaction(() => {
42
+ // C1: never advance the cursor past the stream's stable frontier. A delta can
43
+ // arrive for seq N while N-1's claim is still uncommitted (out-of-commit-order);
44
+ // clamping to min(seq, frontierSeq) means the cursor never skips the still-pending
45
+ // hole. Older servers omit frontierSeq — treat it as the delta's own seq (no clamp).
46
+ const frontier = typeof delta.frontierSeq === "number" ? delta.frontierSeq : delta.seq;
47
+ const cursorTarget = Math.min(delta.seq, frontier);
48
+ const seqJump = delta.seq > getCursor({store, stream: delta.stream}) + 1;
49
+ const advanceCursor = (): void => {
50
+ setCursor({now, seq: cursorTarget, store, stream: delta.stream});
51
+ };
52
+
53
+ const existing = store.getEntity({collection: delta.collection, id: delta.id});
54
+ if (existing && delta.seq <= existing.seq) {
55
+ advanceCursor();
56
+ return {applied: false, seqJump};
57
+ }
58
+ if (existing?.pendingMutationId) {
59
+ store.markNeedsRepair({
60
+ collection: delta.collection,
61
+ entityId: delta.id,
62
+ missedSeq: delta.seq,
63
+ stream: delta.stream,
64
+ });
65
+ advanceCursor();
66
+ return {applied: false, seqJump};
67
+ }
68
+
69
+ const deleted = delta.deleted === true || delta.method === "delete";
70
+ store.upsertEntity({
71
+ collection: delta.collection,
72
+ // Tombstone deltas omit data; keep the last known payload for conflict UIs.
73
+ data: delta.data !== undefined ? delta.data : (existing?.data ?? null),
74
+ deleted,
75
+ id: delta.id,
76
+ pendingMutationId: "",
77
+ seq: delta.seq,
78
+ // C2: record the stream so leave-purge can drop this entity in O(stream).
79
+ stream: delta.stream,
80
+ });
81
+ store.clearNeedsRepair({collection: delta.collection, entityId: delta.id});
82
+ advanceCursor();
83
+ return {applied: true, seqJump};
84
+ });
@@ -0,0 +1,161 @@
1
+ import {describe, expect, it} from "bun:test";
2
+
3
+ import {createSyncStore, type SyncStore} from "../storage/store";
4
+ import {applyRepairedEntity, repairMarkedEntities} from "./entityRepair";
5
+
6
+ const STREAM = "todos|owner:u1";
7
+
8
+ const makeStore = (): SyncStore => createSyncStore({collections: ["todos"]});
9
+
10
+ describe("entityRepair", () => {
11
+ it("marks and repairs an entity after a skipped delta", async () => {
12
+ const store = makeStore();
13
+ store.upsertEntity({
14
+ collection: "todos",
15
+ data: {title: "Optimistic"},
16
+ id: "t1",
17
+ pendingMutationId: "m1",
18
+ seq: 1,
19
+ });
20
+ store.markNeedsRepair({
21
+ collection: "todos",
22
+ entityId: "t1",
23
+ missedSeq: 4,
24
+ stream: STREAM,
25
+ });
26
+ store.upsertEntity({
27
+ collection: "todos",
28
+ data: {title: "Optimistic"},
29
+ id: "t1",
30
+ pendingMutationId: "",
31
+ seq: 1,
32
+ });
33
+
34
+ const repaired = await repairMarkedEntities({
35
+ channel: {
36
+ fetchEntities: async () => ({
37
+ entities: [{data: {title: "Server truth"}, deleted: false, id: "t1", seq: 4}],
38
+ }),
39
+ },
40
+ collection: "todos",
41
+ entityIds: ["t1"],
42
+ store,
43
+ });
44
+
45
+ expect(repaired).toBe(1);
46
+ expect(store.getEntity({collection: "todos", id: "t1"})).toEqual({
47
+ data: {title: "Server truth"},
48
+ deleted: false,
49
+ id: "t1",
50
+ pendingMutationId: undefined,
51
+ seq: 4,
52
+ stream: STREAM,
53
+ });
54
+ expect(store.hasNeedsRepair({collection: "todos", entityId: "t1"})).toBe(false);
55
+ });
56
+
57
+ it("does not overwrite entities that still have a pendingMutationId", async () => {
58
+ const store = makeStore();
59
+ store.upsertEntity({
60
+ collection: "todos",
61
+ data: {title: "Optimistic"},
62
+ id: "t1",
63
+ pendingMutationId: "m1",
64
+ seq: 1,
65
+ });
66
+ store.markNeedsRepair({
67
+ collection: "todos",
68
+ entityId: "t1",
69
+ missedSeq: 4,
70
+ stream: STREAM,
71
+ });
72
+
73
+ const repaired = await repairMarkedEntities({
74
+ channel: {
75
+ fetchEntities: async () => ({
76
+ entities: [{data: {title: "Server truth"}, deleted: false, id: "t1", seq: 4}],
77
+ }),
78
+ },
79
+ collection: "todos",
80
+ entityIds: ["t1"],
81
+ store,
82
+ });
83
+
84
+ expect(repaired).toBe(0);
85
+ expect(store.getEntity({collection: "todos", id: "t1"})).toEqual({
86
+ data: {title: "Optimistic"},
87
+ deleted: false,
88
+ id: "t1",
89
+ pendingMutationId: "m1",
90
+ seq: 1,
91
+ stream: undefined,
92
+ });
93
+ // Mark kept so a later pass (after the pending mutation resolves) can repair.
94
+ expect(store.hasNeedsRepair({collection: "todos", entityId: "t1"})).toBe(true);
95
+ });
96
+
97
+ // A mark the server can never satisfy (hard-deleted doc, permission-filtered doc,
98
+ // or a client-minted id whose create never landed) used to stay marked forever, so
99
+ // every reconcile re-fetched it and held isSyncing high for the whole pass.
100
+ it("clears marks for ids the server does not return", async () => {
101
+ const store = makeStore();
102
+ store.markNeedsRepair({
103
+ collection: "todos",
104
+ entityId: "missing-on-server",
105
+ missedSeq: 7,
106
+ stream: STREAM,
107
+ });
108
+
109
+ const repaired = await repairMarkedEntities({
110
+ channel: {fetchEntities: async () => ({entities: []})},
111
+ collection: "todos",
112
+ store,
113
+ });
114
+
115
+ expect(repaired).toBe(0);
116
+ expect(store.hasNeedsRepair({collection: "todos", entityId: "missing-on-server"})).toBe(false);
117
+ expect(store.listNeedsRepair()).toHaveLength(0);
118
+ });
119
+
120
+ it("does not refetch ids the server already declined to return", async () => {
121
+ const store = makeStore();
122
+ store.markNeedsRepair({
123
+ collection: "todos",
124
+ entityId: "missing-on-server",
125
+ missedSeq: 7,
126
+ stream: STREAM,
127
+ });
128
+ const requestedIds: string[][] = [];
129
+ const channel = {
130
+ fetchEntities: async ({ids}: {collection: string; ids: string[]}) => {
131
+ requestedIds.push(ids);
132
+ return {entities: []};
133
+ },
134
+ };
135
+
136
+ await repairMarkedEntities({channel, collection: "todos", store});
137
+ await repairMarkedEntities({channel, collection: "todos", store});
138
+
139
+ expect(requestedIds).toEqual([["missing-on-server"]]);
140
+ });
141
+
142
+ it("applyRepairedEntity applies tombstones from the server", () => {
143
+ const store = makeStore();
144
+ store.markNeedsRepair({
145
+ collection: "todos",
146
+ entityId: "t1",
147
+ missedSeq: 9,
148
+ stream: STREAM,
149
+ });
150
+ applyRepairedEntity({
151
+ collection: "todos",
152
+ entity: {data: null, deleted: true, id: "t1", seq: 9},
153
+ store,
154
+ stream: STREAM,
155
+ });
156
+ const entity = store.getEntity({collection: "todos", id: "t1"});
157
+ expect(entity?.deleted).toBe(true);
158
+ expect(entity?.seq).toBe(9);
159
+ expect(store.listEntities({collection: "todos"})).toHaveLength(0);
160
+ });
161
+ });
@@ -0,0 +1,124 @@
1
+ import type {SyncStore} from "../storage/store";
2
+ import type {SyncSnapshotEntity} from "../types";
3
+ import type {HttpChannel} from "./httpChannel";
4
+
5
+ /** Max ids per repair fetch (matches server cap). */
6
+ export const MAX_REPAIR_FETCH_IDS = 100;
7
+
8
+ /**
9
+ * Apply canonical server state after a pending mutation resolved without a
10
+ * server ack. Bypasses pending-protection — the outbox row is terminal and
11
+ * `pendingMutationId` was cleared before repair runs. No-ops (and keeps the
12
+ * needs-repair mark) when the entity is still pending or conflicted so a
13
+ * reconcile-time repair pass cannot clobber optimistic local state.
14
+ */
15
+ export const applyRepairedEntity = ({
16
+ store,
17
+ collection,
18
+ stream,
19
+ entity,
20
+ }: {
21
+ store: SyncStore;
22
+ collection: string;
23
+ /**
24
+ * Stream the repaired row belongs to. Empty/absent when the mark carries no
25
+ * provenance (a terminal-nack mark for a row the server never streamed to
26
+ * this client — Task 9.11a); the existing row's stream is preserved then.
27
+ */
28
+ stream?: string;
29
+ entity: SyncSnapshotEntity;
30
+ }): boolean => {
31
+ const existing = store.getEntity({collection, id: entity.id});
32
+ // Still owned by an unresolved outbox mutation (including conflicted): the
33
+ // optimistic row must stay until the user resolves. Leave the needs-repair
34
+ // mark so a later pass (after release) can apply canonical server state.
35
+ if (existing?.pendingMutationId) {
36
+ return false;
37
+ }
38
+ store.upsertEntity({
39
+ collection,
40
+ data: entity.data,
41
+ deleted: entity.deleted,
42
+ id: entity.id,
43
+ pendingMutationId: "",
44
+ seq: entity.seq,
45
+ stream: stream || undefined,
46
+ });
47
+ store.clearNeedsRepair({collection, entityId: entity.id});
48
+ return true;
49
+ };
50
+
51
+ /**
52
+ * Fetch current server state for marked entities and overwrite local rows.
53
+ * No-ops when the channel is unavailable or nothing is marked.
54
+ *
55
+ * Entities that still carry a `pendingMutationId` are left marked and
56
+ * untouched — reconcile marks them when a snapshot page is skipped for
57
+ * pending protection, but repair must wait until the outbox row is terminal
58
+ * (see {@link applyRepairedEntity}).
59
+ *
60
+ * Every other requested id is unmarked, whether or not the server returned it.
61
+ * An id the server declines to return (hard-deleted, permission-filtered, or a
62
+ * client-minted id whose create never landed) has no server state to repair to,
63
+ * so keeping the mark would make every later reconcile re-fetch it forever —
64
+ * holding `isSyncing` high and growing the request set without bound.
65
+ */
66
+ export const repairMarkedEntities = async ({
67
+ store,
68
+ channel,
69
+ collection,
70
+ entityIds,
71
+ }: {
72
+ store: SyncStore;
73
+ channel: Pick<HttpChannel, "fetchEntities">;
74
+ collection: string;
75
+ entityIds?: string[];
76
+ }): Promise<number> => {
77
+ // Snapshot the marks once: resolving each response entity's stream against a live
78
+ // table scan is O(marks) per entity, which dominates a large repair pass.
79
+ const streamByEntityId = new Map<string, string>();
80
+ for (const row of store.listNeedsRepair()) {
81
+ if (row.collection === collection) {
82
+ streamByEntityId.set(row.entityId, row.stream);
83
+ }
84
+ }
85
+
86
+ const targets = entityIds ?? [...streamByEntityId.keys()];
87
+ // Drop still-pending ids from this pass entirely (do not fetch, do not clear
88
+ // their marks). Reconcile ends with repairAllMarkedEntities; without this
89
+ // filter a reconnect would overwrite optimistic conflict state with server.
90
+ const ids = targets.filter((id) => {
91
+ if (!streamByEntityId.has(id)) {
92
+ return false;
93
+ }
94
+ const existing = store.getEntity({collection, id});
95
+ return !existing?.pendingMutationId;
96
+ });
97
+ if (ids.length === 0) {
98
+ return 0;
99
+ }
100
+
101
+ let repaired = 0;
102
+ for (let i = 0; i < ids.length; i += MAX_REPAIR_FETCH_IDS) {
103
+ const chunk = ids.slice(i, i + MAX_REPAIR_FETCH_IDS);
104
+ const response = await channel.fetchEntities({collection, ids: chunk});
105
+ const returned = new Set<string>();
106
+ for (const entity of response.entities) {
107
+ returned.add(entity.id);
108
+ // A mark with no stream provenance (terminal-nack mark for a row the
109
+ // server never streamed here — Task 9.11a) still repairs: fall back to the
110
+ // local row's stream, and preserve whatever is there when both are empty.
111
+ const stream =
112
+ streamByEntityId.get(entity.id) || store.getEntity({collection, id: entity.id})?.stream;
113
+ if (applyRepairedEntity({collection, entity, store, stream})) {
114
+ repaired += 1;
115
+ }
116
+ }
117
+ for (const id of chunk) {
118
+ if (!returned.has(id)) {
119
+ store.clearNeedsRepair({collection, entityId: id});
120
+ }
121
+ }
122
+ }
123
+ return repaired;
124
+ };
@@ -0,0 +1,265 @@
1
+ import {describe, expect, it} from "bun:test";
2
+
3
+ import type {AuthProvider} from "../types";
4
+ import {AuthRequiredError, createHttpChannel, type FetchLike} from "./httpChannel";
5
+
6
+ const authProvider: Pick<AuthProvider, "getToken"> = {
7
+ getToken: async () => "token-123",
8
+ };
9
+
10
+ interface RecordedRequest {
11
+ input: string;
12
+ init?: RequestInit;
13
+ }
14
+
15
+ const makeFetch = (
16
+ responder: (input: string, init?: RequestInit) => Response | Promise<Response>
17
+ ): {fetchImpl: FetchLike; requests: RecordedRequest[]} => {
18
+ const requests: RecordedRequest[] = [];
19
+ const fetchImpl: FetchLike = async (input, init) => {
20
+ requests.push({init, input});
21
+ return responder(input, init);
22
+ };
23
+ return {fetchImpl, requests};
24
+ };
25
+
26
+ const headersOf = (request: RecordedRequest | undefined): Record<string, string> =>
27
+ (request?.init?.headers ?? {}) as Record<string, string>;
28
+
29
+ const json = (body: unknown, status = 200): Response =>
30
+ new Response(JSON.stringify(body), {
31
+ headers: {"Content-Type": "application/json"},
32
+ status,
33
+ });
34
+
35
+ describe("createHttpChannel", () => {
36
+ describe("fetchSnapshotPage", () => {
37
+ it("requests the snapshot with bearer token, stream, cursor, and limit", async () => {
38
+ const page = {
39
+ cursor: 5,
40
+ entities: [],
41
+ frontierSeq: 5,
42
+ hasMore: false,
43
+ oldestRetainedSeq: 0,
44
+ stream: "todos|owner:u1",
45
+ };
46
+ const {fetchImpl, requests} = makeFetch(() => json(page));
47
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
48
+ const result = await channel.fetchSnapshotPage({
49
+ cursor: 3,
50
+ limit: 10,
51
+ stream: "todos|owner:u1",
52
+ });
53
+ expect(result).toEqual(page);
54
+ expect(requests[0]?.input).toBe(
55
+ "http://api/sync/snapshot?cursor=3&stream=todos%7Cowner%3Au1&limit=10"
56
+ );
57
+ expect(headersOf(requests[0]).Authorization).toBe("Bearer token-123");
58
+ });
59
+
60
+ it("forwards the legacyCursor token (C3) when provided", async () => {
61
+ const page = {
62
+ cursor: 0,
63
+ entities: [],
64
+ frontierSeq: 0,
65
+ hasMore: true,
66
+ legacyCursor: "abc123",
67
+ oldestRetainedSeq: 0,
68
+ stream: "todos|owner:u1",
69
+ };
70
+ const {fetchImpl, requests} = makeFetch(() => json(page));
71
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
72
+ const result = await channel.fetchSnapshotPage({
73
+ cursor: 0,
74
+ legacyCursor: "prev-id",
75
+ stream: "todos|owner:u1",
76
+ });
77
+ expect(result.legacyCursor).toBe("abc123");
78
+ expect(requests[0]?.input).toContain("legacyCursor=prev-id");
79
+ });
80
+
81
+ it("omits the limit parameter and the auth header when absent", async () => {
82
+ const {fetchImpl, requests} = makeFetch(() =>
83
+ json({
84
+ cursor: 0,
85
+ entities: [],
86
+ frontierSeq: 0,
87
+ hasMore: false,
88
+ oldestRetainedSeq: 0,
89
+ stream: "todos|owner:u1",
90
+ })
91
+ );
92
+ const channel = createHttpChannel({
93
+ authProvider: {getToken: async () => null},
94
+ baseUrl: "http://api",
95
+ fetchImpl,
96
+ });
97
+ await channel.fetchSnapshotPage({cursor: 0, stream: "todos|owner:u1"});
98
+ expect(requests[0]?.input).toBe(
99
+ "http://api/sync/snapshot?cursor=0&stream=todos%7Cowner%3Au1"
100
+ );
101
+ expect(headersOf(requests[0]).Authorization).toBeUndefined();
102
+ });
103
+
104
+ it("rejects with AuthRequiredError on 401", async () => {
105
+ const {fetchImpl} = makeFetch(() => json({}, 401));
106
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
107
+ await expect(
108
+ channel.fetchSnapshotPage({cursor: 0, stream: "todos|owner:u1"})
109
+ ).rejects.toThrow(AuthRequiredError);
110
+ });
111
+
112
+ it("rejects on non-ok statuses", async () => {
113
+ const {fetchImpl} = makeFetch(() => json({}, 404));
114
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
115
+ await expect(
116
+ channel.fetchSnapshotPage({cursor: 0, stream: "todos|owner:u1"})
117
+ ).rejects.toThrow("status 404");
118
+ });
119
+
120
+ it("propagates network errors", async () => {
121
+ const {fetchImpl} = makeFetch(() => {
122
+ throw new Error("offline");
123
+ });
124
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
125
+ await expect(
126
+ channel.fetchSnapshotPage({cursor: 0, stream: "todos|owner:u1"})
127
+ ).rejects.toThrow("offline");
128
+ });
129
+ });
130
+
131
+ describe("fetchStreams", () => {
132
+ it("GETs /sync/streams and returns the membership set", async () => {
133
+ const streams = [
134
+ {collection: "todos", stream: "todos|owner:u1"},
135
+ {collection: "todos", stream: "todos|tenant:org1"},
136
+ ];
137
+ const {fetchImpl, requests} = makeFetch(() => json({streams}));
138
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
139
+ await expect(channel.fetchStreams()).resolves.toEqual(streams);
140
+ expect(requests[0]?.input).toBe("http://api/sync/streams");
141
+ expect(headersOf(requests[0]).Authorization).toBe("Bearer token-123");
142
+ });
143
+
144
+ it("returns an empty array when the body has no streams field", async () => {
145
+ const {fetchImpl} = makeFetch(() => json({}));
146
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
147
+ await expect(channel.fetchStreams()).resolves.toEqual([]);
148
+ });
149
+
150
+ it("rejects with AuthRequiredError on 401 (INV-2: never treated as a leave)", async () => {
151
+ const {fetchImpl} = makeFetch(() => json({}, 401));
152
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
153
+ await expect(channel.fetchStreams()).rejects.toBeInstanceOf(AuthRequiredError);
154
+ });
155
+
156
+ it("rejects on non-ok statuses", async () => {
157
+ const {fetchImpl} = makeFetch(() => json({}, 500));
158
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
159
+ await expect(channel.fetchStreams()).rejects.toThrow("status 500");
160
+ });
161
+ });
162
+
163
+ describe("sendMutation", () => {
164
+ const mutation = {
165
+ collection: "todos",
166
+ data: {title: "hi"},
167
+ id: "t1",
168
+ mutationId: "m1",
169
+ operation: "create" as const,
170
+ };
171
+
172
+ it("POSTs the mutation and maps 200 {ack} to an ack result", async () => {
173
+ const ack = {id: "t1", mutationId: "m1", seq: 7};
174
+ const {fetchImpl, requests} = makeFetch(() => json({ack}));
175
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
176
+ const result = await channel.sendMutation(mutation);
177
+ expect(result).toEqual({ack, type: "ack"});
178
+ expect(requests[0]?.input).toBe("http://api/sync/mutate");
179
+ expect(requests[0]?.init?.method).toBe("POST");
180
+ expect(JSON.parse(String(requests[0]?.init?.body))).toEqual(mutation);
181
+ const headers = requests[0]?.init?.headers as Record<string, string>;
182
+ expect(headers["Content-Type"]).toBe("application/json");
183
+ });
184
+
185
+ it.each([
186
+ [409, "conflict"],
187
+ [403, "unauthorized"],
188
+ [422, "validation"],
189
+ [500, "error"],
190
+ ] as const)("maps %i {nack} bodies to nack results", async (status, code) => {
191
+ const nack = {code, mutationId: "m1", serverSeq: 3};
192
+ const {fetchImpl} = makeFetch(() => json({nack}, status));
193
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
194
+ const result = await channel.sendMutation(mutation);
195
+ expect(result).toEqual({nack, type: "nack"});
196
+ });
197
+
198
+ it("rejects with AuthRequiredError on 401", async () => {
199
+ const {fetchImpl} = makeFetch(() => json({}, 401));
200
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
201
+ await expect(channel.sendMutation(mutation)).rejects.toThrow(AuthRequiredError);
202
+ });
203
+
204
+ it("rejects when an error status has no nack body", async () => {
205
+ const {fetchImpl} = makeFetch(() => json({}, 500));
206
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
207
+ await expect(channel.sendMutation(mutation)).rejects.toThrow("status 500");
208
+ });
209
+
210
+ it("rejects on non-JSON responses", async () => {
211
+ const {fetchImpl} = makeFetch(() => new Response("<html>bad gateway</html>", {status: 502}));
212
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
213
+ await expect(channel.sendMutation(mutation)).rejects.toThrow("non-JSON");
214
+ });
215
+
216
+ it("rejects when a 200 body carries neither ack nor nack", async () => {
217
+ const {fetchImpl} = makeFetch(() => json({}));
218
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
219
+ await expect(channel.sendMutation(mutation)).rejects.toThrow("status 200");
220
+ });
221
+ });
222
+
223
+ it("uses global fetch when no fetchImpl is provided (network error path)", async () => {
224
+ const channel = createHttpChannel({
225
+ authProvider,
226
+ // Port 9 (discard) is never listening locally; fetch fails fast.
227
+ baseUrl: "http://127.0.0.1:9",
228
+ });
229
+ await expect(
230
+ channel.fetchSnapshotPage({cursor: 0, stream: "todos|owner:u1"})
231
+ ).rejects.toThrow();
232
+ });
233
+
234
+ describe("fetchKeyMaterial", () => {
235
+ it("fetches GET /sync/key with the bearer token and returns the material", async () => {
236
+ const {fetchImpl, requests} = makeFetch(() => json({keyMaterial: "material-abc"}));
237
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
238
+ await expect(channel.fetchKeyMaterial()).resolves.toBe("material-abc");
239
+ expect(requests[0].input).toBe("http://api/sync/key");
240
+ expect(headersOf(requests[0]).Authorization).toBe("Bearer token-123");
241
+ });
242
+
243
+ it("rejects with AuthRequiredError on 401", async () => {
244
+ const {fetchImpl} = makeFetch(() => json({}, 401));
245
+ const channel = createHttpChannel({authProvider, baseUrl: "http://api", fetchImpl});
246
+ await expect(channel.fetchKeyMaterial()).rejects.toBeInstanceOf(AuthRequiredError);
247
+ });
248
+
249
+ it("rejects on non-ok statuses and missing keyMaterial", async () => {
250
+ const bad = createHttpChannel({
251
+ authProvider,
252
+ baseUrl: "http://api",
253
+ fetchImpl: makeFetch(() => json({}, 500)).fetchImpl,
254
+ });
255
+ await expect(bad.fetchKeyMaterial()).rejects.toThrow(/status 500/);
256
+
257
+ const empty = createHttpChannel({
258
+ authProvider,
259
+ baseUrl: "http://api",
260
+ fetchImpl: makeFetch(() => json({})).fetchImpl,
261
+ });
262
+ await expect(empty.fetchKeyMaterial()).rejects.toThrow(/missing keyMaterial/);
263
+ });
264
+ });
265
+ });