@terreno/api 57.21.0 → 58.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 (121) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/README.md +1 -1
  3. package/dist/api.d.ts +0 -13
  4. package/dist/api.js +0 -9
  5. package/dist/auth.d.ts +3 -2
  6. package/dist/auth.js +95 -5
  7. package/dist/authRecovery.d.ts +2 -1
  8. package/dist/authRecovery.js +35 -17
  9. package/dist/collectionRegistry.d.ts +3 -4
  10. package/dist/collectionRegistry.js +0 -1
  11. package/dist/consentApp.d.ts +1 -1
  12. package/dist/consentApp.js +58 -2
  13. package/dist/index.d.ts +4 -5
  14. package/dist/index.js +8 -20
  15. package/dist/mcp/adminTracking.js +1 -1
  16. package/dist/mcp/serviceTokens.d.ts +21 -1
  17. package/dist/mcp/serviceTokens.js +159 -183
  18. package/dist/migrations/builtin/mcpServiceTokenStringIds.d.ts +18 -0
  19. package/dist/migrations/builtin/mcpServiceTokenStringIds.js +67 -0
  20. package/dist/models/mcpRequestLog.js +1 -1
  21. package/dist/models/mcpServiceToken.js +36 -4
  22. package/dist/openApiBuilder.d.ts +4 -0
  23. package/dist/openApiBuilder.js +2 -0
  24. package/dist/rbac/realtimeAccess.d.ts +5 -4
  25. package/dist/rbac/realtimeAccess.js +17 -64
  26. package/dist/realtime/changeStreamWatcher.d.ts +8 -63
  27. package/dist/realtime/changeStreamWatcher.js +32 -391
  28. package/dist/realtime/realtimeApp.d.ts +14 -27
  29. package/dist/realtime/realtimeApp.js +14 -220
  30. package/dist/realtime/types.d.ts +0 -64
  31. package/dist/sync/entityIds.d.ts +14 -0
  32. package/dist/sync/entityIds.js +17 -0
  33. package/dist/sync/executors.js +14 -2
  34. package/dist/sync/models.d.ts +1 -0
  35. package/dist/sync/models.js +4 -0
  36. package/dist/sync/mutationHandler.js +51 -2
  37. package/dist/sync/routes.js +12 -17
  38. package/dist/sync/socketHandlers.d.ts +1 -1
  39. package/dist/sync/socketHandlers.js +1 -1
  40. package/dist/sync/types.d.ts +8 -0
  41. package/dist/terrenoApp.d.ts +7 -5
  42. package/dist/terrenoApp.js +18 -14
  43. package/dist/tests/openApiResponseSchema.d.ts +39 -0
  44. package/dist/tests/openApiResponseSchema.js +56 -0
  45. package/dist/tests.d.ts +1 -0
  46. package/dist/tests.js +4 -1
  47. package/dist/types/mcpAdmin.d.ts +1 -1
  48. package/dist/types/mcpServiceToken.d.ts +7 -4
  49. package/dist/versionCheckPlugin.d.ts +1 -1
  50. package/dist/versionCheckPlugin.js +25 -2
  51. package/package.json +17 -6
  52. package/src/__snapshots__/openApi.test.ts.snap +4986 -2478
  53. package/src/__snapshots__/openApiBuilder.test.ts.snap +836 -0
  54. package/src/__tests__/openApiResponseSchema.test.ts +148 -0
  55. package/src/__tests__/versionCheckPlugin.test.ts +72 -0
  56. package/src/api.test.ts +9 -7
  57. package/src/api.ts +0 -24
  58. package/src/auth.ts +116 -5
  59. package/src/authOpenApi.test.ts +316 -0
  60. package/src/authRecovery.ts +47 -19
  61. package/src/betterAuthOAuthHandoff.test.ts +13 -5
  62. package/src/collectionRegistry.ts +3 -5
  63. package/src/consentApp.test.ts +98 -0
  64. package/src/consentApp.ts +67 -2
  65. package/src/index.ts +6 -28
  66. package/src/mcp/actionTools.test.ts +2 -2
  67. package/src/mcp/adminTracking.ts +1 -1
  68. package/src/mcp/auth.test.ts +7 -3
  69. package/src/mcp/oauth.test.ts +12 -12
  70. package/src/mcp/serviceTokens.sync.test.ts +230 -0
  71. package/src/mcp/serviceTokens.test.ts +112 -61
  72. package/src/mcp/serviceTokens.ts +193 -212
  73. package/src/migrations/builtin/mcpServiceTokenStringIds.test.ts +194 -0
  74. package/src/migrations/builtin/mcpServiceTokenStringIds.ts +121 -0
  75. package/src/models/mcpRequestLog.ts +1 -1
  76. package/src/models/mcpServiceToken.test.ts +52 -5
  77. package/src/models/mcpServiceToken.ts +51 -14
  78. package/src/openApiBuilder.test.ts +34 -1
  79. package/src/openApiBuilder.ts +5 -0
  80. package/src/rateLimit/rateLimit.test.ts +25 -10
  81. package/src/rbac/realtimeAccess.test.ts +20 -172
  82. package/src/rbac/realtimeAccess.ts +17 -82
  83. package/src/realtime/changeStreamWatcher.ts +43 -506
  84. package/src/realtime/realtime.test.ts +205 -2545
  85. package/src/realtime/realtimeApp.ts +16 -295
  86. package/src/realtime/types.ts +0 -72
  87. package/src/sync/entityIds.ts +18 -0
  88. package/src/sync/executors.test.ts +28 -0
  89. package/src/sync/executors.ts +23 -2
  90. package/src/sync/models.ts +6 -0
  91. package/src/sync/mutationHandler.test.ts +84 -0
  92. package/src/sync/mutationHandler.ts +57 -2
  93. package/src/sync/routes.ts +12 -17
  94. package/src/sync/socketHandlers.ts +1 -1
  95. package/src/sync/syncRoutes.test.ts +8 -4
  96. package/src/sync/syncSocket.test.ts +77 -113
  97. package/src/sync/types.ts +9 -0
  98. package/src/terrenoApp.mcpServiceTokens.test.ts +14 -6
  99. package/src/terrenoApp.ts +24 -18
  100. package/src/tests/openApiResponseSchema.ts +104 -0
  101. package/src/tests.ts +7 -0
  102. package/src/types/mcpAdmin.ts +1 -1
  103. package/src/types/mcpServiceToken.ts +7 -4
  104. package/src/versionCheckPlugin.ts +41 -2
  105. package/biome.jsonc +0 -22
  106. package/bunfig.toml +0 -10
  107. package/bunfig.unit.toml +0 -3
  108. package/dist/realtime/deprecation.d.ts +0 -13
  109. package/dist/realtime/deprecation.js +0 -31
  110. package/dist/realtime/queryStore.d.ts +0 -37
  111. package/dist/realtime/queryStore.js +0 -103
  112. package/dist/realtime/registry.d.ts +0 -15
  113. package/dist/realtime/registry.js +0 -52
  114. package/e2e/smoke.ts +0 -193
  115. package/src/realtime/deprecation.test.ts +0 -60
  116. package/src/realtime/deprecation.ts +0 -33
  117. package/src/realtime/queryStore.ts +0 -122
  118. package/src/realtime/registry.ts +0 -84
  119. package/tsconfig.json +0 -19
  120. package/tsconfig.typecheck.json +0 -14
  121. package/tsconfig.typedoc.json +0 -13
