@terreno/api 57.21.0 → 58.0.0-beta.1

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 (101) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/README.md +1 -1
  3. package/biome.jsonc +2 -2
  4. package/dist/api.d.ts +0 -13
  5. package/dist/api.js +0 -9
  6. package/dist/auth.d.ts +3 -2
  7. package/dist/auth.js +95 -5
  8. package/dist/authRecovery.d.ts +2 -1
  9. package/dist/authRecovery.js +35 -17
  10. package/dist/collectionRegistry.d.ts +3 -4
  11. package/dist/collectionRegistry.js +0 -1
  12. package/dist/consentApp.d.ts +1 -1
  13. package/dist/consentApp.js +58 -2
  14. package/dist/index.d.ts +4 -5
  15. package/dist/index.js +8 -20
  16. package/dist/mcp/adminTracking.js +1 -1
  17. package/dist/mcp/serviceTokens.d.ts +21 -1
  18. package/dist/mcp/serviceTokens.js +159 -183
  19. package/dist/migrations/builtin/mcpServiceTokenStringIds.d.ts +18 -0
  20. package/dist/migrations/builtin/mcpServiceTokenStringIds.js +67 -0
  21. package/dist/models/mcpRequestLog.js +1 -1
  22. package/dist/models/mcpServiceToken.js +36 -4
  23. package/dist/openApiBuilder.d.ts +4 -0
  24. package/dist/openApiBuilder.js +2 -0
  25. package/dist/rbac/realtimeAccess.d.ts +5 -4
  26. package/dist/rbac/realtimeAccess.js +17 -64
  27. package/dist/realtime/changeStreamWatcher.d.ts +8 -63
  28. package/dist/realtime/changeStreamWatcher.js +32 -391
  29. package/dist/realtime/realtimeApp.d.ts +14 -27
  30. package/dist/realtime/realtimeApp.js +14 -220
  31. package/dist/realtime/types.d.ts +0 -64
  32. package/dist/sync/executors.js +14 -2
  33. package/dist/sync/socketHandlers.d.ts +1 -1
  34. package/dist/sync/socketHandlers.js +1 -1
  35. package/dist/terrenoApp.d.ts +7 -5
  36. package/dist/terrenoApp.js +18 -14
  37. package/dist/tests/openApiResponseSchema.d.ts +39 -0
  38. package/dist/tests/openApiResponseSchema.js +56 -0
  39. package/dist/tests.d.ts +1 -0
  40. package/dist/tests.js +4 -1
  41. package/dist/types/mcpAdmin.d.ts +1 -1
  42. package/dist/types/mcpServiceToken.d.ts +7 -4
  43. package/dist/versionCheckPlugin.d.ts +1 -1
  44. package/dist/versionCheckPlugin.js +25 -2
  45. package/package.json +10 -6
  46. package/src/__snapshots__/openApi.test.ts.snap +4986 -2478
  47. package/src/__snapshots__/openApiBuilder.test.ts.snap +836 -0
  48. package/src/__tests__/openApiResponseSchema.test.ts +148 -0
  49. package/src/__tests__/versionCheckPlugin.test.ts +72 -0
  50. package/src/api.test.ts +9 -7
  51. package/src/api.ts +0 -24
  52. package/src/auth.ts +116 -5
  53. package/src/authOpenApi.test.ts +316 -0
  54. package/src/authRecovery.ts +47 -19
  55. package/src/betterAuthOAuthHandoff.test.ts +13 -5
  56. package/src/collectionRegistry.ts +3 -5
  57. package/src/consentApp.test.ts +98 -0
  58. package/src/consentApp.ts +67 -2
  59. package/src/index.ts +6 -28
  60. package/src/mcp/actionTools.test.ts +2 -2
  61. package/src/mcp/adminTracking.ts +1 -1
  62. package/src/mcp/auth.test.ts +7 -3
  63. package/src/mcp/oauth.test.ts +12 -12
  64. package/src/mcp/serviceTokens.sync.test.ts +230 -0
  65. package/src/mcp/serviceTokens.test.ts +112 -61
  66. package/src/mcp/serviceTokens.ts +193 -212
  67. package/src/migrations/builtin/mcpServiceTokenStringIds.test.ts +194 -0
  68. package/src/migrations/builtin/mcpServiceTokenStringIds.ts +121 -0
  69. package/src/models/mcpRequestLog.ts +1 -1
  70. package/src/models/mcpServiceToken.test.ts +52 -5
  71. package/src/models/mcpServiceToken.ts +51 -14
  72. package/src/openApiBuilder.test.ts +34 -1
  73. package/src/openApiBuilder.ts +5 -0
  74. package/src/rateLimit/rateLimit.test.ts +25 -10
  75. package/src/rbac/realtimeAccess.test.ts +20 -172
  76. package/src/rbac/realtimeAccess.ts +17 -82
  77. package/src/realtime/changeStreamWatcher.ts +43 -506
  78. package/src/realtime/realtime.test.ts +205 -2545
  79. package/src/realtime/realtimeApp.ts +16 -295
  80. package/src/realtime/types.ts +0 -72
  81. package/src/sync/executors.test.ts +28 -0
  82. package/src/sync/executors.ts +23 -2
  83. package/src/sync/socketHandlers.ts +1 -1
  84. package/src/sync/syncSocket.test.ts +77 -113
  85. package/src/terrenoApp.mcpServiceTokens.test.ts +14 -6
  86. package/src/terrenoApp.ts +24 -18
  87. package/src/tests/openApiResponseSchema.ts +104 -0
  88. package/src/tests.ts +7 -0
  89. package/src/types/mcpAdmin.ts +1 -1
  90. package/src/types/mcpServiceToken.ts +7 -4
  91. package/src/versionCheckPlugin.ts +41 -2
  92. package/dist/realtime/deprecation.d.ts +0 -13
  93. package/dist/realtime/deprecation.js +0 -31
  94. package/dist/realtime/queryStore.d.ts +0 -37
  95. package/dist/realtime/queryStore.js +0 -103
  96. package/dist/realtime/registry.d.ts +0 -15
  97. package/dist/realtime/registry.js +0 -52
  98. package/src/realtime/deprecation.test.ts +0 -60
  99. package/src/realtime/deprecation.ts +0 -33
  100. package/src/realtime/queryStore.ts +0 -122
  101. package/src/realtime/registry.ts +0 -84
