@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,379 @@
1
+ import {io, type Socket} from "socket.io-client";
2
+
3
+ import type {
4
+ AuthProvider,
5
+ SyncAck,
6
+ SyncDelta,
7
+ SyncMutateBatchRequest,
8
+ SyncMutateRequest,
9
+ SyncNack,
10
+ } from "../types";
11
+ import {
12
+ DEFAULT_MUTATION_TIMEOUT_MS,
13
+ type SendMutationBatchResult,
14
+ type SendMutationResult,
15
+ type SyncTransport,
16
+ type TransportStatus,
17
+ } from "./transport";
18
+
19
+ /**
20
+ * Grace period to wait for EITHER a `sync:mutateBatch` ack callback OR the
21
+ * `sync:batchReceived` receipt before treating the server as not supporting
22
+ * the batch event at all. Socket.io silently drops emits to event names with
23
+ * no registered handler — there is no error to catch, only silence — so this
24
+ * must be much shorter than the full batch timeout or every batch send
25
+ * against an old server would stall for that long. Once the receipt DOES
26
+ * arrive within this window, the server is known to support batching (it's
27
+ * just slow) and the client waits the full {@link batchTimeoutMs} instead of
28
+ * falling back (FIX 5).
29
+ */
30
+ export const BATCH_UNSUPPORTED_GRACE_MS = 2_000;
31
+
32
+ /**
33
+ * Compute the batch send timeout once a `sync:batchReceived` receipt has
34
+ * confirmed the server is processing (as opposed to silent/unsupported): the
35
+ * existing per-mutation timeout scaled by chunk size, so a large batch isn't
36
+ * timed out prematurely just because it's slower than a single mutation
37
+ * (FIX 5).
38
+ */
39
+ export const batchTimeoutMs = (mutationCount: number, perMutationTimeoutMs: number): number =>
40
+ Math.max(perMutationTimeoutMs, mutationCount * 1_000);
41
+
42
+ export interface SocketTransportConfig {
43
+ /** Server origin, e.g. "http://localhost:4000". */
44
+ baseUrl: string;
45
+ /** Token source; `getToken()` is called fresh on every connection attempt. */
46
+ authProvider: Pick<AuthProvider, "getToken">;
47
+ /** How long to wait for a mutation ack/nack before rejecting (default 15s). */
48
+ timeoutMs?: number;
49
+ /** Grace period before a batch send is treated as unsupported (default 2s). */
50
+ batchUnsupportedGraceMs?: number;
51
+ }
52
+
53
+ interface PendingMutation {
54
+ resolve: (result: SendMutationResult) => void;
55
+ reject: (error: Error) => void;
56
+ timer: ReturnType<typeof setTimeout>;
57
+ }
58
+
59
+ /**
60
+ * Socket.io implementation of {@link SyncTransport}, speaking the server's
61
+ * sync protocol (see @terreno/api `src/sync/socketHandlers.ts`):
62
+ *
63
+ * - client emits `sync:subscribe {collections}` and `sync:mutate <request>`;
64
+ * - server replies with `sync:ack` / `sync:nack` events **and** a Socket.io
65
+ * ack callback carrying `{ack}` / `{nack}` — replies are correlated by
66
+ * `mutationId` and the first to arrive settles the pending promise;
67
+ * - server pushes `sync:delta` events for subscribed streams.
68
+ *
69
+ * The handshake token is resolved via `authProvider.getToken()` inside the
70
+ * Socket.io `auth` callback, which runs on **every** connection attempt — the
71
+ * token is never cached, so session refreshes are picked up transparently on
72
+ * reconnect. The raw provider token is sent with a `Bearer ` prefix (unless the
73
+ * provider already included one): the server's legacy JWT socket validator
74
+ * (`@thream/socketio-jwt` via @terreno/api `createSocketAuthMiddleware`)
75
+ * requires that exact format, and the Better Auth validator strips an optional
76
+ * prefix — so prefixing is correct for both. Reconnection is enabled; on every
77
+ * (re)connect the transport re-emits `sync:subscribe` for all previously
78
+ * subscribed collections because server-side subscription state is
79
+ * per-connection.
80
+ */
81
+ export const createSocketTransport = ({
82
+ baseUrl,
83
+ authProvider,
84
+ timeoutMs = DEFAULT_MUTATION_TIMEOUT_MS,
85
+ batchUnsupportedGraceMs = BATCH_UNSUPPORTED_GRACE_MS,
86
+ }: SocketTransportConfig): SyncTransport => {
87
+ const deltaListeners = new Set<(delta: SyncDelta) => void>();
88
+ const statusListeners = new Set<(status: TransportStatus) => void>();
89
+ const pending = new Map<string, PendingMutation>();
90
+ const pendingBatches = new Map<
91
+ string,
92
+ {
93
+ resolve: (result: SendMutationBatchResult) => void;
94
+ reject: (error: Error) => void;
95
+ /** Cleared once a `sync:batchReceived` receipt arrives (FIX 5). */
96
+ graceTimer?: ReturnType<typeof setTimeout>;
97
+ /** Armed once the receipt lands, replacing the grace timer (FIX 5). */
98
+ fullTimer?: ReturnType<typeof setTimeout>;
99
+ /** Removes this batch's `sync:batchReceived` listener (FIX 5). */
100
+ offReceived: () => void;
101
+ }
102
+ >();
103
+ let nextBatchId = 1;
104
+ const subscribed = new Set<string>();
105
+
106
+ const socket: Socket = io(baseUrl, {
107
+ auth: (callback) => {
108
+ // Called per connection attempt; never cache the token across attempts.
109
+ // The server's socket auth chain expects "Bearer <token>" (matching the
110
+ // Authorization header format the HTTP channel sends).
111
+ void authProvider.getToken().then(
112
+ (token) =>
113
+ callback(token ? {token: token.startsWith("Bearer ") ? token : `Bearer ${token}`} : {}),
114
+ () => callback({})
115
+ );
116
+ },
117
+ autoConnect: false,
118
+ reconnection: true,
119
+ // Start with polling so dev server restarts don't fail the initial
120
+ // websocket-only handshake; Socket.io upgrades once connected.
121
+ transports: ["polling", "websocket"],
122
+ });
123
+
124
+ const settle = (mutationId: string, result: SendMutationResult): void => {
125
+ const entry = pending.get(mutationId);
126
+ if (!entry) {
127
+ return;
128
+ }
129
+ pending.delete(mutationId);
130
+ clearTimeout(entry.timer);
131
+ entry.resolve(result);
132
+ };
133
+
134
+ const rejectAllPending = (reason: string): void => {
135
+ for (const [mutationId, entry] of pending) {
136
+ pending.delete(mutationId);
137
+ clearTimeout(entry.timer);
138
+ entry.reject(new Error(reason));
139
+ }
140
+ for (const [batchId, entry] of pendingBatches) {
141
+ pendingBatches.delete(batchId);
142
+ if (entry.graceTimer !== undefined) {
143
+ clearTimeout(entry.graceTimer);
144
+ }
145
+ if (entry.fullTimer !== undefined) {
146
+ clearTimeout(entry.fullTimer);
147
+ }
148
+ entry.offReceived();
149
+ entry.reject(new Error(reason));
150
+ }
151
+ };
152
+
153
+ const notifyStatus = (connected: boolean, authExpired?: boolean): void => {
154
+ for (const listener of statusListeners) {
155
+ listener(authExpired ? {authExpired: true, connected} : {connected});
156
+ }
157
+ };
158
+
159
+ // D1: the server's session re-validation sweep emits `sync:auth-expired`
160
+ // immediately before calling `socket.disconnect(true)` — this flag survives just
161
+ // long enough for the subsequent `disconnect` handler to tag its status
162
+ // notification, then resets so a later, unrelated disconnect isn't misattributed.
163
+ let pendingAuthExpired = false;
164
+
165
+ socket.on("sync:delta", (delta: SyncDelta) => {
166
+ for (const listener of deltaListeners) {
167
+ listener(delta);
168
+ }
169
+ });
170
+ socket.on("sync:ack", (ack: SyncAck) => {
171
+ settle(ack.mutationId, {ack, type: "ack"});
172
+ });
173
+ socket.on("sync:nack", (nack: SyncNack) => {
174
+ settle(nack.mutationId, {nack, type: "nack"});
175
+ });
176
+ socket.on("sync:auth-expired", () => {
177
+ pendingAuthExpired = true;
178
+ });
179
+ // D1: Socket.io's own automatic background reconnection (reconnection: true,
180
+ // configured below) re-runs the handshake without going through this module's
181
+ // connect() promise — so an auth rejection on a RECONNECT attempt (token expired
182
+ // or session revoked while offline, discovered only when the client comes back)
183
+ // must be observed here, not just on the initial connect(). Any auth-shaped
184
+ // rejection (the server's auth middleware `next(error)`, matching the
185
+ // `UnauthorizedError` data shape from @thream/socketio-jwt / socketAuth.ts) maps
186
+ // into the same auth-pause path as an explicit sync:auth-expired disconnect.
187
+ socket.on("connect_error", (error: Error & {data?: {type?: string}}) => {
188
+ if (error?.data?.type === "UnauthorizedError") {
189
+ notifyStatus(false, true);
190
+ }
191
+ });
192
+ socket.on("connect", () => {
193
+ // Server-side subscriptions are per-connection: re-subscribe on reconnect.
194
+ if (subscribed.size > 0) {
195
+ socket.emit("sync:subscribe", {collections: [...subscribed]});
196
+ }
197
+ notifyStatus(true);
198
+ });
199
+ socket.on("disconnect", () => {
200
+ // Replies for in-flight mutations will never arrive on this connection;
201
+ // reject now so the replay coordinator can requeue instead of waiting out
202
+ // the full timeout.
203
+ rejectAllPending("Socket disconnected before the mutation was acknowledged");
204
+ const authExpired = pendingAuthExpired;
205
+ pendingAuthExpired = false;
206
+ notifyStatus(false, authExpired);
207
+ });
208
+
209
+ const connect = (): Promise<void> =>
210
+ new Promise<void>((resolve, reject) => {
211
+ if (socket.connected) {
212
+ resolve();
213
+ return;
214
+ }
215
+ const cleanup = (): void => {
216
+ socket.off("connect", onConnect);
217
+ socket.off("connect_error", onConnectError);
218
+ };
219
+ const onConnect = (): void => {
220
+ cleanup();
221
+ resolve();
222
+ };
223
+ const onConnectError = (error: Error): void => {
224
+ // Reject the initial connect() promise; background reconnection keeps
225
+ // retrying and a later success surfaces through onStatusChange.
226
+ cleanup();
227
+ reject(error);
228
+ };
229
+ socket.once("connect", onConnect);
230
+ socket.once("connect_error", onConnectError);
231
+ socket.connect();
232
+ });
233
+
234
+ const disconnect = (): void => {
235
+ socket.disconnect();
236
+ rejectAllPending("Transport disconnected");
237
+ };
238
+
239
+ const subscribe = (collections: string[]): void => {
240
+ for (const collection of collections) {
241
+ subscribed.add(collection);
242
+ }
243
+ // Only emit when connected; the connect handler (re)subscribes otherwise —
244
+ // Socket.io would buffer a disconnected emit and duplicate the subscribe.
245
+ if (socket.connected && collections.length > 0) {
246
+ socket.emit("sync:subscribe", {collections});
247
+ }
248
+ };
249
+
250
+ const sendMutation = (request: SyncMutateRequest): Promise<SendMutationResult> =>
251
+ new Promise<SendMutationResult>((resolve, reject) => {
252
+ const timer = setTimeout(() => {
253
+ pending.delete(request.mutationId);
254
+ reject(
255
+ new Error(`Timed out after ${timeoutMs}ms waiting for ack/nack: ${request.mutationId}`)
256
+ );
257
+ }, timeoutMs);
258
+ pending.set(request.mutationId, {reject, resolve, timer});
259
+ // The server both emits sync:ack/sync:nack and invokes this Socket.io
260
+ // ack callback; whichever arrives first settles (settle is idempotent).
261
+ socket.emit("sync:mutate", request, (response: {ack?: SyncAck; nack?: SyncNack}) => {
262
+ if (response?.ack) {
263
+ settle(request.mutationId, {ack: response.ack, type: "ack"});
264
+ } else if (response?.nack) {
265
+ settle(request.mutationId, {nack: response.nack, type: "nack"});
266
+ }
267
+ });
268
+ });
269
+
270
+ const sendMutationBatch = (
271
+ request: {mutations: SyncMutateRequest[]} & SyncMutateBatchRequest
272
+ ): Promise<SendMutationBatchResult> =>
273
+ new Promise<SendMutationBatchResult>((resolve, reject) => {
274
+ const batchId = String(nextBatchId++);
275
+
276
+ // FIX 5: a server without a sync:mutateBatch handler never invokes the
277
+ // ack callback NOR emits sync:batchReceived (Socket.io silently drops
278
+ // emits to unregistered events) — a short grace timeout with NO
279
+ // receipt landing is the ONLY signal for "unsupported". Once a
280
+ // receipt (or the final ack callback, whichever arrives first) lands
281
+ // within that window, the server is known to support batching and is
282
+ // just slow — the full batch timeout (proportional to chunk size)
283
+ // takes over instead of resolving `unsupported` prematurely.
284
+ const cleanup = (): void => {
285
+ pendingBatches.delete(batchId);
286
+ socket.off("sync:batchReceived", onReceived);
287
+ };
288
+ const finish = (result: SendMutationBatchResult): void => {
289
+ cleanup();
290
+ resolve(result);
291
+ };
292
+ const armFullTimer = (): void => {
293
+ const entry = pendingBatches.get(batchId);
294
+ if (!entry || entry.fullTimer !== undefined) {
295
+ return;
296
+ }
297
+ if (entry.graceTimer !== undefined) {
298
+ clearTimeout(entry.graceTimer);
299
+ entry.graceTimer = undefined;
300
+ }
301
+ entry.fullTimer = setTimeout(
302
+ () => {
303
+ // The server confirmed support (a receipt or ack landed) but never
304
+ // finished within the scaled batch timeout — this is a genuine
305
+ // transport failure (not "unsupported"), so reject: the
306
+ // coordinator applies its unlimited-backoff transport-failure
307
+ // path and resends the whole chunk (INV-3), rather than wrongly
308
+ // downgrading a merely-slow-but-supported server to single-sends.
309
+ cleanup();
310
+ reject(
311
+ new Error(`Timed out after the batch timeout waiting for batch ${batchId} to finish`)
312
+ );
313
+ },
314
+ batchTimeoutMs(request.mutations.length, timeoutMs)
315
+ );
316
+ };
317
+ const onReceived = ({batchId: receivedId}: {batchId?: string}): void => {
318
+ if (receivedId === batchId) {
319
+ armFullTimer();
320
+ }
321
+ };
322
+ socket.on("sync:batchReceived", onReceived);
323
+
324
+ const graceTimer = setTimeout(() => {
325
+ finish({type: "unsupported"});
326
+ }, batchUnsupportedGraceMs);
327
+ // The pendingBatches entry MUST exist before the emit: on localhost the
328
+ // server's immediate sync:batchReceived echo can round-trip fast enough
329
+ // to race this same synchronous block, and armFullTimer/the ack
330
+ // callback both look up this entry by batchId.
331
+ pendingBatches.set(batchId, {
332
+ graceTimer,
333
+ offReceived: () => socket.off("sync:batchReceived", onReceived),
334
+ reject,
335
+ resolve,
336
+ });
337
+
338
+ socket.emit(
339
+ "sync:mutateBatch",
340
+ {...request, batchId},
341
+ (response: {
342
+ results?: ({type: "ack"; ack: SyncAck} | {type: "nack"; nack: SyncNack})[];
343
+ }) => {
344
+ const entry = pendingBatches.get(batchId);
345
+ if (!entry) {
346
+ return;
347
+ }
348
+ if (entry.fullTimer !== undefined) {
349
+ clearTimeout(entry.fullTimer);
350
+ }
351
+ if (Array.isArray(response?.results)) {
352
+ finish({results: response.results, type: "results"});
353
+ } else {
354
+ finish({type: "unsupported"});
355
+ }
356
+ }
357
+ );
358
+ });
359
+
360
+ return {
361
+ connect,
362
+ disconnect,
363
+ onDelta: (callback: (delta: SyncDelta) => void): (() => void) => {
364
+ deltaListeners.add(callback);
365
+ return () => {
366
+ deltaListeners.delete(callback);
367
+ };
368
+ },
369
+ onStatusChange: (callback: (status: TransportStatus) => void): (() => void) => {
370
+ statusListeners.add(callback);
371
+ return () => {
372
+ statusListeners.delete(callback);
373
+ };
374
+ },
375
+ sendMutation,
376
+ sendMutationBatch,
377
+ subscribe,
378
+ };
379
+ };
@@ -0,0 +1,76 @@
1
+ import type {
2
+ SyncAck,
3
+ SyncDelta,
4
+ SyncMutateBatchRequest,
5
+ SyncMutateRequest,
6
+ SyncNack,
7
+ } from "../types";
8
+
9
+ /** Default time to wait for a mutation ack/nack before rejecting. */
10
+ export const DEFAULT_MUTATION_TIMEOUT_MS = 15_000;
11
+
12
+ /** Default max mutations per batch send (server also enforces this cap). */
13
+ export const DEFAULT_BATCH_SIZE = 50;
14
+
15
+ /** The server's reply to a sent mutation: accepted (ack) or rejected (nack). */
16
+ export type SendMutationResult = {type: "ack"; ack: SyncAck} | {type: "nack"; nack: SyncNack};
17
+
18
+ /**
19
+ * The server's reply to a batch send: a `results` array (see
20
+ * `SyncMutateBatchResponse`), or `unsupported` when the transport/server has no
21
+ * batch endpoint (HTTP 404, or a socket that never acks `sync:mutateBatch` within
22
+ * the timeout — Socket.io silently drops emits to unregistered events). Callers
23
+ * treat `unsupported` as a signal to set the per-connection `batchUnsupported`
24
+ * flag and fall back to single-mutation sends, never as a transport failure.
25
+ */
26
+ export type SendMutationBatchResult =
27
+ | {type: "results"; results: ({type: "ack"; ack: SyncAck} | {type: "nack"; nack: SyncNack})[]}
28
+ | {type: "unsupported"};
29
+
30
+ /** Transport connection status snapshot delivered to status listeners. */
31
+ export interface TransportStatus {
32
+ connected: boolean;
33
+ /**
34
+ * D1: set when this disconnect was caused by the server's session re-validation
35
+ * sweep (`sync:auth-expired`, emitted before `socket.disconnect(true)`) rather than
36
+ * a generic network drop. The client maps this into the existing A4 auth-pause path
37
+ * (INV-2 — no wipe, outbox intact) instead of treating it as a transient transport
38
+ * blip eligible for unlimited-retry backoff.
39
+ */
40
+ authExpired?: boolean;
41
+ }
42
+
43
+ /**
44
+ * Bidirectional sync channel between the local store and the server. The
45
+ * Socket.io implementation (`createSocketTransport`) speaks the server's
46
+ * `sync:*` event protocol; `createFakeTransport` provides a deterministic
47
+ * in-memory double for tests.
48
+ */
49
+ export interface SyncTransport {
50
+ /** Open the connection; resolves once connected, rejects on the first failure. */
51
+ connect: () => Promise<void>;
52
+ /** Close the connection and reject any in-flight mutation sends. */
53
+ disconnect: () => void;
54
+ /** Subscribe to delta streams for the given collections (idempotent server-side). */
55
+ subscribe: (collections: string[]) => void;
56
+ /**
57
+ * Send a mutation and resolve with the server's ack/nack, correlated by
58
+ * `mutationId`. Rejects when no reply arrives within the transport's
59
+ * configured timeout (default {@link DEFAULT_MUTATION_TIMEOUT_MS}) or when
60
+ * the connection drops before the reply.
61
+ */
62
+ sendMutation: (request: SyncMutateRequest) => Promise<SendMutationResult>;
63
+ /**
64
+ * Send a batch of mutations (`sync:mutateBatch`) and resolve with either the
65
+ * server's per-mutation results or `unsupported` (server has no batch handler —
66
+ * Socket.io drops emits to unregistered events, so this resolves after a short
67
+ * grace timeout rather than the full mutation timeout). Rejects on transport
68
+ * failure exactly like `sendMutation` (timeout waiting for a KNOWN-supported
69
+ * server, network error, disconnect).
70
+ */
71
+ sendMutationBatch?: (request: SyncMutateBatchRequest) => Promise<SendMutationBatchResult>;
72
+ /** Subscribe to inbound `sync:delta` events. Returns an unsubscribe function. */
73
+ onDelta: (callback: (delta: SyncDelta) => void) => () => void;
74
+ /** Subscribe to connection status changes. Returns an unsubscribe function. */
75
+ onStatusChange: (callback: (status: TransportStatus) => void) => () => void;
76
+ }
@@ -0,0 +1,125 @@
1
+ import {describe, expect, it} from "bun:test";
2
+ import type {TransportStatus} from "../sync/transport";
3
+ import type {SyncDelta} from "../types";
4
+ import {createFakeTransport} from "./fakeTransport";
5
+
6
+ const makeDelta = (overrides: Partial<SyncDelta> = {}): SyncDelta => ({
7
+ collection: "todos",
8
+ data: {title: "x"},
9
+ id: "t1",
10
+ method: "create",
11
+ seq: 1,
12
+ stream: "todos|owner:u1",
13
+ ...overrides,
14
+ });
15
+
16
+ describe("createFakeTransport", () => {
17
+ it("connect/disconnect notify status listeners once per change", async () => {
18
+ const transport = createFakeTransport();
19
+ const statuses: TransportStatus[] = [];
20
+ transport.onStatusChange((status) => statuses.push(status));
21
+ await transport.connect();
22
+ await transport.connect();
23
+ transport.disconnect();
24
+ expect(statuses).toEqual([{connected: true}, {connected: false}]);
25
+ });
26
+
27
+ it("delivers deltas to listeners and honors unsubscribe", async () => {
28
+ const transport = createFakeTransport();
29
+ const seen: SyncDelta[] = [];
30
+ const unsubscribe = transport.onDelta((delta) => seen.push(delta));
31
+ transport.deliverDelta(makeDelta());
32
+ unsubscribe();
33
+ transport.deliverDelta(makeDelta({id: "t2"}));
34
+ expect(seen).toHaveLength(1);
35
+ expect(seen[0]?.id).toBe("t1");
36
+ });
37
+
38
+ it("records subscriptions as a distinct union", () => {
39
+ const transport = createFakeTransport();
40
+ transport.subscribe(["todos"]);
41
+ transport.subscribe(["todos", "notes"]);
42
+ expect(transport.subscribedCollections.sort()).toEqual(["notes", "todos"]);
43
+ });
44
+
45
+ it("auto-acks by default with increasing seqs and request-derived ids", async () => {
46
+ const transport = createFakeTransport();
47
+ const first = await transport.sendMutation({
48
+ collection: "todos",
49
+ id: "t1",
50
+ mutationId: "m1",
51
+ operation: "create",
52
+ });
53
+ const second = await transport.sendMutation({
54
+ collection: "todos",
55
+ mutationId: "m2",
56
+ operation: "create",
57
+ });
58
+ expect(first).toEqual({ack: {id: "t1", mutationId: "m1", seq: 1}, type: "ack"});
59
+ expect(second).toEqual({ack: {id: "server-2", mutationId: "m2", seq: 2}, type: "ack"});
60
+ expect(transport.sentMutations.map((m) => m.mutationId)).toEqual(["m1", "m2"]);
61
+ });
62
+
63
+ it("respondWithAck/respondWithNack queue one-shot responses in order", async () => {
64
+ const transport = createFakeTransport();
65
+ transport.respondWithNack({code: "conflict", serverDoc: {title: "srv"}, serverSeq: 4});
66
+ transport.respondWithAck({seq: 9});
67
+ const nacked = await transport.sendMutation({
68
+ collection: "todos",
69
+ id: "t1",
70
+ mutationId: "m1",
71
+ operation: "update",
72
+ });
73
+ const acked = await transport.sendMutation({
74
+ collection: "todos",
75
+ id: "t1",
76
+ mutationId: "m2",
77
+ operation: "update",
78
+ });
79
+ expect(nacked).toEqual({
80
+ nack: {code: "conflict", mutationId: "m1", serverDoc: {title: "srv"}, serverSeq: 4},
81
+ type: "nack",
82
+ });
83
+ expect(acked).toEqual({ack: {id: "t1", mutationId: "m2", seq: 9}, type: "ack"});
84
+ });
85
+
86
+ it("respondWith supports rejecting responders and setDefaultResponder overrides", async () => {
87
+ const transport = createFakeTransport();
88
+ transport.respondWith(() => {
89
+ throw new Error("network down");
90
+ });
91
+ await expect(
92
+ transport.sendMutation({collection: "todos", id: "t1", mutationId: "m1", operation: "update"})
93
+ ).rejects.toThrow("network down");
94
+
95
+ transport.setDefaultResponder((request) => ({
96
+ nack: {code: "validation", mutationId: request.mutationId},
97
+ type: "nack",
98
+ }));
99
+ const result = await transport.sendMutation({
100
+ collection: "todos",
101
+ id: "t1",
102
+ mutationId: "m2",
103
+ operation: "update",
104
+ });
105
+ expect(result.type).toBe("nack");
106
+
107
+ transport.setDefaultResponder();
108
+ const acked = await transport.sendMutation({
109
+ collection: "todos",
110
+ id: "t1",
111
+ mutationId: "m3",
112
+ operation: "update",
113
+ });
114
+ expect(acked.type).toBe("ack");
115
+ });
116
+
117
+ it("status unsubscribe stops notifications", async () => {
118
+ const transport = createFakeTransport();
119
+ const statuses: TransportStatus[] = [];
120
+ const unsubscribe = transport.onStatusChange((status) => statuses.push(status));
121
+ unsubscribe();
122
+ transport.setConnected(true);
123
+ expect(statuses).toEqual([]);
124
+ });
125
+ });