@terreno/api 0.31.0 → 56.0.0-beta.2

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 (232) hide show
  1. package/dist/api.d.ts +10 -0
  2. package/dist/api.js +110 -361
  3. package/dist/auth.d.ts +26 -0
  4. package/dist/auth.js +121 -26
  5. package/dist/betterAuth.d.ts +5 -0
  6. package/dist/betterAuthSetup.js +23 -4
  7. package/dist/docLoader.js +12 -9
  8. package/dist/errors.d.ts +13 -0
  9. package/dist/errors.js +29 -1
  10. package/dist/index.d.ts +17 -1
  11. package/dist/index.js +29 -1
  12. package/dist/middleware.d.ts +7 -0
  13. package/dist/middleware.js +16 -1
  14. package/dist/openApiCompat.d.ts +10 -1
  15. package/dist/openApiCompat.js +115 -47
  16. package/dist/permissions.d.ts +27 -0
  17. package/dist/permissions.js +42 -1
  18. package/dist/plugins.d.ts +13 -0
  19. package/dist/plugins.js +47 -1
  20. package/dist/realtime/changeStreamWatcher.d.ts +100 -3
  21. package/dist/realtime/changeStreamWatcher.js +542 -137
  22. package/dist/realtime/realtimeApp.d.ts +2 -0
  23. package/dist/realtime/realtimeApp.js +83 -27
  24. package/dist/realtime/sessionRevalidation.d.ts +90 -0
  25. package/dist/realtime/sessionRevalidation.js +438 -0
  26. package/dist/realtime/socketAuth.d.ts +97 -0
  27. package/dist/realtime/socketAuth.js +272 -0
  28. package/dist/realtime/socketUser.d.ts +54 -0
  29. package/dist/realtime/socketUser.js +75 -5
  30. package/dist/realtime/types.d.ts +54 -0
  31. package/dist/secretProviders.d.ts +23 -0
  32. package/dist/secretProviders.js +9 -3
  33. package/dist/sync/executors.d.ts +198 -0
  34. package/dist/sync/executors.js +670 -0
  35. package/dist/sync/loadHarness.js +807 -0
  36. package/dist/sync/models.d.ts +216 -0
  37. package/dist/sync/models.js +644 -0
  38. package/dist/sync/mutationHandler.d.ts +97 -0
  39. package/dist/sync/mutationHandler.js +886 -0
  40. package/dist/sync/registry.d.ts +73 -0
  41. package/dist/sync/registry.js +223 -0
  42. package/dist/sync/routes.d.ts +62 -0
  43. package/dist/sync/routes.js +936 -0
  44. package/dist/sync/scripts/compactTombstones.d.ts +47 -0
  45. package/dist/sync/scripts/compactTombstones.js +270 -0
  46. package/dist/sync/serialize.d.ts +20 -0
  47. package/dist/{tests/bunSetup.js → sync/serialize.js} +35 -68
  48. package/dist/sync/socketHandlers.d.ts +54 -0
  49. package/dist/sync/socketHandlers.js +470 -0
  50. package/dist/sync/streams.d.ts +85 -0
  51. package/dist/sync/streams.js +221 -0
  52. package/dist/sync/syncApp.d.ts +29 -0
  53. package/dist/sync/syncApp.js +44 -0
  54. package/dist/sync/syncBatch.d.ts +71 -0
  55. package/dist/sync/syncBatch.js +252 -0
  56. package/dist/sync/syncSeqPlugin.d.ts +8 -0
  57. package/dist/sync/syncSeqPlugin.js +899 -0
  58. package/dist/sync/types.d.ts +254 -0
  59. package/dist/sync/types.js +9 -0
  60. package/dist/terrenoApp.js +90 -27
  61. package/dist/vendor/wesleytodd-openapi/index.d.ts +1 -1
  62. package/dist/vendor/wesleytodd-openapi/lib/ui.d.ts +2 -1
  63. package/package.json +7 -6
  64. package/src/__tests__/openApiCompat.test.ts +20 -0
  65. package/src/api.errors.test.ts +32 -23
  66. package/src/api.test.ts +12 -0
  67. package/src/api.ts +87 -296
  68. package/src/auth.test.ts +202 -0
  69. package/src/auth.ts +134 -23
  70. package/src/betterAuth.ts +6 -0
  71. package/src/betterAuthSetup.test.ts +34 -0
  72. package/src/betterAuthSetup.ts +20 -1
  73. package/src/configuration.test.ts +59 -38
  74. package/src/configurationPlugin.test.ts +72 -42
  75. package/src/docLoader.ts +3 -1
  76. package/src/errors.ts +33 -0
  77. package/src/expressServer.test.ts +7 -1
  78. package/src/index.ts +42 -0
  79. package/src/middleware.test.ts +56 -1
  80. package/src/middleware.ts +15 -0
  81. package/src/openApiCompat.ts +99 -45
  82. package/src/permissions.test.ts +101 -17
  83. package/src/permissions.ts +49 -0
  84. package/src/plugins.test.ts +64 -0
  85. package/src/plugins.ts +56 -0
  86. package/src/realtime/changeStreamWatcher.ts +552 -114
  87. package/src/realtime/realtime.test.ts +157 -0
  88. package/src/realtime/realtimeApp.ts +82 -14
  89. package/src/realtime/realtimeAppSetup.test.ts +25 -27
  90. package/src/realtime/sessionRevalidation.test.ts +423 -0
  91. package/src/realtime/sessionRevalidation.ts +273 -0
  92. package/src/realtime/socketAuth.test.ts +355 -0
  93. package/src/realtime/socketAuth.ts +228 -0
  94. package/src/realtime/socketUser.ts +69 -0
  95. package/src/realtime/types.ts +54 -0
  96. package/src/secretProviders.test.ts +7 -1
  97. package/src/secretProviders.ts +15 -3
  98. package/src/secretProvidersGcpClient.test.ts +66 -0
  99. package/src/sync/ensureSyncIndexes.test.ts +144 -0
  100. package/src/sync/executors.test.ts +882 -0
  101. package/src/sync/executors.ts +705 -0
  102. package/src/sync/integration.test.ts +1160 -0
  103. package/src/sync/loadHarness.ts +618 -0
  104. package/src/sync/models.ts +641 -0
  105. package/src/sync/mutationHandler.test.ts +1252 -0
  106. package/src/sync/mutationHandler.ts +850 -0
  107. package/src/sync/registry.ts +232 -0
  108. package/src/sync/routes.ts +812 -0
  109. package/src/sync/scripts/compactTombstones.test.ts +249 -0
  110. package/src/sync/scripts/compactTombstones.ts +145 -0
  111. package/src/sync/serialize.ts +48 -0
  112. package/src/sync/sessionRevalidationIntegration.test.ts +281 -0
  113. package/src/sync/socketHandlers.ts +320 -0
  114. package/src/sync/streams.ts +188 -0
  115. package/src/sync/sync.test.ts +582 -0
  116. package/src/sync/syncApp.ts +44 -0
  117. package/src/sync/syncBatch.ts +219 -0
  118. package/src/sync/syncFrontier.test.ts +494 -0
  119. package/src/sync/syncPhaseC.test.ts +718 -0
  120. package/src/sync/syncRoutes.test.ts +865 -0
  121. package/src/sync/syncSeqPlugin.ts +730 -0
  122. package/src/sync/syncSocket.test.ts +1440 -0
  123. package/src/sync/types.ts +270 -0
  124. package/src/terrenoApp.ts +37 -17
  125. package/src/tests/bunSetup.ts +8 -0
  126. package/tsconfig.json +4 -4
  127. package/tsconfig.typedoc.json +7 -1
  128. package/dist/__tests__/openApiCompat.test.js +0 -317
  129. package/dist/__tests__/versionCheckPlugin.test.d.ts +0 -1
  130. package/dist/__tests__/versionCheckPlugin.test.js +0 -597
  131. package/dist/actions.openApi.test.d.ts +0 -1
  132. package/dist/actions.openApi.test.js +0 -253
  133. package/dist/actions.test.d.ts +0 -1
  134. package/dist/actions.test.js +0 -1087
  135. package/dist/api.arrayOperations.test.d.ts +0 -1
  136. package/dist/api.arrayOperations.test.js +0 -878
  137. package/dist/api.asyncHandler.test.d.ts +0 -1
  138. package/dist/api.asyncHandler.test.js +0 -236
  139. package/dist/api.coverage.test.d.ts +0 -1
  140. package/dist/api.coverage.test.js +0 -192
  141. package/dist/api.errorPaths.test.d.ts +0 -1
  142. package/dist/api.errorPaths.test.js +0 -887
  143. package/dist/api.errors.test.d.ts +0 -1
  144. package/dist/api.errors.test.js +0 -185
  145. package/dist/api.hooks.test.d.ts +0 -1
  146. package/dist/api.hooks.test.js +0 -950
  147. package/dist/api.query.test.d.ts +0 -1
  148. package/dist/api.query.test.js +0 -948
  149. package/dist/api.test.d.ts +0 -1
  150. package/dist/api.test.js +0 -2820
  151. package/dist/auth.compile.test.d.ts +0 -1
  152. package/dist/auth.compile.test.js +0 -201
  153. package/dist/auth.coverage.test.d.ts +0 -1
  154. package/dist/auth.coverage.test.js +0 -202
  155. package/dist/auth.test.d.ts +0 -1
  156. package/dist/auth.test.js +0 -2286
  157. package/dist/betterAuth.test.d.ts +0 -1
  158. package/dist/betterAuth.test.js +0 -181
  159. package/dist/betterAuthApp.test.d.ts +0 -1
  160. package/dist/betterAuthApp.test.js +0 -242
  161. package/dist/betterAuthSetup.test.d.ts +0 -1
  162. package/dist/betterAuthSetup.test.js +0 -762
  163. package/dist/config.test.d.ts +0 -1
  164. package/dist/config.test.js +0 -353
  165. package/dist/configuration.test.d.ts +0 -1
  166. package/dist/configuration.test.js +0 -980
  167. package/dist/configurationPlugin.test.d.ts +0 -1
  168. package/dist/configurationPlugin.test.js +0 -827
  169. package/dist/consentApp.test.d.ts +0 -1
  170. package/dist/consentApp.test.js +0 -1411
  171. package/dist/docLoader.test.d.ts +0 -1
  172. package/dist/docLoader.test.js +0 -137
  173. package/dist/envConfigurationPlugin.test.d.ts +0 -1
  174. package/dist/envConfigurationPlugin.test.js +0 -369
  175. package/dist/errors.test.d.ts +0 -1
  176. package/dist/errors.test.js +0 -607
  177. package/dist/expressServer.test.d.ts +0 -1
  178. package/dist/expressServer.test.js +0 -1249
  179. package/dist/githubAuth.test.d.ts +0 -1
  180. package/dist/githubAuth.test.js +0 -1142
  181. package/dist/httpClient.test.d.ts +0 -1
  182. package/dist/httpClient.test.js +0 -1471
  183. package/dist/logger.test.d.ts +0 -1
  184. package/dist/logger.test.js +0 -685
  185. package/dist/middleware.test.d.ts +0 -1
  186. package/dist/middleware.test.js +0 -241
  187. package/dist/notifiers/googleChatNotifier.test.d.ts +0 -1
  188. package/dist/notifiers/googleChatNotifier.test.js +0 -298
  189. package/dist/notifiers/slackNotifier.test.d.ts +0 -1
  190. package/dist/notifiers/slackNotifier.test.js +0 -297
  191. package/dist/notifiers/zoomNotifier.test.d.ts +0 -1
  192. package/dist/notifiers/zoomNotifier.test.js +0 -373
  193. package/dist/openApi.test.d.ts +0 -1
  194. package/dist/openApi.test.js +0 -620
  195. package/dist/openApiBuilder.test.d.ts +0 -1
  196. package/dist/openApiBuilder.test.js +0 -599
  197. package/dist/openApiEtag.test.d.ts +0 -1
  198. package/dist/openApiEtag.test.js +0 -86
  199. package/dist/openApiValidator.test.d.ts +0 -1
  200. package/dist/openApiValidator.test.js +0 -795
  201. package/dist/permissions.middleware.test.d.ts +0 -1
  202. package/dist/permissions.middleware.test.js +0 -308
  203. package/dist/permissions.test.d.ts +0 -1
  204. package/dist/permissions.test.js +0 -439
  205. package/dist/plugins.test.d.ts +0 -1
  206. package/dist/plugins.test.js +0 -902
  207. package/dist/populate.test.d.ts +0 -1
  208. package/dist/populate.test.js +0 -370
  209. package/dist/realtime/realtime.test.d.ts +0 -10
  210. package/dist/realtime/realtime.test.js +0 -4213
  211. package/dist/realtime/realtimeAppSetup.test.d.ts +0 -1
  212. package/dist/realtime/realtimeAppSetup.test.js +0 -213
  213. package/dist/requestContext.test.d.ts +0 -1
  214. package/dist/requestContext.test.js +0 -412
  215. package/dist/scriptRunner.test.d.ts +0 -1
  216. package/dist/scriptRunner.test.js +0 -386
  217. package/dist/secretProviders.test.d.ts +0 -1
  218. package/dist/secretProviders.test.js +0 -726
  219. package/dist/syncConsents.test.d.ts +0 -1
  220. package/dist/syncConsents.test.js +0 -522
  221. package/dist/terrenoApp.test.d.ts +0 -1
  222. package/dist/terrenoApp.test.js +0 -489
  223. package/dist/tests/bunSetup.d.ts +0 -1
  224. package/dist/tests/fixtures/compileAuthEntry.d.ts +0 -1
  225. package/dist/tests/fixtures/compileAuthEntry.js +0 -37
  226. package/dist/tests/testEnv.d.ts +0 -0
  227. package/dist/tests/testEnv.js +0 -6
  228. package/dist/transformers.test.d.ts +0 -1
  229. package/dist/transformers.test.js +0 -423
  230. package/dist/utils.test.d.ts +0 -1
  231. package/dist/utils.test.js +0 -242
  232. /package/dist/{__tests__/openApiCompat.test.d.ts → sync/loadHarness.d.ts} +0 -0