@@ -3,40 +3,24 @@ import * as Sentry from "@sentry/bun";
3
3
  import type express from "express";
4
4
  import {Server, type Socket} from "socket.io";
5
5
 
6
- import type {User, UserModel} from "../auth";
6
+ import type {UserModel} from "../auth";
7
7
  import {findBetterAuthProvider, getProvidedBetterAuth} from "../betterAuthApp";
8
8
  import {APIError} from "../errors";
9
9
  import {logger} from "../logger";
10
- import {canSubscribeRealtime} from "../rbac/realtimeAccess";
11
10
  import {warnOnSyncScopesWithoutUserModel} from "../sync/registry";
12
11
  import {installSyncSocketHandlers} from "../sync/socketHandlers";
13
12
  import {getSyncAppOptions} from "../sync/syncApp";
14
13
  import type {TerrenoApp} from "../terrenoApp";
15
14
  import type {TerrenoPlugin} from "../terrenoPlugin";
16
15
  import {startChangeStreamWatcher, stopChangeStreamWatcher} from "./changeStreamWatcher";
17
- import {
18
- addQuerySubscription,
19
- computeQueryId,
20
- removeAllSocketQueries,
21
- removeQuerySubscription,
22
- } from "./queryStore";
23
- import {findRegistryEntryByRoutePath, type RealtimeRegistryEntry} from "./registry";
24
16
  import {
25
17
  loadFullUserForSocket,
26
18
  type SessionRevalidationHandle,
27
19
  startSessionRevalidationSweep,
28
20
  } from "./sessionRevalidation";
29
21
  import {type BetterAuthSocketOptions, createSocketAuthMiddleware} from "./socketAuth";