@@ -1,6 +1,5 @@
1
1
  import * as Sentry from "@sentry/bun";
2
2
  import type express from "express";
3
- import {DateTime} from "luxon";
4
3
  import type {ChangeStream, ChangeStreamDocument, ChangeStreamOptions} from "mongodb";
5
4
  import mongoose from "mongoose";
6
5
  import type {Server, Socket} from "socket.io";
@@ -9,7 +8,7 @@ import type {User} from "../auth";
9
8
  import {APIError} from "../errors";
10
9
  import {logger} from "../logger";
11
10
  import type {PermissionMethod} from "../permissions";
12
- import {canReadDocumentRealtime, maskRealtimeDocument} from "../rbac/realtimeAccess";
11
+ import {canReadDocumentRealtime} from "../rbac/realtimeAccess";
13
12
  import {
14
13
  authorizeAdminBroadcastDocument,
15
14
  isAdminBroadcastSocketRoom,
@@ -20,11 +19,8 @@ import {serializeSyncPayload} from "../sync/serialize";
20
19
  import {syncRoomForStream} from "../sync/socketHandlers";
21
20
  import {adminBroadcastStream, resolveStreamForDoc} from "../sync/streams";
22
21
  import type {SyncDelta, SyncMutationOperation, SyncResyncHint} from "../sync/types";
23
- import {matchesQuery} from "./queryMatcher";
24
- import {getQuerySubscriptionsForCollection} from "./queryStore";
25
- import {findRegistryEntryByCollection, type RealtimeRegistryEntry} from "./registry";
26
22
  import {awaitSocketFullUser, type SocketWithDecodedToken} from "./socketUser";
27
- import type {ChangeStreamConfig, RealtimeEvent} from "./types";
23
+ import type {ChangeStreamConfig} from "./types";
28
24
 
29
25
  /**
30
26
  * The subset of ChangeStreamDocument variants this watcher actually processes.
@@ -134,20 +130,14 @@ export const DEFAULT_IGNORED_COLLECTIONS = [
134
130
  /**
135
131
  * Map MongoDB change stream operation types to our method names.
136
132
  *
137
- * Soft deletes (an `update` that sets `deleted: true`) are reclassified as
138
- * `"delete"` only when the model has `"delete"` enabled in its realtime
139
- * methods. Otherwise they fall back to `"update"` so models that subscribe
140
- * to updates (but not deletes) still see the change — without this fallback,
141
- * a model configured with `methods: ["create", "update"]` would silently
142
- * drop soft-delete events.
133
+ * Soft deletes (an `update` that sets `deleted: true`) are reclassified as `"delete"`.
143
134
  *
144
135
  * Exported for testing.
145
136
  */
146
137
  /** @internal */
147
138
  export const mapOperationType = (
148
139
  operationType: string,
149
- change: ChangeStreamDocument,
150
- enabledMethods: ReadonlyArray<"create" | "update" | "delete"> = ["create", "update", "delete"]
140
+ change: ChangeStreamDocument
151
141
  ): "create" | "update" | "delete" | null => {
152
142
  if (operationType === "insert") {
153
143
  return "create";
@@ -159,7 +149,7 @@ export const mapOperationType = (
159
149
  const updateChange = change as Extract<ChangeStreamDocument, {operationType: "update"}>;
160
150
  const isSoftDelete =
161
151
  operationType === "update" && updateChange.updateDescription?.updatedFields?.deleted === true;
162
- if (isSoftDelete && enabledMethods.includes("delete")) {
152
+ if (isSoftDelete) {
163
153
  return "delete";
164
154
  }
165
155
  return "update";
@@ -195,8 +185,8 @@ const getSocketsInRoom = (io: Server, room: string): RealtimeSocketWithAuth[] =>
195
185
  };
196
186
 
197
187
  /**
198
- * The minimal registry-entry shape the authorized-room emitters need. Both
199
- * `RealtimeRegistryEntry` and `SyncRegistryEntry` satisfy it structurally.
188
+ * The minimal registry-entry shape the authorized-room emitter needs.
189
+ * `SyncRegistryEntry` satisfies it structurally.
200
190
  */
201
191
  export interface AuthorizedEmitEntry {
202
192
  collectionTag?: string;
@@ -208,50 +198,34 @@ export interface AuthorizedEmitEntry {
208
198
  const emitCollectionTag = (entry: AuthorizedEmitEntry): string | undefined =>
209
199
  entry.collectionTag ?? (entry.routePath ? getCollectionTag(entry.routePath) : undefined);
210
200
 
211
- const canReadDocument = async (
212
- entry: AuthorizedEmitEntry,
213
- user?: User,
214
- doc?: Record<string, unknown>
215
- ): Promise<boolean> => canReadDocumentRealtime(entry, user, doc);
216
-
217
201
  /**
218
- * Determine which Socket.io rooms to emit to based on the room strategy.
219
- * Exported for testing.
202
+ * The change-stream post-image as the model document REST permission checks receive, so
203
+ * virtuals resolve: `Permissions.IsOwner` reads `ownerId`, which models owned through another
204
+ * field (GptHistory's `userId`) only have as a virtual. Falls back to the raw image when the
205
+ * model is not registered or the image does not hydrate.
220
206
  */
221
- /** @internal */
222
- export const resolveRooms = (
223
- entry: RealtimeRegistryEntry,
224
- doc: Record<string, unknown>,
225
- method: string
226
- ): string[] => {
227
- const {roomStrategy} = entry.config;
228
- // Use the collection tag (e.g. "todos") for model rooms, matching what the frontend subscribes to
229
- const collectionTag = getCollectionTag(entry.routePath);
230
-
231
- if (typeof roomStrategy === "function") {
232
- // Custom room resolver — pass a minimal pseudo-request. The strategy only inspects
233
- // doc/method; we never read fields off req here, so an empty cast is safe.
234
- return roomStrategy(doc, method, {} as unknown as express.Request);
207
+ const toPermissionDocument = (
208
+ modelName: string,
209
+ doc?: Record<string, unknown>
210
+ ): Record<string, unknown> | undefined => {
211
+ if (!doc || Object.keys(doc).length === 0 || !mongoose.modelNames().includes(modelName)) {
212
+ return doc;
235
213
  }
236
-
237
- switch (roomStrategy) {
238
- case "owner": {
239
- const ownerId = doc?.ownerId != null ? String(doc.ownerId) : undefined;
240
- if (ownerId) {
241
- return [`user:${ownerId}`];
242
- }
243
- // If no ownerId, fall back to model room
244
- return [`model:${collectionTag}`];
245
- }
246
- case "model":
247
- return [`model:${collectionTag}`];
248
- case "broadcast":
249
- return ["authenticated"];
250
- default:
251
- return [`model:${collectionTag}`];
214
+ try {
215
+ return mongoose.model(modelName).hydrate(doc) as unknown as Record<string, unknown>;
216
+ } catch (error) {
217
+ logger.warn(`[realtime] Could not hydrate ${modelName} for a read check: ${error}`);
218
+ return doc;
252
219
  }
253
220
  };
254
221
 
222
+ const canReadDocument = async (
223
+ entry: AuthorizedEmitEntry,
224
+ user?: User,
225
+ doc?: Record<string, unknown>
226
+ ): Promise<boolean> =>
227
+ canReadDocumentRealtime(entry, user, toPermissionDocument(entry.modelName, doc));
228
+
255
229
  /**
256
230
  * Ensure serialized documents include `id` to match REST API responses.
257
231
  * Change stream fullDocument payloads are raw BSON objects with `_id` only.
@@ -268,78 +242,7 @@ export const ensureApiId = (data: unknown): unknown => {
268
242
  return data;
269
243
  };
270
244
 
271
- /**
272
- * Serialize a document for emission.
273
- *
274
- * Precedence:
275
- * 1. `realtimeResponseHandler` if provided (full control over what's emitted).
276
- * 2. modelRouter `responseHandler` if provided — invoked with a synthetic request
277
- * so the same stripping logic used for REST responses (e.g. removing `hash`/`salt`)
278
- * applies to realtime events. This prevents accidental leaks when an app only
279
- * configures sanitization in the REST `responseHandler`.
280
- * 3. `toJSON()` fallback.
281
- *
282
- * If a user-supplied handler throws, we re-throw so the caller's outer try/catch
283
- * records the failure and the event is dropped. Falling back to `toJSON()` here
284
- * would risk leaking unsanitized fields (e.g. `hash`/`salt`) that the handler
285
- * was supposed to strip.
286
- */
287
- /** @internal */
288
- export const serializeDoc = async (
289
- entry: RealtimeRegistryEntry,
290
- doc: Record<string, unknown>,
291
- method: "create" | "update" | "delete",
292
- user?: User
293
- ): Promise<unknown> => {
294
- if (entry.config.realtimeResponseHandler) {
295
- try {
296
- return ensureApiId(await entry.config.realtimeResponseHandler(doc, method));
297
- } catch (error) {
298
- logger.error(
299
- `[realtime] realtimeResponseHandler threw for ${entry.modelName}/${method}: ${error}. ` +
300
- "Dropping event to avoid leaking unsanitized data."
301
- );
302
- throw error;
303
- }
304
- }
305
-
306
- const responseHandler = entry.options?.responseHandler;
307
- if (responseHandler) {
308
- try {
309
- // The REST responseHandler signature expects a "list" | "create" | "read" | "update" method.
310
- // Map "delete" → "read" so handlers that branch on method receive a sane value.
311
- const restMethod = method === "delete" ? "read" : method;
312
- // Synthesize the minimal request shape responseHandlers commonly inspect.
313
- const syntheticReq = {params: {}, query: {}, user} as unknown as express.Request;
314
- const serialized = await responseHandler(
315
- doc as unknown as mongoose.Document<unknown, unknown, unknown>,
316
- restMethod,
317
- syntheticReq,
318
- entry.options
319
- );
320
- const masked = await maskRealtimeDocument(entry, user, serialized, restMethod);
321
- return ensureApiId(masked);
322
- } catch (error) {
323
- logger.error(
324
- `[realtime] modelRouter responseHandler threw during realtime serialization for ` +
325
- `${entry.modelName}/${method}: ${error}. Dropping event to avoid leaking unsanitized data.`
326
- );
327
- throw error;
328
- }
329
- }
330
-
331
- const fallback =
332
- typeof doc.toJSON === "function" ? (doc as {toJSON: () => unknown}).toJSON() : doc;
333
- const maskedFallback = await maskRealtimeDocument(
334
- entry,
335
- user,
336
- fallback,
337
- method === "delete" ? "read" : method
338
- );
339
- return ensureApiId(maskedFallback);
340
- };
341
-
342
- /** Returned by a `buildPayload` callback to send nothing to that socket. */
245
+ /** Returned by a buildPayload callback to send nothing to that socket. */
343
246
  const SKIP_EMISSION = Symbol("skipEmission");
344
247
 
345
248
  /**
@@ -347,8 +250,7 @@ const SKIP_EMISSION = Symbol("skipEmission");
347
250
  * read-permission check against `fullDocument`, builds the payload per socket (so
348
251
  * responseHandlers can tailor output to the receiving user), and emits `eventName`.
349
252
  *
350
- * `emitToAuthorizedRoom` (legacy "sync" events) and the sync layer's `sync:delta`
351
- * emission both delegate here.
253
+ * The sync layer's `sync:delta` emission delegates here.
352
254
  */
353
255
  export const emitPayloadToAuthorizedRoom = async ({
354
256
  io,
@@ -417,357 +319,11 @@ export const emitPayloadToAuthorizedRoom = async ({
417
319
  }
418
320
  };
419
321
 
420
- /** @internal */
421
- export const emitToAuthorizedRoom = async (
422
- io: Server,
423
- room: string,
424
- event: RealtimeEvent,
425
- entry: RealtimeRegistryEntry,
426
- fullDocument: Record<string, unknown> | undefined,
427
- logDebug: (msg: string) => void
428
- ): Promise<void> =>
429
- emitPayloadToAuthorizedRoom({
430
- buildPayload: async (user) => {
431
- if (!fullDocument) {
432
- return event;
433
- }
434
- const data = await serializeDoc(entry, fullDocument, event.method, user);
435
- return {...event, data};
436
- },
437
- entry,
438
- eventName: "sync",
439
- fullDocument,
440
- io,
441
- logDebug,
442
- room,
443
- });
444
-
445
- /**
446
- * Query-room fan-out for routers with RBAC field views. Each recipient's match is evaluated
447
- * against the document as masked for that recipient, so a field hidden from them cannot
448
- * decide whether they receive a create, update, or delete.
449
- */
450
- const emitMaskedQueryRoomEvent = async ({
451
- io,
452
- queryRoom,
453
- event,
454
- entry,
455
- fullDocument,
456
- query,
457
- logDebug,
458
- }: {
459
- io: Server;
460
- queryRoom: string;
461
- event: RealtimeEvent;
462
- entry: RealtimeRegistryEntry;
463
- fullDocument: Record<string, unknown>;
464
- query: Record<string, unknown>;
465
- logDebug: (msg: string) => void;
466
- }): Promise<void> =>
467
- emitPayloadToAuthorizedRoom({
468
- buildPayload: async (user) => {
469
- const masked = await maskRealtimeDocument(entry, user, fullDocument, "read");
470
- const matches =
471
- typeof masked === "object" &&
472
- masked !== null &&
473
- !Array.isArray(masked) &&
474
- matchesQuery(masked as Record<string, unknown>, query);
475
- let method: RealtimeEvent["method"] | undefined;
476
- if (event.method === "update") {
477
- method = matches ? "update" : "delete";
478
- } else if (matches) {
479
- method = event.method;
480
- }
481
- if (!method) {
482
- return SKIP_EMISSION;
483
- }
484
- const data = await serializeDoc(entry, fullDocument, method, user);
485
- return {...event, data, method};
486
- },
487
- entry,
488
- eventName: "sync",
489
- fullDocument,
490
- io,
491
- logDebug,
492
- room: queryRoom,
493
- });
494
-
495
- /** Fan one change out to one query room. */
496
- const emitToQueryRoom = async ({
497
- io,
498
- queryRoom,
499
- query,
500
- event,
501
- fullDocument,
502
- entry,
503
- hasFieldViews,
504
- isOwnerStrategy,
505
- logDebug,
506
- }: {
507
- io: Server;
508
- queryRoom: string;
509
- query: Record<string, unknown>;
510
- event: RealtimeEvent;
511
- fullDocument: Record<string, unknown> | undefined;
512
- entry?: RealtimeRegistryEntry;
513
- hasFieldViews: boolean;
514
- isOwnerStrategy: boolean;
515
- logDebug: (msg: string) => void;
516
- }): Promise<void> => {
517
- if (event.method === "delete") {
518
- if (!fullDocument) {
519
- // Hard delete with no document context. For owner-strategy collections we can't
520
- // tell which query rooms belong to the owner without leaking activity to others,
521
- // so skip query fanout entirely — subscribers will reconcile on next fetch.
522
- if (isOwnerStrategy) {
523
- logDebug(
524
- `[realtime] Skipping hard delete fanout to ${queryRoom} (owner strategy, no fullDocument)`
525
- );
526
- return;
527
- }
528
- if (entry) {
529
- await emitToAuthorizedRoom(io, queryRoom, event, entry, fullDocument, logDebug);
530
- } else {
531
- io.to(queryRoom).emit("sync", event);
532
- }
533
- logDebug(`[realtime] Emitted hard delete to ${queryRoom}`);
534
- return;
535
- }
536
-
537
- if (entry && hasFieldViews) {
538
- await emitMaskedQueryRoomEvent({
539
- entry,
540
- event,
541
- fullDocument,
542
- io,
543
- logDebug,
544
- query,
545
- queryRoom,
546
- });
547
- return;
548
- }
549
-
550
- // Soft delete: only forward to query rooms whose filter the document satisfies.
551
- if (matchesQuery(fullDocument, query)) {
552
- if (entry) {
553
- await emitToAuthorizedRoom(io, queryRoom, event, entry, fullDocument, logDebug);
554
- } else {
555
- io.to(queryRoom).emit("sync", event);
556
- }
557
- logDebug(`[realtime] Emitted soft delete to ${queryRoom} (query matched)`);
558
- }
559
- return;
560
- }
561
-
562
- if (!fullDocument) {
563
- return;
564
- }
565
-
566
- if (entry && hasFieldViews) {
567
- await emitMaskedQueryRoomEvent({entry, event, fullDocument, io, logDebug, query, queryRoom});
568
- return;
569
- }
570
-
571
- const docMatches = matchesQuery(fullDocument, query);
572
-
573
- if (event.method === "create" && docMatches) {
574
- // New document matches the query — send create event
575
- if (entry) {
576
- await emitToAuthorizedRoom(io, queryRoom, event, entry, fullDocument, logDebug);
577
- } else {
578
- io.to(queryRoom).emit("sync", event);
579
- }
580
- logDebug(`[realtime] Emitted create to ${queryRoom} (query matched)`);
581
- } else if (event.method === "update") {
582
- if (docMatches) {
583
- // Document still matches (or newly matches) — send update event
584
- if (entry) {
585
- await emitToAuthorizedRoom(io, queryRoom, event, entry, fullDocument, logDebug);
586
- } else {
587
- io.to(queryRoom).emit("sync", event);
588
- }
589
- logDebug(`[realtime] Emitted update to ${queryRoom} (query matched)`);
590
- } else {
591
- // Document no longer matches the query — send delete event so client removes it
592
- const removeEvent: RealtimeEvent = {
593
- ...event,
594
- method: "delete",
595
- };
596
- if (entry) {
597
- await emitToAuthorizedRoom(io, queryRoom, removeEvent, entry, fullDocument, logDebug);
598
- } else {
599
- io.to(queryRoom).emit("sync", removeEvent);
600
- }
601
- logDebug(`[realtime] Emitted delete to ${queryRoom} (query no longer matched)`);
602
- }
603
- }
604
- };
605
-
606
- /**
607
- * Emit a sync event to document-specific and query rooms.
608
- *
609
- * Document rooms: `document:{collection}:{docId}` — clients subscribed to a single document.
610
- * Query rooms: `query:{queryId}` — clients subscribed to a query filter. The change stream
611
- * watcher evaluates whether the document matches each active query for the collection.
612
- *
613
- * For deletes, we are careful not to leak cross-user activity:
614
- * - Soft deletes (fullDocument present) are matched against each query like updates so
615
- * query subscribers only see deletes for docs that matched their filter.
616
- * - Hard deletes (fullDocument absent) on owner-strategy collections are NOT forwarded
617
- * to query rooms — subscribers will reconcile on their next fetch. Other strategies
618
- * forward the delete because the model/broadcast rooms are not user-scoped.
619
- *
620
- * Exported for testing.
621
- */
622
- /** @internal */
623
- export const emitToDocumentAndQueryRooms = async (
624
- io: Server,
625
- collection: string,
626
- event: RealtimeEvent,
627
- fullDocument: Record<string, unknown> | undefined,
628
- logDebug: (msg: string) => void,
629
- entry?: RealtimeRegistryEntry
630
- ): Promise<void> => {
631
- // Emit to document-specific room
632
- const docRoom = `document:${collection}:${event.id}`;
633
- if (entry) {
634
- await emitToAuthorizedRoom(io, docRoom, event, entry, fullDocument, logDebug);
635
- } else {
636
- io.to(docRoom).emit("sync", event);
637
- }
638
- logDebug(`[realtime] Emitted ${event.method} to ${docRoom}`);
639
-
640
- const isOwnerStrategy = entry?.config.roomStrategy === "owner";
641
- const hasFieldViews = Boolean(entry?.options.access && entry?.options.accessControl);
642
-
643
- // Evaluate query subscriptions
644
- const querySubscriptions = getQuerySubscriptionsForCollection(collection);
645
- for (const subscription of querySubscriptions) {
646
- try {
647
- await emitToQueryRoom({
648
- entry,
649
- event,
650
- fullDocument,
651
- hasFieldViews,
652
- io,
653
- isOwnerStrategy,
654
- logDebug,
655
- query: subscription.query,
656
- queryRoom: `query:${subscription.queryId}`,
657
- });
658
- } catch (error) {
659
- // One subscription's failure must not stop the others or the change's sync:delta.
660
- logger.warn(
661
- `[realtime] Query subscription ${subscription.queryId} failed to evaluate; skipping it: ${error}`
662
- );
663
- }
664
- }
665
- };
666
-
667
- /**
668
- * Emit legacy realtime "sync" events for a change on a realtime-registered collection.
669
- * Extracted verbatim from the change handler so sync-delta emission (which is keyed off
670
- * the independent sync registry) runs even when the realtime path skips the change.
671
- */
672
- const processRealtimeChange = async ({
673
- io,
674
- entry,
675
- change,
676
- docId,
677
- logDebug,
678
- logInfo,
679
- }: {
680
- io: Server;
681
- entry: RealtimeRegistryEntry;
682
- change: WatchedChange;
683
- docId: string;
684
- logDebug: (msg: string) => void;
685
- logInfo: (msg: string) => void;
686
- }): Promise<void> => {
687
- // Map to our method type. Pass enabledMethods so soft deletes only
688
- // remap to "delete" when the model actually subscribes to deletes —
689
- // otherwise the change is kept as "update" so update subscribers
690
- // still receive it.
691
- const method = mapOperationType(change.operationType, change, entry.config.methods);
692
- if (!method) {
693
- return;
694
- }
695
-
696
- // Check if this method is enabled for this model
697
- if (!entry.config.methods.includes(method)) {
698
- logDebug(`[realtime] Method ${method} not enabled for ${entry.modelName}`);
699
- return;
700
- }
701
-
702
- // fullDocument is present on insert/update/replace; absent on delete.
703
- const fullDocument = change.operationType === "delete" ? undefined : change.fullDocument;
704
-
705
- // For hard deletes, we don't have the full document
706
- const isHardDelete = method === "delete" && !fullDocument;
707
-
708
- // Determine target rooms
709
- let rooms: string[];
710
- if (isHardDelete) {
711
- // Hard delete: no fullDocument, so we can't resolve owner/custom rooms.
712
- // For owner strategy we cannot safely fan out to a model room without
713
- // leaking deletes across users — admins still receive the event via the
714
- // admin room and any document-specific subscribers via document rooms.
715
- if (entry.config.roomStrategy === "owner") {
716
- rooms = ["admin"];
717
- } else if (entry.config.roomStrategy === "broadcast") {
718
- rooms = ["authenticated"];
719
- } else {
720
- const collectionTag = getCollectionTag(entry.routePath);
721
- rooms = [`model:${collectionTag}`];
722
- }
723
- } else {
724
- rooms = resolveRooms(entry, fullDocument ?? {}, method);
725
- }
726
-
727
- const collection = getCollectionTag(entry.routePath);
728
-
729
- const event: RealtimeEvent = {
730
- collection,
731
- id: docId,
732
- method,
733
- model: entry.modelName,
734
- timestamp: DateTime.now().toMillis(),
735
- ...(change.operationType === "update" && change.updateDescription?.updatedFields
736
- ? {updatedFields: Object.keys(change.updateDescription.updatedFields)}
737
- : {}),
738
- };
739
-
740
- // Emit to strategy-based rooms (model/owner/broadcast)
741
- for (const room of rooms) {
742
- await emitToAuthorizedRoom(io, room, event, entry, fullDocument, logDebug);
743
- }
744
-
745
- // Emit to document-specific and query rooms
746
- await emitToDocumentAndQueryRooms(io, collection, event, fullDocument, logDebug, entry);
747
-
748
- logDebug(
749
- `[realtime] Emitted ${method} for ${entry.modelName}/${docId} to rooms: ${rooms.join(", ")}`
750
- );
751
- // Log only metadata — never the document payload, which may contain sensitive fields.
752
- const metadata: Record<string, unknown> = {
753
- collection: event.collection,
754
- id: event.id,
755
- method: event.method,
756
- model: event.model,
757
- timestamp: event.timestamp,
758
- };
759
- if (event.updatedFields) {
760
- metadata.updatedFields = event.updatedFields;
761
- }
762
- logInfo(`[realtime] sync event: ${JSON.stringify(metadata)}`);
763
- };
764
-
765
322
  /**
766
323
  * Emit `sync:delta` events for a change on a sync-registered collection.
767
324
  *
768
325
  * Deltas fan out to the dedicated `sync:{stream}` rooms joined via `sync:subscribe`
769
- * (independent of the legacy realtime rooms), with the same per-socket read-permission
770
- * checks as legacy events. `seq` and `stream` come from the post-image: the `syncPlugin`
326
+ * with per-socket read-permission checks. `seq` and `stream` come from the post-image: the `syncPlugin`
771
327
  * stamps `_syncSeq` on every synced write and the watcher runs `updateLookup`.
772
328
  *
773
329
  * Soft deletes (an update setting `deleted: true`, reclassified by `mapOperationType`)
@@ -786,9 +342,6 @@ const processRealtimeChange = async ({
786
342
  * emit time, C1); the client advances its cursor to `min(delta.seq, delta.frontierSeq)`
787
343
  * so a delta observed out of commit order never advances a cursor past an uncommitted hole.
788
344
  *
789
- * A model with both `realtime` and `sync` configs emits both the legacy "sync" event and
790
- * "sync:delta" — distinct event names, no interference (documented as transitional).
791
- *
792
345
  * Exported for testing.
793
346
  */
794
347
  export const emitSyncDeltaForChange = async ({
@@ -914,7 +467,7 @@ export const emitSyncDeltaForChange = async ({
914
467
  };
915
468
 
916
469
  /**
917
- * Start watching MongoDB change streams and emitting real-time events.
470
+ * Start watching MongoDB change streams and emitting `sync:delta` events.
918
471
  *
919
472
  * Task 9.16: the stream is supervised — an `error`/`close`/`end` schedules a re-open with
920
473
  * exponential backoff, resuming from the last seen token. Call
@@ -1091,40 +644,24 @@ const openChangeStream = ({
1091
644
  return;
1092
645
  }
1093
646
 
1094
- // Realtime and sync registries are independent: a model may be in either or both.
1095
- // A model with both configs emits both the legacy "sync" event and "sync:delta".
1096
- const entry = findRegistryEntryByCollection(collectionName);
1097
647
  const syncEntry = findSyncEntryByCollectionName(collectionName);
1098
-
1099
- if (!entry && !syncEntry) {
1100
- // Not a registered realtime or sync model — skip
1101
- logDebug(`[realtime] No registry entry for collection: ${collectionName}`);
648
+ if (!syncEntry) {
649
+ // Not a sync-registered model — skip
650
+ logDebug(`[realtime] No sync registry entry for collection: ${collectionName}`);
1102
651
  return;
1103
652
  }
1104
653
 
1105
- if (entry) {
1106
- // A legacy realtime failure must not skip the independent sync:delta emission.
654
+ // C8: serialize per entity so same-doc deltas emit in change-stream order;
655
+ // different docs still dispatch concurrently. See serializePerEntity + the
656
+ // per-entity LWW-by-seq contract documented in sync/types.ts (SyncDelta).
657
+ serializePerEntity(`${collectionName}:${docId}`, async () => {
1107
658
  try {
1108
- await processRealtimeChange({change, docId, entry, io, logDebug, logInfo});
659
+ await emitSyncDeltaForChange({change, docId, entry: syncEntry, io, logDebug});
1109
660
  } catch (error) {
1110
- logger.error(`[realtime] Error processing realtime change: ${error}`);
661
+ logger.error(`[sync] Error emitting sync delta: ${error}`);
1111
662
  Sentry.captureException(error);
1112
663
  }
1113
- }
1114
-
1115
- if (syncEntry) {
1116
- // C8: serialize per entity so same-doc deltas emit in change-stream order;
1117
- // different docs still dispatch concurrently. See serializePerEntity + the
1118
- // per-entity LWW-by-seq contract documented in sync/types.ts (SyncDelta).
1119
- serializePerEntity(`${collectionName}:${docId}`, async () => {
1120
- try {
1121
- await emitSyncDeltaForChange({change, docId, entry: syncEntry, io, logDebug});
1122
- } catch (error) {
1123
- logger.error(`[sync] Error emitting sync delta: ${error}`);
1124
- Sentry.captureException(error);
1125
- }
1126
- });
1127
- }
664
+ });
1128
665
  } catch (error) {
1129
666
  logger.error(`[realtime] Error processing change event: ${error}`);
1130
667
  Sentry.captureException(error);