@@ -2460,6 +2460,163 @@ describe("startChangeStreamWatcher", () => {
2460
2460
  mockStream.trigger("end");
2461
2461
  });
2462
2462
 
2463
+ // Task 9.16: a transient stream failure used to be logged and then permanently starve
2464
+ // every realtime event and sync delta until the process restarted.
2465
+ describe("restart with resume token (Task 9.16)", () => {
2466
+ const waitFor = async (
2467
+ predicate: () => boolean,
2468
+ label: string,
2469
+ timeoutMs = 3000
2470
+ ): Promise<void> => {
2471
+ const start = Date.now();
2472
+ while (Date.now() - start < timeoutMs) {
2473
+ if (predicate()) {
2474
+ return;
2475
+ }
2476
+ await new Promise((resolve) => setTimeout(resolve, 10));
2477
+ }
2478
+ throw new Error(`Timed out after ${timeoutMs}ms waiting for ${label}`);
2479
+ };
2480
+
2481
+ const registerTodos = (): void => {
2482
+ registerRealtime({
2483
+ collectionName: "todos",
2484
+ config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
2485
+ modelName: "Todo",
2486
+ options: {
2487
+ permissions: {
2488
+ create: [() => true],
2489
+ delete: [() => true],
2490
+ list: [() => true],
2491
+ read: [() => true],
2492
+ update: [() => true],
2493
+ },
2494
+ },
2495
+ routePath: "/todos",
2496
+ });
2497
+ };
2498
+
2499
+ /** An io whose room socket records deliveries, plus a recorded server-wide `emit`. */
2500
+ const createRecordingIo = (): {
2501
+ io: import("socket.io").Server;
2502
+ deliveries: {event: string; payload: unknown}[];
2503
+ serverEmissions: {event: string; payload: unknown}[];
2504
+ } => {
2505
+ const deliveries: {event: string; payload: unknown}[] = [];
2506
+ const serverEmissions: {event: string; payload: unknown}[] = [];
2507
+ const rooms = new Map<string, Set<string>>();
2508
+ rooms.set("model:todos", new Set(["sock-1"]));
2509
+ const sockets = new Map<string, any>();
2510
+ sockets.set("sock-1", {
2511
+ decodedToken: {id: "user-1"},
2512
+ emit: (event: string, payload: unknown) => {
2513
+ deliveries.push({event, payload});
2514
+ },
2515
+ id: "sock-1",
2516
+ });
2517
+ return {
2518
+ deliveries,
2519
+ io: {
2520
+ emit: (event: string, payload: unknown) => {
2521
+ serverEmissions.push({event, payload});
2522
+ },
2523
+ sockets: {adapter: {rooms}, sockets},
2524
+ to: () => ({emit: () => {}}),
2525
+ } as unknown as import("socket.io").Server,
2526
+ serverEmissions,
2527
+ };
2528
+ };
2529
+
2530
+ it("reopens with resumeAfter after a stream error and keeps delivering changes", async () => {
2531
+ const firstStream = createMockChangeStream();
2532
+ const secondStream = createMockChangeStream();
2533
+ const streams = [firstStream, secondStream];
2534
+ const mockDb = {watch: mock(() => streams.shift() ?? secondStream)};
2535
+ (mongoose.connection as any).db = mockDb;
2536
+ registerTodos();
2537
+
2538
+ const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
2539
+ const {deliveries, io} = createRecordingIo();
2540
+ startChangeStreamWatcher(io, {}, true);
2541
+
2542
+ // A change on the first stream establishes the resume position.
2543
+ await invokeRegisteredChangeHandler(firstStream, {
2544
+ _id: {_data: "token-1"},
2545
+ documentKey: {_id: "doc-1"},
2546
+ fullDocument: {_id: "doc-1", name: "before the failure"},
2547
+ ns: {coll: "todos"},
2548
+ operationType: "insert",
2549
+ });
2550
+ expect(deliveries).toHaveLength(1);
2551
+
2552
+ firstStream.trigger("error", new Error("replica set election"));
2553
+ await waitFor(() => mockDb.watch.mock.calls.length >= 2, "the stream to reopen");
2554
+
2555
+ const reopenOptions = (mockDb.watch.mock.calls[1] as any[])[1];
2556
+ expect(reopenOptions.resumeAfter).toEqual({_data: "token-1"});
2557
+
2558
+ // The reopened stream is fully wired: later writes still fan out.
2559
+ await invokeRegisteredChangeHandler(secondStream, {
2560
+ _id: {_data: "token-2"},
2561
+ documentKey: {_id: "doc-2"},
2562
+ fullDocument: {_id: "doc-2", name: "after the restart"},
2563
+ ns: {coll: "todos"},
2564
+ operationType: "insert",
2565
+ });
2566
+ expect(deliveries).toHaveLength(2);
2567
+ });
2568
+
2569
+ it("drops the resume token and asks clients to resync when the oplog history is lost", async () => {
2570
+ const firstStream = createMockChangeStream();
2571
+ const secondStream = createMockChangeStream();
2572
+ const streams = [firstStream, secondStream];
2573
+ const mockDb = {watch: mock(() => streams.shift() ?? secondStream)};
2574
+ (mongoose.connection as any).db = mockDb;
2575
+
2576
+ const {SYNC_RESYNC_EVENT, startChangeStreamWatcher} = await import("./changeStreamWatcher");
2577
+ const {io, serverEmissions} = createRecordingIo();
2578
+ startChangeStreamWatcher(io, {}, true);
2579
+
2580
+ await invokeRegisteredChangeHandler(firstStream, {
2581
+ _id: {_data: "token-1"},
2582
+ documentKey: {_id: "doc-1"},
2583
+ ns: {coll: "unregistered"},
2584
+ operationType: "insert",
2585
+ });
2586
+
2587
+ const historyLost = Object.assign(new Error("resume of change stream was not possible"), {
2588
+ code: 286,
2589
+ codeName: "ChangeStreamHistoryLost",
2590
+ });
2591
+ firstStream.trigger("error", historyLost);
2592
+
2593
+ expect(serverEmissions).toEqual([
2594
+ {event: SYNC_RESYNC_EVENT, payload: {reason: "history_lost"}},
2595
+ ]);
2596
+
2597
+ await waitFor(() => mockDb.watch.mock.calls.length >= 2, "the stream to reopen");
2598
+ // An unusable token must not be replayed — the reopen starts from now.
2599
+ expect((mockDb.watch.mock.calls[1] as any[])[1].resumeAfter).toBeUndefined();
2600
+ });
2601
+
2602
+ it("does not reopen after the watcher is stopped", async () => {
2603
+ const mockStream = createMockChangeStream();
2604
+ const mockDb = {watch: mock(() => mockStream)};
2605
+ (mongoose.connection as any).db = mockDb;
2606
+
2607
+ const {startChangeStreamWatcher, stopChangeStreamWatcher: stop} = await import(
2608
+ "./changeStreamWatcher"
2609
+ );
2610
+ const {io} = createRecordingIo();
2611
+ startChangeStreamWatcher(io, {}, true);
2612
+
2613
+ mockStream.trigger("error", new Error("shutting down"));
2614
+ await stop();
2615
+ await new Promise((resolve) => setTimeout(resolve, 400));
2616
+ expect(mockDb.watch).toHaveBeenCalledTimes(1);
2617
+ });
2618
+ });
2619
+
2463
2620
  it("uses custom batchSize and fullDocument config", async () => {
2464
2621
  const mockStream = createMockChangeStream();
2465
2622
  const mockDb = {
@@ -2,7 +2,6 @@
2
2
  // biome-ignore-all lint/suspicious/noExplicitAny: Socket.io handler signatures require dynamic args
3
3
  import type http from "node:http";
4
4
  import * as Sentry from "@sentry/bun";
5
- import {authorize} from "@thream/socketio-jwt";
6
5
  import type express from "express";
7
6
  import {Server, type Socket} from "socket.io";
8
7
 
@@ -10,6 +9,9 @@ import type {User} from "../auth";
10
9
  import {APIError} from "../errors";
11
10
  import {logger} from "../logger";
12
11
  import {checkPermissions} from "../permissions";
12
+ import {warnOnSyncScopesWithoutUserModel} from "../sync/registry";
13
+ import {installSyncSocketHandlers} from "../sync/socketHandlers";
14
+ import {getSyncAppOptions} from "../sync/syncApp";
13
15
  import type {TerrenoPlugin} from "../terrenoPlugin";
14
16
  import {startChangeStreamWatcher, stopChangeStreamWatcher} from "./changeStreamWatcher";
15
17
  import {
@@ -19,7 +21,13 @@ import {
19
21
  removeQuerySubscription,
20
22
  } from "./queryStore";
21
23
  import {findRegistryEntryByRoutePath, type RealtimeRegistryEntry} from "./registry";
22
- import {getSocketUser, type SocketWithDecodedToken} from "./socketUser";
24
+ import {
25
+ loadFullUserForSocket,
26
+ type SessionRevalidationHandle,
27
+ startSessionRevalidationSweep,
28
+ } from "./sessionRevalidation";
29
+ import {createSocketAuthMiddleware} from "./socketAuth";
30
+ import {getSocketUser, type SocketDataBag, type SocketWithDecodedToken} from "./socketUser";
23
31
  import type {DocumentSubscription, QuerySubscription, RealtimeAppOptions} from "./types";
24
32
 
25
33
  /**
@@ -123,7 +131,9 @@ export const installRealtimeSocketHandlers = (
123
131
  const logInfo = options.logInfo ?? ((): void => {});
124
132
  const userId = socket.decodedToken?.id;
125
133
  const isAdmin = socket.decodedToken?.admin === true;
126
- const user = getSocketUser(socket);
134
+ // D2: re-derive per event rather than capturing once at install time, so a
135
+ // handshake-time-loaded full user (or one refreshed by D1's sweep) is always used.
136
+ const currentUser = (): User | undefined => getSocketUser(socket);
127
137
 
128
138
  const counts = {document: 0, model: 0, query: 0};
129
139
 
@@ -170,7 +180,7 @@ export const installRealtimeSocketHandlers = (
170
180
  return;
171
181
  }
172
182
 
173
- if (!(await canSubscribe(entry, "list", user))) {
183
+ if (!(await canSubscribe(entry, "list", currentUser()))) {
174
184
  logInfo(
175
185
  `[realtime] User ${userId} denied model subscription for ${modelName}: list permission denied`
176
186
  );
@@ -213,7 +223,7 @@ export const installRealtimeSocketHandlers = (
213
223
  return;
214
224
  }
215
225
 
216
- if (!(await canSubscribe(entry, "read", user))) {
226
+ if (!(await canSubscribe(entry, "read", currentUser()))) {
217
227
  logInfo(
218
228
  `[realtime] User ${userId} denied document subscription for ` +
219
229
  `${payload.collection}/${payload.id}: read permission denied`
@@ -268,7 +278,7 @@ export const installRealtimeSocketHandlers = (
268
278
  return;
269
279
  }
270
280
 
271
- let query = await getAuthorizedQuery(entry, {...payload.query}, user);
281
+ let query = await getAuthorizedQuery(entry, {...payload.query}, currentUser());
272
282
  if (!query) {
273
283
  logInfo(
274
284
  `[realtime] User ${userId} denied query subscription for ${payload.collection}: ` +
@@ -337,8 +347,10 @@ export const installRealtimeSocketHandlers = (
337
347
  * ```
338
348
  */
339
349
  export class RealtimeApp implements TerrenoPlugin {
350
+ private app: express.Application | null = null;
340
351
  private io: Server | null = null;
341
352
  private config: RealtimeAppOptions;
353
+ private sessionRevalidation: SessionRevalidationHandle | null = null;
342
354
 
343
355
  constructor(config: RealtimeAppOptions = {}) {
344
356
  this.config = config;
@@ -348,6 +360,7 @@ export class RealtimeApp implements TerrenoPlugin {
348
360
  * Register routes and middleware. Adds a /realtime/health endpoint.
349
361
  */
350
362
  register(app: express.Application): void {
363
+ this.app = app;
351
364
  app.get("/realtime/health", (_req, res) => {
352
365
  const connected = this.io?.engine?.clientsCount ?? 0;
353
366
  res.json({
@@ -374,14 +387,17 @@ export class RealtimeApp implements TerrenoPlugin {
374
387
  try {
375
388
  logInfo("[realtime] Setting up Socket.io server...");
376
389
 
377
- this.io = new Server(server, {
390
+ // Prefer an injected Server constructor in tests so callers never need
391
+ // process-wide `mock.module("socket.io")` (which poisons later files).
392
+ const SocketServerCtor = this.config.SocketServer ?? Server;
393
+ this.io = new SocketServerCtor(server, {
378
394
  cors: this.config.cors ?? {
379
395
  methods: ["GET", "POST"],
380
396
  origin: "*",
381
397
  },
382
398
  });
383
399
 
384
- // JWT authentication middleware
400
+ // Authentication middleware: legacy JWT first, optionally Better Auth sessions.
385
401
  const tokenSecret = this.config.tokenSecret ?? process.env.TOKEN_SECRET;
386
402
  if (!tokenSecret) {
387
403
  throw new APIError({
@@ -392,13 +408,31 @@ export class RealtimeApp implements TerrenoPlugin {
392
408
  });
393
409
  }
394
410
 
411
+ // D1: pass the issuer through for parity with the HTTP JWT path
412
+ // (jwt.verify(token, secret, {issuer})) — without it a validly-signed token
413
+ // issued for a different TOKEN_ISSUER was silently accepted over sockets. A
414
+ // thunk (not a value captured once here) so a later change to
415
+ // process.env.TOKEN_ISSUER — or to an explicitly configured tokenIssuer — is
416
+ // honored on every handshake, matching the HTTP path's per-request env read.
417
+ const resolveTokenIssuer = (): string | undefined =>
418
+ this.config.tokenIssuer ?? process.env.TOKEN_ISSUER;
419
+
395
420
  this.io.use(
396
- authorize({
397
- secret: tokenSecret,
421
+ createSocketAuthMiddleware({
422
+ betterAuth: this.config.betterAuth,
423
+ issuer: resolveTokenIssuer,
424
+ tokenSecret,
398
425
  })
399
426
  );
400
427
 
401
- logInfo("[realtime] JWT authorization middleware added");
428
+ logInfo(
429
+ `[realtime] Socket auth middleware added (JWT${this.config.betterAuth ? " + Better Auth" : ""})`
430
+ );
431
+
432
+ // Task 9.21: tenant/custom sync scopes can only be resolved from the full user
433
+ // document, so warn loudly here (once, at startup) rather than silently serving
434
+ // empty tenant streams for the life of the process.
435
+ warnOnSyncScopesWithoutUserModel({userModel: this.config.userModel});
402
436
 
403
437
  // Configure adapter for multi-instance deployments
404
438
  this.setupAdapter(logInfo);
@@ -406,9 +440,27 @@ export class RealtimeApp implements TerrenoPlugin {
406
440
  // Connection handling
407
441
  this.io.on("connection", (socket: Socket): void => {
408
442
  try {
409
- // socketio-jwt's authorize middleware adds `decodedToken` at runtime; cast through
443
+ // D2: load the full user document once at handshake (by the decoded
444
+ // token's id) and cache it on socket.data.fullUser — getSocketUser prefers
445
+ // it over the synthetic {_id, admin, id} shape for every authorization
446
+ // check below. Fire-and-forget: handlers install synchronously and fall
447
+ // back to the synthetic shape until this resolves.
448
+ void loadFullUserForSocket(
449
+ socket as unknown as Socket & {data: SocketDataBag},
450
+ this.config.userModel
451
+ );
452
+ // The auth middleware adds `decodedToken` at runtime; cast through
410
453
  // RealtimeSocketLike (a structural subset) to keep socket handler logic testable.
411
454
  installRealtimeSocketHandlers(socket as unknown as RealtimeSocketLike, {logInfo});
455
+ // Sync protocol handlers (sync:subscribe / sync:mutate). Options come from the
456
+ // SyncApp registered on this Express app or an explicit `sync` override here;
457
+ // with neither, the handlers still install and reject unknown collections.
458
+ installSyncSocketHandlers(
459
+ this.io,
460
+ socket as unknown as RealtimeSocketLike,
461
+ this.config.sync ?? (this.app ? getSyncAppOptions(this.app) : undefined) ?? {},
462
+ {logInfo}
463
+ );
412
464
  } catch (error) {
413
465
  logger.error(`[realtime] Error handling connection: ${error}`);
414
466
  Sentry.captureException(error);
@@ -420,8 +472,22 @@ export class RealtimeApp implements TerrenoPlugin {
420
472
  Sentry.captureException(error);
421
473
  });
422
474
 
423
- // Start the change stream watcher
424
- startChangeStreamWatcher(this.io, this.config.changeStream, debug);
475
+ // Start the change stream watcher (injectable for unit tests — see SocketServer).
476
+ const startWatcher = this.config.startChangeStreamWatcher ?? startChangeStreamWatcher;
477
+ startWatcher(this.io, this.config.changeStream, debug);
478
+
479
+ // D1: periodic session re-validation sweep — disconnects sockets whose JWT has
480
+ // expired, whose Better Auth session is no longer valid, or whose user has
481
+ // since been disabled; also refreshes socket.data.fullUser (D2) and
482
+ // re-resolves sync room membership (D4) for sockets that remain valid.
483
+ // A thunk (not a snapshot) reads this app's SyncApp options fresh on every sweep.
484
+ this.sessionRevalidation = startSessionRevalidationSweep(this.io, () => ({
485
+ betterAuth: this.config.betterAuth,
486
+ intervalMs: this.config.sessionRevalidationIntervalMs,
487
+ logInfo,
488
+ sync: this.config.sync ?? (this.app ? getSyncAppOptions(this.app) : undefined),
489
+ userModel: this.config.userModel,
490
+ }));
425
491
 
426
492
  logInfo("[realtime] Socket.io server setup complete");
427
493
  } catch (error) {
@@ -443,6 +509,8 @@ export class RealtimeApp implements TerrenoPlugin {
443
509
  */
444
510
  async close(): Promise<void> {
445
511
  try {
512
+ this.sessionRevalidation?.stop();
513
+ this.sessionRevalidation = null;
446
514
  await stopChangeStreamWatcher();
447
515
  if (this.io) {
448
516
  await this.io.close();
@@ -1,13 +1,15 @@
1
1
  /**
2
2
  * Tests for RealtimeApp.onServerCreated — the Socket.io server wiring that a
3
- * live server would exercise. socket.io, the JWT authorize middleware, and the
4
- * change-stream watcher are mocked so the connection / connect_error handlers
5
- * can be captured and invoked without standing up a real server.
3
+ * live server would exercise. Socket.IO Server and the change-stream watcher are
4
+ * injected via RealtimeAppOptions so we never `mock.module` (bun's module mocks
5
+ * are process-wide and would break later files that need the real implementations).
6
6
  */
7
- import {afterEach, beforeAll, beforeEach, describe, expect, it, mock} from "bun:test";
7
+ import {afterEach, beforeEach, describe, expect, it} from "bun:test";
8
8
 
9
9
  import type http from "node:http";
10
10
 
11
+ import {RealtimeApp} from "./realtimeApp";
12
+
11
13
  type Handler = (...args: unknown[]) => void;
12
14
 
13
15
  interface FakeIo {
@@ -43,23 +45,6 @@ class FakeServer {
43
45
  }
44
46
  }
45
47
 
46
- mock.module("socket.io", () => ({Server: FakeServer}));
47
- mock.module("@thream/socketio-jwt", () => ({
48
- authorize: (_opts: unknown) => (_socket: unknown, next: () => void) => next(),
49
- }));
50
- mock.module("./changeStreamWatcher", () => ({
51
- startChangeStreamWatcher: () => {
52
- watcherStarts += 1;
53
- },
54
- stopChangeStreamWatcher: () => {},
55
- }));
56
-
57
- let RealtimeApp: typeof import("./realtimeApp").RealtimeApp;
58
-
59
- beforeAll(async () => {
60
- ({RealtimeApp} = await import("./realtimeApp"));
61
- });
62
-
63
48
  const lastIo = (): FakeIo => {
64
49
  const io = ios[ios.length - 1];
65
50
  if (!io) {
@@ -95,6 +80,19 @@ const createConnectionSocket = (throwOnOn = false): Record<string, unknown> => {
95
80
  };
96
81
  };
97
82
 
83
+ /** Shared RealtimeAppOptions that inject FakeServer + a start-watcher counter. */
84
+ const testRealtimeOptions = (
85
+ overrides: ConstructorParameters<typeof RealtimeApp>[0] = {}
86
+ ): ConstructorParameters<typeof RealtimeApp>[0] => ({
87
+ SocketServer: FakeServer as unknown as NonNullable<
88
+ ConstructorParameters<typeof RealtimeApp>[0]
89
+ >["SocketServer"],
90
+ startChangeStreamWatcher: () => {
91
+ watcherStarts += 1;
92
+ },
93
+ ...overrides,
94
+ });
95
+
98
96
  describe("RealtimeApp.onServerCreated", () => {
99
97
  beforeEach(() => {
100
98
  ios = [];
@@ -106,7 +104,7 @@ describe("RealtimeApp.onServerCreated", () => {
106
104
  });
107
105
 
108
106
  it("wires up auth middleware, connection handlers, and the change-stream watcher", () => {
109
- const app = new RealtimeApp({debug: true, tokenSecret: "test-secret"});
107
+ const app = new RealtimeApp(testRealtimeOptions({debug: true, tokenSecret: "test-secret"}));
110
108
  app.onServerCreated(fakeServer);
111
109
 
112
110
  const io = lastIo();
@@ -118,7 +116,7 @@ describe("RealtimeApp.onServerCreated", () => {
118
116
  });
119
117
 
120
118
  it("installs socket handlers for each new connection", () => {
121
- const app = new RealtimeApp({tokenSecret: "test-secret"});
119
+ const app = new RealtimeApp(testRealtimeOptions({tokenSecret: "test-secret"}));
122
120
  app.onServerCreated(fakeServer);
123
121
 
124
122
  const connectionHandler = getHandler("connection");
@@ -128,7 +126,7 @@ describe("RealtimeApp.onServerCreated", () => {
128
126
  });
129
127
 
130
128
  it("captures errors thrown while handling a connection", () => {
131
- const app = new RealtimeApp({tokenSecret: "test-secret"});
129
+ const app = new RealtimeApp(testRealtimeOptions({tokenSecret: "test-secret"}));
132
130
  app.onServerCreated(fakeServer);
133
131
 
134
132
  const connectionHandler = getHandler("connection");
@@ -138,7 +136,7 @@ describe("RealtimeApp.onServerCreated", () => {
138
136
  });
139
137
 
140
138
  it("logs connect_error events without throwing", () => {
141
- const app = new RealtimeApp({tokenSecret: "test-secret"});
139
+ const app = new RealtimeApp(testRealtimeOptions({tokenSecret: "test-secret"}));
142
140
  app.onServerCreated(fakeServer);
143
141
 
144
142
  const errorHandler = getHandler("connect_error");
@@ -147,7 +145,7 @@ describe("RealtimeApp.onServerCreated", () => {
147
145
 
148
146
  it("reads the token secret from the environment when not provided in config", () => {
149
147
  process.env.TOKEN_SECRET = "env-secret";
150
- const app = new RealtimeApp();
148
+ const app = new RealtimeApp(testRealtimeOptions());
151
149
  app.onServerCreated(fakeServer);
152
150
 
153
151
  expect(lastIo().handlers.has("connection")).toBe(true);
@@ -155,7 +153,7 @@ describe("RealtimeApp.onServerCreated", () => {
155
153
 
156
154
  it("throws when no token secret is available", () => {
157
155
  delete process.env.TOKEN_SECRET;
158
- const app = new RealtimeApp();
156
+ const app = new RealtimeApp(testRealtimeOptions());
159
157
  expect(() => app.onServerCreated(fakeServer)).toThrow(/TOKEN_SECRET is required/);
160
158
  });
161
159
  });