30
- import {getSocketUser, type SocketDataBag, type SocketWithDecodedToken} from "./socketUser";
31
- import type {DocumentSubscription, QuerySubscription, RealtimeAppOptions} from "./types";
32
-
33
- /**
34
- * Caps on per-socket subscriptions. Prevents a malicious or buggy client from
35
- * exhausting server memory by opening unbounded subscriptions.
36
- */
37
- export const MAX_MODEL_SUBSCRIPTIONS = 50;
38
- export const MAX_DOCUMENT_SUBSCRIPTIONS = 500;
39
- export const MAX_QUERY_SUBSCRIPTIONS = 100;
22
+ import type {SocketDataBag, SocketWithDecodedToken} from "./socketUser";
23
+ import type {RealtimeAppOptions} from "./types";
40
24
 
41
25
  /**
42
26
  * Replace any userinfo (`user:password@`) component in a URL with `***@` so the
@@ -74,91 +58,14 @@ export interface RealtimeSocketLike extends SocketWithDecodedToken {
74
58
  on: (event: string, handler: (...args: never[]) => void | Promise<void>) => void;
75
59
  }
76
60
 
77
- const LOGICAL_QUERY_KEYS = new Set(["$and", "$or"]);
78
-
79
- const isPlainQueryObject = (value: unknown): value is Record<string, unknown> =>
80
- typeof value === "object" && value !== null && !Array.isArray(value);
81
-
82
61
  /**
83
- * Returns the first field a client query names outside `queryFields`, walking `$and` / `$or`
84
- * clauses, or undefined when every field is allowed. A query room's event method reveals
85
- * whether a document matches, so subscriptions may only filter on the fields REST list
86
- * accepts.
87
- */
88
- const findDisallowedQueryField = (
89
- query: Record<string, unknown>,
90
- queryFields: string[]
91
- ): string | undefined => {
92
- for (const [key, condition] of Object.entries(query)) {
93
- if (LOGICAL_QUERY_KEYS.has(key)) {
94
- if (!Array.isArray(condition)) {
95
- return key;
96
- }
97
- for (const clause of condition) {
98
- if (!isPlainQueryObject(clause)) {
99
- return key;
100
- }
101
- const nested = findDisallowedQueryField(clause, queryFields);
102
- if (nested) {
103
- return nested;
104
- }
105
- }
106
- continue;
107
- }
108
- if (!queryFields.includes(key)) {
109
- return key;
110
- }
111
- }
112
- return undefined;
113
- };
114
-
115
- const canSubscribe = async (
116
- entry: RealtimeRegistryEntry,
117
- method: "list" | "read",
118
- user?: User
119
- ): Promise<boolean> => canSubscribeRealtime(entry, method, user);
120
-
121
- const getAuthorizedQuery = async (
122
- entry: RealtimeRegistryEntry,
123
- query: Record<string, unknown>,
124
- user?: User
125
- ): Promise<Record<string, unknown> | null> => {
126
- if (!(await canSubscribe(entry, "list", user))) {
127
- return null;
128
- }
129
-
130
- if (!entry.options.queryFilter) {
131
- return query;
132
- }
133
-
134
- let filteredQuery: Record<string, unknown> | null;
135
- try {
136
- filteredQuery = await entry.options.queryFilter(user, query);
137
- } catch (error) {
138
- logger.error(
139
- `[realtime] queryFilter threw for ${entry.modelName}/list: ${error}. Denying query subscription.`
140
- );
141
- Sentry.captureException(error);
142
- return null;
143
- }
144
-
145
- if (filteredQuery === null) {
146
- return null;
147
- }
148
-
149
- return {...query, ...filteredQuery};
150
- };
151
-
152
- /**
153
- * Install the realtime subscription handlers on a single socket. Extracted from the
154
- * RealtimeApp connection handler so this logic can be unit-tested with a mock socket
155
- * (no real Socket.io / HTTP server / JWT handshake required).
62
+ * Install the base socket handlers on a single socket: join the per-user, `authenticated`,
63
+ * and (for admins) `admin` rooms, and log disconnects. Extracted from the RealtimeApp
64
+ * connection handler so it can be unit-tested with a mock socket (no real Socket.io /
65
+ * HTTP server / JWT handshake required).
156
66
  *
157
- * Enforces:
158
- * - per-socket subscription caps (DoS protection)
159
- * - registry membership (only realtime-enabled collections can be subscribed)
160
- * - owner-strategy isolation (non-admin users cannot subscribe to other users' rooms)
161
- * - server-side queryId computation (clients can't hijack queries by colliding ids)
67
+ * Collection subscriptions go through the sync protocol (`sync:subscribe`), installed
68
+ * separately by `installSyncSocketHandlers`.
162
69
  */
