@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
@@ -0,0 +1,281 @@
1
+ // noExplicitAny: the rig bridges generic model/router/test types
2
+ // biome-ignore-all lint/suspicious/noExplicitAny: the rig bridges generic model/router/test types
3
+ /**
4
+ * Integration coverage for D1 (socket session re-validation sweep) and D4
5
+ * (membership revocation vs socket rooms), using a REAL @terreno/syncdb client
6
+ * against a REAL @terreno/api backend — the same rig shape as integration.test.ts,
7
+ * but a dedicated file/registry/server so a short `sessionRevalidationIntervalMs`
8
+ * and a tenant-scoped model don't interact with that file's sequential scenarios.
9
+ *
10
+ * Scenarios:
11
+ * - D1: a disabled user's socket is disconnected by the sweep within one interval,
12
+ * emitting sync:auth-expired first; the client lands in auth-pause with the
13
+ * outbox intact (INV-2).
14
+ * - D4: revoking a user's only organization membership mid-session causes the
15
+ * sweep to leave the tenant's sync room — no further deltas for that org reach
16
+ * the live socket, even though the connection itself stays up (still a valid,
17
+ * non-disabled user).
18
+ */
19
+
20
+ import {afterAll, beforeAll, describe, expect, it} from "bun:test";
21
+ import {createServer, type Server as HttpServer} from "node:http";
22
+ import type {AddressInfo} from "node:net";
23
+ import {
24
+ type AuthProvider,
25
+ clearMemoryPersisterData,
26
+ createHttpChannel,
27
+ createSocketTransport,
28
+ createSyncDb,
29
+ memoryPersisterFactory,
30
+ type SyncDb,
31
+ } from "@terreno/syncdb";
32
+ import mongoose, {model, Schema} from "mongoose";
33
+
34
+ import {modelRouter} from "../api";
35
+ import {addAuthRoutes, generateTokens, setupAuth} from "../auth";
36
+ import {createdUpdatedPlugin, findOneOrNoneFor, type IsDeleted, isDeletedPlugin} from "../plugins";
37
+ import {RealtimeApp} from "../realtime/realtimeApp";
38
+ import {getBaseServer, setupDb, UserModel} from "../tests";
39
+ import {SyncCounter, SyncMutation} from "./models";
40
+ import {clearSyncRegistry} from "./registry";
41
+ import {SyncApp} from "./syncApp";
42
+ import {syncPlugin} from "./syncSeqPlugin";
43
+
44
+ interface RevalProject extends IsDeleted {
45
+ _id: string;
46
+ title: string;
47
+ organizationId: string;
48
+ created: Date;
49
+ _syncSeq?: number;
50
+ }
51
+
52
+ const revalProjectSchema = new Schema<RevalProject>({
53
+ _id: {
54
+ default: (): string => new mongoose.Types.ObjectId().toHexString(),
55
+ description: "The document id (string so offline clients can mint ids)",
56
+ type: String,
57
+ },
58
+ organizationId: {description: "Tenant organization id", type: String},
59
+ title: {description: "Project title", required: true, type: String},
60
+ });
61
+ revalProjectSchema.plugin(isDeletedPlugin);
62
+ revalProjectSchema.plugin(createdUpdatedPlugin);
63
+ revalProjectSchema.plugin(syncPlugin);
64
+ const RevalProjectModel = model<RevalProject>("RevalIntegrationProject", revalProjectSchema);
65
+
66
+ const COLLECTION = "revalProjects";
67
+ const SESSION_REVALIDATION_INTERVAL_MS = 200;
68
+
69
+ /** Poll until the predicate holds; throws on timeout so failures name the wait. */
70
+ const waitFor = async (
71
+ predicate: () => boolean | Promise<boolean>,
72
+ {label = "condition", timeoutMs = 8_000}: {label?: string; timeoutMs?: number} = {}
73
+ ): Promise<void> => {
74
+ const start = Date.now();
75
+ while (Date.now() - start < timeoutMs) {
76
+ if (await predicate()) {
77
+ return;
78
+ }
79
+ await new Promise((resolve) => setTimeout(resolve, 25));
80
+ }
81
+ throw new Error(`Timed out after ${timeoutMs}ms waiting for ${label}`);
82
+ };
83
+
84
+ /** Waits at least `ms`, useful for asserting something did NOT happen by a deadline. */
85
+ const settleFor = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
86
+
87
+ /** Change streams (D4's delta fan-out) require a replica set — mirrors integration.test.ts. */
88
+ const hasReplicaSet = async (): Promise<boolean> => {
89
+ try {
90
+ const admin = mongoose.connection.db?.admin();
91
+ const status = await admin?.command({replSetGetStatus: 1});
92
+ return Boolean(status?.ok);
93
+ } catch {
94
+ return false;
95
+ }
96
+ };
97
+
98
+ describe("session re-validation sweep integration (D1/D4)", () => {
99
+ let httpServer: HttpServer;
100
+ let realtimeApp: RealtimeApp;
101
+ let baseUrl = "";
102
+ let userDoc: {_id: unknown};
103
+ let replicaSetAvailable = false;
104
+ const memberships = new Map<string, string[]>();
105
+ const clients: SyncDb[] = [];
106
+
107
+ const makeAuthProvider = (user: {_id: unknown}): AuthProvider => ({
108
+ getToken: async () => (await generateTokens(user)).token ?? null,
109
+ getUserId: async () => String(user._id),
110
+ onAuthChange: () => () => {},
111
+ });
112
+
113
+ const makeClient = (name: string, user: {_id: unknown}): SyncDb => {
114
+ const authProvider = makeAuthProvider(user);
115
+ const httpChannel = createHttpChannel({authProvider, baseUrl});
116
+ const transport = createSocketTransport({authProvider, baseUrl, timeoutMs: 4_000});
117
+ clearMemoryPersisterData({databaseName: name});
118
+ const client = createSyncDb({
119
+ authProvider,
120
+ collections: [COLLECTION],
121
+ httpChannel,
122
+ name,
123
+ persisterFactory: memoryPersisterFactory,
124
+ reconcileIntervalMs: 0,
125
+ transport,
126
+ });
127
+ clients.push(client);
128
+ return client;
129
+ };
130
+
131
+ beforeAll(async () => {
132
+ const [, notAdmin] = await setupDb();
133
+ userDoc = notAdmin as unknown as {_id: unknown};
134
+ memberships.set(String(userDoc._id), ["org-a"]);
135
+ replicaSetAvailable = await hasReplicaSet();
136
+
137
+ await Promise.all([SyncCounter.ensureIndexes(), SyncMutation.ensureIndexes()]);
138
+ await Promise.all([
139
+ RevalProjectModel.collection.deleteMany({}),
140
+ SyncCounter.deleteMany({}),
141
+ SyncMutation.deleteMany({}),
142
+ ]);
143
+
144
+ clearSyncRegistry();
145
+ const registration = modelRouter<RevalProject>("/revalProjects", RevalProjectModel, {
146
+ permissions: {
147
+ create: [() => true],
148
+ delete: [() => true],
149
+ list: [() => true],
150
+ read: [() => true],
151
+ update: [() => true],
152
+ },
153
+ preCreate: (body) => body as RevalProject,
154
+ sync: {scope: {field: "organizationId", type: "tenant"}},
155
+ });
156
+
157
+ const app = getBaseServer();
158
+ setupAuth(app as any, UserModel as any);
159
+ addAuthRoutes(app as any, UserModel as any);
160
+ new SyncApp({
161
+ getUserScopes: (user) => memberships.get(String(user.id)) ?? [],
162
+ }).register(app);
163
+ app.use(registration.path, registration.router);
164
+
165
+ realtimeApp = new RealtimeApp({
166
+ // D1: a short sweep interval so the tests don't wait a full 60s default.
167
+ sessionRevalidationIntervalMs: SESSION_REVALIDATION_INTERVAL_MS,
168
+ userModel: UserModel as any,
169
+ });
170
+ realtimeApp.register(app);
171
+
172
+ httpServer = createServer(app);
173
+ await new Promise<void>((resolve) => {
174
+ httpServer.listen(0, () => resolve());
175
+ });
176
+ const {port} = httpServer.address() as AddressInfo;
177
+ baseUrl = `http://127.0.0.1:${port}`;
178
+
179
+ realtimeApp.onServerCreated(httpServer);
180
+ // Give the change-stream cursor a moment to open (only delivers post-open
181
+ // events) — same settle the sibling integration/change-stream tests use.
182
+ if (replicaSetAvailable) {
183
+ await new Promise((resolve) => setTimeout(resolve, 300));
184
+ }
185
+ });
186
+
187
+ afterAll(async () => {
188
+ for (const client of clients) {
189
+ await client.stop().catch(() => {});
190
+ }
191
+ realtimeApp?.getIo()?.disconnectSockets(true);
192
+ httpServer?.closeAllConnections?.();
193
+ await realtimeApp?.close();
194
+ await new Promise<void>((resolve) => {
195
+ httpServer.close(() => resolve());
196
+ });
197
+ clearSyncRegistry();
198
+ });
199
+
200
+ it("D1: the sweep disconnects a disabled user's socket, and the client lands in auth-pause with the outbox intact", async () => {
201
+ const client = makeClient("d1-disabled-user", userDoc);
202
+ await client.start();
203
+ await waitFor(() => client.getSyncStatus().isOnline, {label: "initial connect"});
204
+
205
+ // Disable the user mid-session — the sweep should notice within one interval
206
+ // and disconnect the socket (sync:auth-expired). Note: the HTTP channel would
207
+ // ALSO independently 401 on the disabled user (the existing A4 path), so wait
208
+ // for the socket-specific signal (isOnline flipping false) first — the only
209
+ // thing that can disconnect this socket mid-test is the sweep, since nothing
210
+ // else in this scenario touches the transport.
211
+ const fullUser = await findOneOrNoneFor(UserModel as any, {_id: userDoc._id});
212
+ (fullUser as any).disabled = true;
213
+ await (fullUser as any).save();
214
+
215
+ await waitFor(() => !client.getSyncStatus().isOnline, {
216
+ label: "socket disconnected by the sweep after being disabled",
217
+ timeoutMs: 5_000,
218
+ });
219
+ await waitFor(() => client.getSyncStatus().paused === "auth", {
220
+ label: "client paused for auth after being disabled",
221
+ timeoutMs: 5_000,
222
+ });
223
+ expect(client.getSyncStatus().isOnline).toBe(false);
224
+
225
+ // A mutation made while paused stays queued — nothing is lost, no budget burned.
226
+ const {mutationId} = client.mutate({
227
+ collection: COLLECTION,
228
+ data: {organizationId: "org-a", title: "queued while disabled"},
229
+ operation: "create",
230
+ });
231
+ const mutation = client.outbox.getMutation({mutationId});
232
+ expect(mutation?.status).toBe("queued");
233
+ expect(mutation?.errorNackCount).toBe(0);
234
+
235
+ // Re-enable so afterAll's client.stop() and any later scenario aren't left
236
+ // fighting a disabled user; also proves recovery is possible.
237
+ (fullUser as any).disabled = false;
238
+ await (fullUser as any).save();
239
+ }, 15_000);
240
+
241
+ it("D4: revoking the user's only organization membership stops further deltas for that tenant on the live socket", async () => {
242
+ if (!replicaSetAvailable) {
243
+ // Deltas are change-stream-driven; without a replica set there is nothing
244
+ // to observe. Same gating convention as api/src/sync/integration.test.ts.
245
+ return;
246
+ }
247
+ const client = makeClient("d4-membership-revoked", userDoc);
248
+ await client.start();
249
+ await waitFor(() => client.getSyncStatus().isOnline, {label: "initial connect"});
250
+
251
+ // Confirm the tenant stream is live: a doc created for org-a arrives as a delta.
252
+ const before = await RevalProjectModel.create({
253
+ organizationId: "org-a",
254
+ title: "before revoke",
255
+ });
256
+ await waitFor(
257
+ () => client.store.getEntity({collection: COLLECTION, id: String(before._id)}) !== undefined,
258
+ {label: "delta before revocation", timeoutMs: 5_000}
259
+ );
260
+
261
+ // Revoke membership — the sweep should leave the sync:revalProjects|tenant:org-a
262
+ // room within one interval.
263
+ memberships.set(String(userDoc._id), []);
264
+ await settleFor(SESSION_REVALIDATION_INTERVAL_MS * 3);
265
+
266
+ // The connection itself stays up (this user is not disabled) — only the
267
+ // stream membership changed.
268
+ expect(client.getSyncStatus().isOnline).toBe(true);
269
+ expect(client.getSyncStatus().paused).toBeUndefined();
270
+
271
+ const after = await RevalProjectModel.create({organizationId: "org-a", title: "after revoke"});
272
+ // Give a fair chance for a (wrongly) delivered delta to arrive, then assert it
273
+ // did not.
274
+ await settleFor(1_000);
275
+ expect(client.store.getEntity({collection: COLLECTION, id: String(after._id)})).toBeUndefined();
276
+
277
+ // Restore membership for hygiene (afterAll doesn't depend on it, but keeps the
278
+ // shared UserModel doc's expectations obvious to a future reader).
279
+ memberships.set(String(userDoc._id), ["org-a"]);
280
+ }, 20_000);
281
+ });
@@ -0,0 +1,320 @@
1
+ // noExplicitAny: Socket.io handler signatures require dynamic args
2
+ // biome-ignore-all lint/suspicious/noExplicitAny: Socket.io handler signatures require dynamic args
3
+ import type {Server} from "socket.io";
4
+
5
+ import type {User} from "../auth";
6
+ import {logger} from "../logger";
7
+ import {checkPermissions} from "../permissions";
8
+ import {awaitSocketFullUser, type SocketWithDecodedToken} from "../realtime/socketUser";
9
+ import type {SyncMutationOutcome} from "./mutationHandler";
10
+ import {findSyncEntryByCollectionTag, type SyncRegistryEntry} from "./registry";
11
+ import type {SyncAppOptions} from "./routes";
12
+ import {MissingScopeResolverError, resolveUserStreamsForEntry} from "./streams";
13
+ import {runSyncBatch, runSyncMutation} from "./syncBatch";
14
+ import type {
15
+ SyncMutateBatchRequest,
16
+ SyncMutateBatchResponse,
17
+ SyncMutateRequest,
18
+ SyncNack,
19
+ } from "./types";
20
+
21
+ /**
22
+ * Socket handlers for the SyncDB local-first protocol:
23
+ *
24
+ * - `sync:subscribe {collections}` / `sync:unsubscribe {collections}` — resolves the
25
+ * caller's streams from the sync registry scope config and joins/leaves `sync:{stream}`
26
+ * rooms. Owner scopes always use the socket's own userId (never a client-supplied one);
27
+ * tenant and custom scopes resolve stream values via `SyncAppOptions.getUserScopes`.
28
+ * Sync deltas fan out through these dedicated `sync:{stream}` rooms rather than the
29
+ * legacy realtime rooms so the two event families never overlap.
30
+ * - `sync:mutate` — applies a mutation through `applySyncMutation` and replies with
31
+ * `sync:ack {mutationId, id, seq}` or `sync:nack {mutationId, code, ...}`; when the
32
+ * client supplied a Socket.io ack callback it also receives `{ack}` / `{nack}`.
33
+ * - `sync:error {collection, message}` — emitted for per-collection subscribe failures
34
+ * (unknown collection, permission denied, missing scope resolver, cap exceeded).
35
+ *
36
+ * ## Wiring
37
+ *
38
+ * `RealtimeApp` installs these handlers on every connection with the `SyncAppOptions`
39
+ * attached to the same Express application, so multiple app instances stay isolated.
40
+ */
41
+
42
+ /** Maximum distinct collection subscriptions per socket (DoS protection). */
43
+ export const MAX_SYNC_COLLECTION_SUBSCRIPTIONS = 50;
44
+
45
+ /**
46
+ * C8: maximum entries accepted in a single `sync:subscribe`/`sync:unsubscribe`
47
+ * `collections` array — checked BEFORE iterating so an oversized array is rejected
48
+ * with no per-entry work.
49
+ */
50
+ export const MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH = 100;
51
+
52
+ /** The Socket.io room a sync stream fans out through. */
53
+ export const syncRoomForStream = (stream: string): string => `sync:${stream}`;
54
+
55
+ /**
56
+ * Minimal shape this module requires from a Socket.io socket. Matches
57
+ * `RealtimeSocketLike` structurally so tests can drive handlers with a mock socket.
58
+ */
59
+ export interface SyncSocketLike extends SocketWithDecodedToken {
60
+ id: string;
61
+ join: (room: string) => Promise<void> | void;
62
+ leave: (room: string) => Promise<void> | void;
63
+ emit: (event: string, payload: unknown) => void;
64
+ on: (event: string, handler: (...args: any[]) => any) => void;
65
+ }
66
+
67
+ /**
68
+ * Resolve the streams a user may subscribe to for a collection. Returns null (after
69
+ * emitting `sync:error`) when the scope cannot be resolved for this user/server config.
70
+ */
71
+ const resolveUserStreams = async ({
72
+ entry,
73
+ user,
74
+ options,
75
+ socket,
76
+ }: {
77
+ entry: SyncRegistryEntry;
78
+ user: User;
79
+ options: SyncAppOptions;
80
+ socket: SyncSocketLike;
81
+ }): Promise<string[] | null> => {
82
+ const collection = entry.collectionTag;
83
+ const emitError = (message: string): void => {
84
+ socket.emit("sync:error", {collection, message});
85
+ };
86
+ try {
87
+ return await resolveUserStreamsForEntry({
88
+ entry,
89
+ getUserScopes: options.getUserScopes,
90
+ user,
91
+ });
92
+ } catch (error: unknown) {
93
+ if (error instanceof MissingScopeResolverError) {
94
+ emitError(error.message);
95
+ return null;
96
+ }
97
+ logger.error(`[sync] getUserScopes threw for ${collection}: ${error}`);
98
+ emitError(`Failed to resolve scopes for ${collection}`);
99
+ return null;
100
+ }
101
+ };
102
+
103
+ /**
104
+ * Install the sync socket handlers on a single socket. Wired into RealtimeApp's
105
+ * connection handler alongside `installRealtimeSocketHandlers`.
106
+ *
107
+ * The `_io` server parameter is accepted for signature symmetry with future fan-out
108
+ * needs; the current handlers only act on the connecting socket.
109
+ */
110
+ export const installSyncSocketHandlers = (
111
+ _io: Server | null,
112
+ socket: SyncSocketLike,
113
+ options: SyncAppOptions = {},
114
+ handlerOptions: {logInfo?: (msg: string) => void} = {}
115
+ ): void => {
116
+ const logInfo = handlerOptions.logInfo ?? ((): void => {});
117
+ const userId = socket.decodedToken?.id;
118
+
119
+ // D2: re-derive the authorizing user on every event rather than capturing it once
120
+ // at install time — `socket.data.fullUser` is loaded at handshake and refreshed by
121
+ // D1's sweep, so a mutation sent after a refresh (e.g. after `organizationIds`
122
+ // changed) sees the current full user, not a handshake-time snapshot.
123
+ //
124
+ // Task 9.21: awaits the handshake load when it is still in flight, closing the window
125
+ // where an event arriving first was authorized against the synthetic JWT-claim user
126
+ // (no membership fields — tenant scopes resolved to nothing).
127
+ const currentUser = (): Promise<User | undefined> => awaitSocketFullUser(socket);
128
+
129
+ // collection tag -> joined sync rooms, for unsubscribe/disconnect cleanup and D4's
130
+ // sweep-time re-resolution. Exposed on socket.data (when present — real sockets
131
+ // always have it; minimal test doubles may not) so the sweep, which runs outside
132
+ // this closure, can read and mutate it directly.
133
+ const subscriptions: Map<string, Set<string>> = socket.data?.syncSubscriptions ?? new Map();
134
+ if (socket.data) {
135
+ socket.data.syncSubscriptions = subscriptions;
136
+ }
137
+
138
+ socket.on("sync:subscribe", async (payload: {collections?: unknown}): Promise<void> => {
139
+ const collections = Array.isArray(payload?.collections) ? payload.collections : null;
140
+ if (!collections) {
141
+ return;
142
+ }
143
+ // C8: reject an oversized array up front (length check before iterating).
144
+ if (collections.length > MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH) {
145
+ logInfo(`[sync] User ${userId} sent an oversized sync:subscribe array`);
146
+ socket.emit("sync:error", {
147
+ collection: "",
148
+ message: `sync:subscribe accepts at most ${MAX_SYNC_SUBSCRIBE_ARRAY_LENGTH} collections`,
149
+ });
150
+ return;
151
+ }
152
+ for (const collection of collections) {
153
+ if (typeof collection !== "string" || collection.length === 0) {
154
+ continue;
155
+ }
156
+ if (subscriptions.has(collection)) {
157
+ // Already subscribed — idempotent.
158
+ continue;
159
+ }
160
+ if (subscriptions.size >= MAX_SYNC_COLLECTION_SUBSCRIPTIONS) {
161
+ logInfo(`[sync] User ${userId} hit sync collection subscription limit`);
162
+ socket.emit("sync:error", {
163
+ collection,
164
+ message: `Sync subscription limit of ${MAX_SYNC_COLLECTION_SUBSCRIPTIONS} collections reached`,
165
+ });
166
+ continue;
167
+ }
168
+ const entry = findSyncEntryByCollectionTag(collection);
169
+ if (!entry) {
170
+ socket.emit("sync:error", {collection, message: `Unknown sync collection: ${collection}`});
171
+ continue;
172
+ }
173
+ const user = await currentUser();
174
+ if (!user) {
175
+ socket.emit("sync:error", {collection, message: "Authentication required"});
176
+ continue;
177
+ }
178
+ if (!(await checkPermissions("list", entry.options.permissions.list, user))) {
179
+ logInfo(`[sync] User ${userId} denied sync subscription for ${collection}`);
180
+ socket.emit("sync:error", {
181
+ collection,
182
+ message: `Access to sync collection ${collection} denied`,
183
+ });
184
+ continue;
185
+ }
186
+ const streams = await resolveUserStreams({entry, options, socket, user});
187
+ if (!streams) {
188
+ continue;
189
+ }
190
+ const rooms = new Set(streams.map(syncRoomForStream));
191
+ for (const room of rooms) {
192
+ await socket.join(room);
193
+ }
194
+ subscriptions.set(collection, rooms);
195
+ socket.emit("sync:subscribed", {collection, streams});
196
+ logInfo(`[sync] User ${userId} subscribed to ${collection}: ${streams.join(", ")}`);
197
+ }
198
+ });
199
+
200
+ socket.on("sync:unsubscribe", async (payload: {collections?: unknown}): Promise<void> => {
201
+ const collections = Array.isArray(payload?.collections) ? payload.collections : null;
202
+ if (!collections) {
203
+ return;
204
+ }
205
+ for (const collection of collections) {
206
+ if (typeof collection !== "string") {
207
+ continue;
208
+ }
209
+ const rooms = subscriptions.get(collection);
210
+ if (!rooms) {
211
+ continue;
212
+ }
213
+ for (const room of rooms) {
214
+ await socket.leave(room);
215
+ }
216
+ subscriptions.delete(collection);
217
+ logInfo(`[sync] User ${userId} unsubscribed from ${collection}`);
218
+ }
219
+ });
220
+
221
+ socket.on(
222
+ "sync:mutate",
223
+ async (payload: SyncMutateRequest, ack?: (response: unknown) => void): Promise<void> => {
224
+ const respond = (outcome: SyncMutationOutcome): void => {
225
+ if (outcome.type === "ack") {
226
+ socket.emit("sync:ack", outcome.ack);
227
+ } else {
228
+ socket.emit("sync:nack", outcome.nack);
229
+ }
230
+ if (typeof ack === "function") {
231
+ ack(outcome.type === "ack" ? {ack: outcome.ack} : {nack: outcome.nack});
232
+ }
233
+ };
234
+ const nack = (partial: Omit<SyncNack, "mutationId">): void => {
235
+ respond({
236
+ nack: {
237
+ mutationId: typeof payload?.mutationId === "string" ? payload.mutationId : "",
238
+ ...partial,
239
+ },
240
+ type: "nack",
241
+ });
242
+ };
243
+
244
+ const user = await currentUser();
245
+ if (!user) {
246
+ nack({code: "unauthorized", message: "Authentication required"});
247
+ return;
248
+ }
249
+
250
+ try {
251
+ // Task 9.20: the rate limit is charged inside the shared runner against this
252
+ // USER's window, so opening more sockets no longer multiplies the budget.
253
+ const {outcome, stage} = await runSyncMutation({
254
+ mutation: payload,
255
+ scopeResolver: options.getUserScopes,
256
+ user,
257
+ });
258
+ if (stage === "rate_limited") {
259
+ logInfo(`[sync] User ${userId} hit the sync:mutate rate limit`);
260
+ }
261
+ respond(outcome);
262
+ } catch (error: unknown) {
263
+ logger.error(`[sync] sync:mutate failed for socket ${socket.id}: ${error}`);
264
+ nack({code: "error", message: "Internal error applying mutation"});
265
+ }
266
+ }
267
+ );
268
+
269
+ socket.on(
270
+ "sync:mutateBatch",
271
+ async (payload: SyncMutateBatchRequest, ack?: (response: unknown) => void): Promise<void> => {
272
+ // FIX 5: emit the receipt IMMEDIATELY, before any processing (including
273
+ // rate-limit/auth checks) — this is what lets the client distinguish
274
+ // "no sync:mutateBatch handler at all" (silence past the grace period)
275
+ // from "the server is just slow finishing this batch" (a receipt
276
+ // arrived; the client then waits the full batch timeout instead of
277
+ // falling back to single sends and possibly double-processing).
278
+ if (typeof payload?.batchId === "string" && payload.batchId.length > 0) {
279
+ socket.emit("sync:batchReceived", {batchId: payload.batchId});
280
+ }
281
+
282
+ const respondBatch = (response: SyncMutateBatchResponse): void => {
283
+ if (typeof ack === "function") {
284
+ ack(response);
285
+ }
286
+ };
287
+ const singleNackBatch = (partial: Omit<SyncNack, "mutationId">, mutationId = ""): void => {
288
+ respondBatch({results: [{nack: {mutationId, ...partial}, type: "nack"}]});
289
+ };
290
+
291
+ const mutations = Array.isArray(payload?.mutations) ? payload.mutations : [];
292
+
293
+ const user = await currentUser();
294
+ if (!user) {
295
+ singleNackBatch({code: "unauthorized", message: "Authentication required"});
296
+ return;
297
+ }
298
+
299
+ try {
300
+ // Task 9.20: validate -> rate limit -> apply, shared with POST /sync/mutate/batch.
301
+ const {response, stage} = await runSyncBatch({
302
+ mutations,
303
+ scopeResolver: options.getUserScopes,
304
+ user,
305
+ });
306
+ if (stage === "rate_limited") {
307
+ logInfo(`[sync] User ${userId} hit the sync:mutateBatch rate limit`);
308
+ }
309
+ respondBatch(response);
310
+ } catch (error: unknown) {
311
+ logger.error(`[sync] sync:mutateBatch failed for socket ${socket.id}: ${error}`);
312
+ singleNackBatch({code: "error", message: "Internal error applying batch"});
313
+ }
314
+ }
315
+ );
316
+
317
+ socket.on("disconnect", () => {
318
+ subscriptions.clear();
319
+ });
320
+ };