163
70
  export const installRealtimeSocketHandlers = (
164
71
  socket: RealtimeSocketLike,
@@ -167,11 +74,6 @@ export const installRealtimeSocketHandlers = (
167
74
  const logInfo = options.logInfo ?? ((): void => {});
168
75
  const userId = socket.decodedToken?.id;
169
76
  const isAdmin = socket.decodedToken?.admin === true;
170
- // D2: re-derive per event rather than capturing once at install time, so a
171
- // handshake-time-loaded full user (or one refreshed by D1's sweep) is always used.
172
- const currentUser = (): User | undefined => getSocketUser(socket);
173
-
174
- const counts = {document: 0, model: 0, query: 0};
175
77
 
176
78
  const joinUserRooms = async (): Promise<void> => {
177
79
  if (userId) {
@@ -188,201 +90,19 @@ export const installRealtimeSocketHandlers = (
188
90
  // Fire-and-forget — there is nothing useful for the caller to await.
189
91
  void joinUserRooms();
190
92
 
191
- socket.on("subscribe:model", async (modelName: string): Promise<void> => {
192
- if (typeof modelName !== "string" || modelName.length === 0) {
193
- return;
194
- }
195
- if (counts.model >= MAX_MODEL_SUBSCRIPTIONS) {
196
- logInfo(`[realtime] User ${userId} hit model subscription limit`);
197
- return;
198
- }
199
-
200
- const entry = findRegistryEntryByRoutePath(modelName);
201
- if (!entry) {
202
- logInfo(
203
- `[realtime] User ${userId} denied model subscription: collection "${modelName}" not registered`
204
- );
205
- return;
206
- }
207
-
208
- // Owner-strategy models fan out via user:{ownerId} — there is no shared model room
209
- // that should be open to all users. Owners receive events through their user room
210
- // automatically; admins can use the admin room to see everything.
211
- if (entry.config.roomStrategy === "owner" && !isAdmin) {
212
- logInfo(
213
- `[realtime] User ${userId} denied model subscription for ${modelName}: ` +
214
- "owner strategy restricts model room to admins"
215
- );
216
- return;
217
- }
218
-
219
- if (!(await canSubscribe(entry, "list", currentUser()))) {
220
- logInfo(
221
- `[realtime] User ${userId} denied model subscription for ${modelName}: list permission denied`
222
- );
223
- return;
224
- }
225
-
226
- counts.model += 1;
227
- await socket.join(`model:${modelName}`);
228
- logInfo(`[realtime] User ${userId} subscribed to model:${modelName}`);
229
- });
230
-
231
- socket.on("unsubscribe:model", async (modelName: string): Promise<void> => {
232
- if (typeof modelName === "string" && modelName.length > 0) {
233
- await socket.leave(`model:${modelName}`);
234
- counts.model = Math.max(0, counts.model - 1);
235
- logInfo(`[realtime] User ${userId} unsubscribed from model:${modelName}`);
236
- }
237
- });
238
-
239
- socket.on("subscribe:document", async (payload: DocumentSubscription): Promise<void> => {
240
- if (
241
- !payload?.collection ||
242
- !payload?.id ||
243
- typeof payload.collection !== "string" ||
244
- typeof payload.id !== "string"
245
- ) {
246
- return;
247
- }
248
- if (counts.document >= MAX_DOCUMENT_SUBSCRIPTIONS) {
249
- logInfo(`[realtime] User ${userId} hit document subscription limit`);
250
- return;
251
- }
252
-
253
- const entry = findRegistryEntryByRoutePath(payload.collection);
254
- if (!entry) {
255
- logInfo(
256
- `[realtime] User ${userId} denied document subscription: ` +
257
- `collection "${payload.collection}" not registered`
258
- );
259
- return;
260
- }
261
-
262
- if (!(await canSubscribe(entry, "read", currentUser()))) {
263
- logInfo(
264
- `[realtime] User ${userId} denied document subscription for ` +
265
- `${payload.collection}/${payload.id}: read permission denied`
266
- );
267
- return;
268
- }
269
-
270
- if (entry.config.roomStrategy === "owner" && !isAdmin) {
271
- logInfo(
272
- `[realtime] User ${userId} denied document subscription for ` +
273
- `${payload.collection}/${payload.id}: owner strategy requires admin`
274
- );
275
- return;
276
- }
277
-
278
- counts.document += 1;
279
- const room = `document:${payload.collection}:${payload.id}`;
280
- await socket.join(room);
281
- logInfo(`[realtime] User ${userId} subscribed to ${room}`);
282
- });
283
-
284
- socket.on("unsubscribe:document", async (payload: DocumentSubscription): Promise<void> => {
285
- if (payload?.collection && payload?.id) {
286
- const room = `document:${payload.collection}:${payload.id}`;
287
- await socket.leave(room);
288
- counts.document = Math.max(0, counts.document - 1);
289
- logInfo(`[realtime] User ${userId} unsubscribed from ${room}`);
290
- }
291
- });
292
-
293
- socket.on("subscribe:query", async (payload: QuerySubscription): Promise<void> => {
294
- if (
295
- !payload?.collection ||
296
- !payload?.query ||
297
- typeof payload.collection !== "string" ||
298
- typeof payload.query !== "object" ||
299
- Array.isArray(payload.query)
300
- ) {
301
- return;
302
- }
303
- if (counts.query >= MAX_QUERY_SUBSCRIPTIONS) {
304
- logInfo(`[realtime] User ${userId} hit query subscription limit`);
305
- return;
306
- }
307
-
308
- const entry = findRegistryEntryByRoutePath(payload.collection);
309
- if (!entry) {
310
- logInfo(
311
- `[realtime] User ${userId} denied query subscription: ` +
312
- `collection "${payload.collection}" not registered`
313
- );
314
- return;
315
- }
316
-
317
- const disallowedField = findDisallowedQueryField(
318
- payload.query,
319
- entry.options.queryFields ?? []
320
- );
321
- if (disallowedField) {
322
- logInfo(
323
- `[realtime] User ${userId} denied query subscription for ${payload.collection}: ` +
324
- `${disallowedField} is not in queryFields`
325
- );
326
- return;
327
- }
328
-
329
- let query = await getAuthorizedQuery(entry, {...payload.query}, currentUser());
330
- if (!query) {
331
- logInfo(
332
- `[realtime] User ${userId} denied query subscription for ${payload.collection}: ` +
333
- "list permission or query filter denied"
334
- );
335
- return;
336
- }
337
-
338
- if (entry.config.roomStrategy === "owner" && !isAdmin) {
339
- if (!userId) {
340
- return;
341
- }
342
- query = {...query, ownerId: userId};
343
- }
344
-
345
- const queryId = computeQueryId(payload.collection, query);
346
-
347
- addQuerySubscription(socket.id, payload.collection, query, queryId);
348
- counts.query += 1;
349
- await socket.join(`query:${queryId}`);
350
- socket.emit("query:subscribed", {
351
- clientQueryId: payload.queryId,
352
- collection: payload.collection,
353
- queryId,
354
- });
355
- logInfo(`[realtime] User ${userId} subscribed to query:${queryId} on ${payload.collection}`);
356
- });
357
-
358
- socket.on("unsubscribe:query", async (payload: {queryId: string}): Promise<void> => {
359
- if (payload?.queryId) {
360
- removeQuerySubscription(socket.id, payload.queryId);
361
- await socket.leave(`query:${payload.queryId}`);
362
- counts.query = Math.max(0, counts.query - 1);
363
- logInfo(`[realtime] User ${userId} unsubscribed from query:${payload.queryId}`);
364
- }
365
- });
366
-
367
93
  socket.on("disconnect", () => {
368
- removeAllSocketQueries(socket.id);
369
94
  logInfo(`[realtime] User ${userId} disconnected`);
370
95
  });
371
96
  };
372
97
 
373
98
  /**
374
- * TerrenoPlugin that provides real-time sync via Socket.io and MongoDB change streams.
99
+ * TerrenoPlugin that hosts Socket.io and the MongoDB change stream watcher for
100
+ * `@terreno/syncdb`.
375
101
  *
376
102
  * Attaches a Socket.io server to the HTTP server created by TerrenoApp.start(),
377
- * sets up JWT and/or Better Auth authentication for socket connections, manages room subscriptions
378
- * (model, document, and query rooms), and starts a change stream watcher that
379
- * emits events to connected clients.
380
- *
381
- * ## Subscription types
382
- *
383
- * - **Model rooms**: `subscribe:model` / `unsubscribe:model` — receive all events for a collection
384
- * - **Document rooms**: `subscribe:document` / `unsubscribe:document` — receive events for a single document
385
- * - **Query rooms**: `subscribe:query` / `unsubscribe:query` — receive events matching a MongoDB query
103
+ * sets up JWT and/or Better Auth authentication for socket connections, installs the
104
+ * sync protocol handlers (`sync:subscribe` / `sync:mutate`), and starts a change stream
105
+ * watcher that emits `sync:delta` events for models registered with `sync`.
386
106
  *
387
107
  * @example
388
108
  * ```typescript
@@ -390,7 +110,8 @@ export const installRealtimeSocketHandlers = (
390
110
  * userModel: User,
391
111
  * realtime: { debug: true },
392
112
  * })
393
- * .register(todoRouter) // todoRouter has realtime config
113
+ * .register(todoRouter) // todoRouter has a `sync` config
114
+ * .register(new SyncApp())
394
115
  * .start();
395
116
  * ```
396
117
  */
@@ -1,59 +1,9 @@
1
- import type express from "express";
2
1
  import type {Server as SocketIoServer} from "socket.io";
3
2
  import type {UserModel} from "../auth";
4
3
  import type {SyncAppOptions} from "../sync/routes";
5
4
  import type {startChangeStreamWatcher} from "./changeStreamWatcher";
6
5
  import type {BetterAuthSocketOptions} from "./socketAuth";
7
6
 
8
- /**
9
- * Configuration for real-time sync on a modelRouter.
10
- * Determines which CRUD methods emit WebSocket events and how they are routed.
11
- *
12
- * @deprecated Removed in Terreno 58. Use `sync` on modelRouter with `@terreno/syncdb`.
13
- * `RealtimeApp` remains required for sync sockets.
14
- */
15
- export interface RealtimeConfig {
16
- /** Which CRUD methods should emit real-time sync events */
17
- methods: Array<"create" | "update" | "delete">;
18
- /**
19
- * Strategy for determining which Socket.io rooms receive events.
20
- * - 'owner': emit to `user:{doc.ownerId}` room
21
- * - 'model': emit to `model:{modelName}` room (clients must subscribe)
22
- * - 'broadcast': emit to all authenticated sockets
23
- * - function: custom room resolver returning room name(s)
24
- */
25
- roomStrategy:
26
- | "owner"
27
- | "model"
28
- | "broadcast"
29
- | ((doc: Record<string, unknown>, method: string, req: express.Request) => string[]);
30
- /** Custom serializer for real-time events. Falls back to the modelRouter responseHandler. */
31
- realtimeResponseHandler?: (doc: Record<string, unknown>, method: string) => unknown;
32
- }
33
-
34
- /**
35
- * A real-time sync event emitted to clients via WebSocket.
36
- *
37
- * @deprecated Removed in Terreno 58 with modelRouter `realtime` and the RTK
38
- * cache-patching helpers. Syncdb uses `sync:delta` events instead.
39
- */
40
- export interface RealtimeEvent {
41
- /** Mongoose model name (e.g. "Todo") */
42
- model: string;
43
- /** Route path used as tag type (e.g. "todos") */
44
- collection: string;
45
- /** The CRUD method that triggered this event */
46
- method: "create" | "update" | "delete";
47
- /** Document ID */
48
- id: string;
49
- /** Serialized document data (omitted for hard deletes) */
50
- data?: unknown;
51
- /** Fields that were updated (for update events from change streams) */
52
- updatedFields?: string[];
53
- /** Epoch milliseconds when the event was generated */
54
- timestamp: number;
55
- }
56
-
57
7
  /**
58
8
  * Configuration for the MongoDB change stream watcher.
59
9
  */
@@ -150,25 +100,3 @@ export interface RealtimeAppOptions {
150
100
  */
151
101
  startChangeStreamWatcher?: typeof startChangeStreamWatcher;
152
102
  }
153
-
154
- /**
155
- * Payload sent by the client to subscribe to a single document's changes.
156
- */
157
- export interface DocumentSubscription {
158
- /** Collection tag (e.g. "todos") */
159
- collection: string;
160
- /** Document ID */
161
- id: string;
162
- }
163
-
164
- /**
165
- * Payload sent by the client to subscribe to a query-filtered list.
166
- */
167
- export interface QuerySubscription {
168
- /** Collection tag (e.g. "todos") */
169
- collection: string;
170
- /** MongoDB-style query filter (e.g. {completed: false}) */
171
- query: Record<string, unknown>;
172
- /** Client-provided queryId (ignored — server computes a canonical ID) */
173
- queryId?: string;
174
- }
@@ -0,0 +1,18 @@
1
+ import type mongoose from "mongoose";
2
+
3
+ const OBJECT_ID_HEX = /^[0-9a-fA-F]{24}$/;
4
+
5
+ /**
6
+ * True for a 24-character hex string. Stricter than `mongoose.isValidObjectId`, which also
7
+ * accepts any 12-character string as raw ObjectId bytes.
8
+ */
9
+ export const isObjectIdHex = (id: unknown): id is string =>
10
+ typeof id === "string" && OBJECT_ID_HEX.test(id);
11
+
12
+ /**
13
+ * True when the model keys documents by ObjectId. Synced ObjectId models take client-minted
14
+ * ObjectId hex ids (syncdb `idFormats: {collection: "objectId"}`); String-keyed models take
15
+ * any id shape (syncdb's UUID default).
16
+ */
17
+ export const isObjectIdKeyed = (model: {schema?: mongoose.Schema}): boolean =>
18
+ (model.schema?.path("_id") as {instance?: string} | undefined)?.instance === "ObjectId";
@@ -465,6 +465,34 @@ describe("executeUpdate", () => {
465
465
  expect(error.status).toBe(404);
466
466
  });
467
467
 
468
+ it("gives preUpdate the document id as req.params.id when no request is passed", async () => {
469
+ const doc = await createDoc();
470
+ const seenIds: unknown[] = [];
471
+ const options = baseOptions({
472
+ preUpdate: (body, req) => {
473
+ seenIds.push(req.params.id);
474
+ return body as ExecStuff;
475
+ },
476
+ });
477
+ await executeUpdate<ExecStuff>({
478
+ body: {name: "renamed"},
479
+ id: doc._id.toString(),
480
+ model: ExecStuffModel,
481
+ options,
482
+ user: owner,
483
+ });
484
+ // A socket sync mutation passes a `{user}` request that has no params.
485
+ await executeUpdate<ExecStuff>({
486
+ body: {name: "renamed again"},
487
+ id: doc._id.toString(),
488
+ model: ExecStuffModel,
489
+ options,
490
+ req: {user: owner} as unknown as express.Request,
491
+ user: owner,
492
+ });
493
+ expect(seenIds).toEqual([doc._id.toString(), doc._id.toString()]);
494
+ });
495
+
468
496
  it("returns 403 when preUpdate returns null", async () => {
469
497
  const doc = await createDoc();
470
498
  const options = baseOptions({preUpdate: () => null});
@@ -146,6 +146,27 @@ export const isExecutorConflictError = (error: unknown): error is ExecutorConfli
146
146
  */
147
147
  const stubRequest = (user?: User): express.Request => ({user}) as unknown as express.Request;
148
148
 
149
+ /**
150
+ * The request a hook sees for an update or delete of `id`. Over HTTP it is the real request. Over
151
+ * sync it is a stub (or the socket's `{user}` object) with no `params`, so `params.id` is filled
152
+ * in, as in the REST routes: hooks that read `req.params.id` must work over sync too.
153
+ */
154
+ const requestForId = ({
155
+ id,
156
+ req,
157
+ user,
158
+ }: {
159
+ id: string;
160
+ req?: express.Request;
161
+ user?: User;
162
+ }): express.Request => {
163
+ const request = req ?? stubRequest(user);
164
+ if (request.params === undefined) {
165
+ request.params = {id};
166
+ }
167
+ return request;
168
+ };
169
+
149
170
  /**
150
171
  * True for the Mongoose error thrown when an `optimisticConcurrency` save matched no
151
172
  * document (its `__v` filter failed) — i.e. another write landed since the load.
@@ -523,7 +544,7 @@ export const executeUpdate = async <T>({
523
544
  /** When true, skip modelRouter permission checks (admin-window sync mutations). */
524
545
  skipPermissionChecks?: boolean;
525
546
  }): Promise<ExecutorResult<T>> => {
526
- const request = req ?? stubRequest(user);
547
+ const request = requestForId({id, req, user});
527
548
 
528
549
  if (
529
550
  !skipPermissionChecks &&
@@ -805,7 +826,7 @@ export const executeDelete = async <T>({
805
826
  /** When true, skip modelRouter permission checks (admin-window sync mutations). */
806
827
  skipPermissionChecks?: boolean;
807
828
  }): Promise<ExecutorResult<T>> => {
808
- const request = req ?? stubRequest(user);
829
+ const request = requestForId({id, req, user});
809
830
 
810
831
  if (
811
832
  !skipPermissionChecks &&
@@ -440,6 +440,7 @@ export interface SyncMutationDocument {
440
440
  collectionTag?: string;
441
441
  status: SyncMutationStatus;
442
442
  nackCode?: string;
443
+ nackReason?: string;
443
444
  resultId?: string;
444
445
  resultSeq?: number;
445
446
  error?: string;
@@ -493,6 +494,11 @@ const syncMutationSchema = new Schema<SyncMutationDocument>(
493
494
  "Nack code recorded for rejected mutations (conflict/unauthorized/validation/error)",
494
495
  type: String,
495
496
  },
497
+ nackReason: {
498
+ description:
499
+ "Why a validation nack rejected the mutation's entity id (id_collision/invalid_id)",
500
+ type: String,
501
+ },
496
502
  resultId: {
497
503
  description:
498
504
  "The affected document id, recorded when the mutation is applied or conflicts; a " +
@@ -908,6 +908,90 @@ describe("applySyncMutation", () => {
908
908
  expect(nack.message).toContain("Unknown sync collection");
909
909
  });
910
910
 
911
+ it("nacks invalid_id for a non-hex id on an ObjectId-keyed collection, for every operation", async () => {
912
+ const doc = await MutStuffModel.create({name: "keyed", ownerId: owner.id});
913
+ const badIds = [crypto.randomUUID(), "abcdefghijkl", `${String(doc._id)}0`];
914
+ for (const [index, id] of badIds.entries()) {
915
+ for (const operation of ["create", "update", "delete"] as const) {
916
+ const mutationId = `m-bad-id-${operation}-${index}`;
917
+ const nack = expectNack(
918
+ await applySyncMutation({
919
+ mutation: {
920
+ baseVersion: 1,
921
+ collection: "mutStuff",
922
+ data: {name: "bad id", ownerId: owner.id},
923
+ id,
924
+ mutationId,
925
+ operation,
926
+ },
927
+ user: owner,
928
+ })
929
+ );
930
+ assert.equal(nack.code, "validation");
931
+ assert.equal(nack.reason, "invalid_id");
932
+ // Rejected before the claim: nothing to replay, nothing written.
933
+ assert.equal(await SyncMutation.countDocuments({mutationId}), 0);
934
+ }
935
+ }
936
+ assert.equal(await MutStuffModel.countDocuments({}), 1);
937
+ });
938
+
939
+ it("accepts any id shape on a String-keyed collection", async () => {
940
+ clearSyncRegistry();
941
+ registerSync({
942
+ config: {scope: {type: "owner"}},
943
+ model: MutOtherModel,
944
+ options: ownerOptions,
945
+ routePath: "/mutOther",
946
+ });
947
+ const id = crypto.randomUUID();
948
+ const ack = expectAck(
949
+ await applySyncMutation({
950
+ mutation: {
951
+ collection: "mutOther",
952
+ data: {name: "uuid", ownerId: owner.id},
953
+ id,
954
+ mutationId: "m-uuid-ok",
955
+ operation: "create",
956
+ },
957
+ user: owner,
958
+ })
959
+ );
960
+ assert.equal(ack.id, id);
961
+ await MutOtherModel.collection.deleteMany({});
962
+ });
963
+
964
+ it("nacks id_collision when a create names an _id another document holds", async () => {
965
+ const taken = await MutStuffModel.create({name: "theirs", ownerId: stranger.id});
966
+ const create = (): Promise<SyncMutationOutcome> =>
967
+ applySyncMutation({
968
+ mutation: {
969
+ collection: "mutStuff",
970
+ data: {name: "mine", ownerId: owner.id},
971
+ id: String(taken._id),
972
+ mutationId: "m-collision",
973
+ operation: "create",
974
+ },
975
+ user: owner,
976
+ });
977
+
978
+ const nack = expectNack(await create());
979
+ assert.equal(nack.code, "validation");
980
+ assert.equal(nack.reason, "id_collision");
981
+ assert.equal(nack.message, "Entity id already exists");
982
+ assert.notInclude(JSON.stringify(nack), stranger.id);
983
+ const stored = await MutStuffModel.findById(taken._id);
984
+ assert.equal(stored?.name, "theirs");
985
+ assert.equal(stored?.ownerId, stranger.id);
986
+
987
+ // A duplicate delivery replays the recorded nack, reason included.
988
+ const replayed = expectNack(await create());
989
+ assert.equal(replayed.reason, "id_collision");
990
+ const row = await SyncMutation.findOne({mutationId: "m-collision"});
991
+ assert.equal(row?.status, "failed");
992
+ assert.equal(row?.nackReason, "id_collision");
993
+ });
994
+
911
995
  it("nacks validation when an update omits baseVersion", async () => {
912
996
  const doc = await MutStuffModel.create({name: "no base", ownerId: owner.id});
913
997
  const nack = expectNack(