@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
@@ -36,9 +36,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
36
36
  return (mod && mod.__esModule) ? mod : { "default": mod };
37
37
  };
38
38
  Object.defineProperty(exports, "__esModule", { value: true });
39
- exports.stopChangeStreamWatcher = exports.startChangeStreamWatcher = exports.emitSyncDeltaForChange = exports.emitToDocumentAndQueryRooms = exports.emitToAuthorizedRoom = exports.emitPayloadToAuthorizedRoom = exports.serializeDoc = exports.ensureApiId = exports.resolveRooms = exports.mapOperationType = exports.DEFAULT_IGNORED_COLLECTIONS = exports.SYNC_RESYNC_EVENT = void 0;
39
+ exports.stopChangeStreamWatcher = exports.startChangeStreamWatcher = exports.emitSyncDeltaForChange = exports.emitPayloadToAuthorizedRoom = exports.ensureApiId = exports.mapOperationType = exports.DEFAULT_IGNORED_COLLECTIONS = exports.SYNC_RESYNC_EVENT = void 0;
40
40
  const Sentry = __importStar(require("@sentry/bun"));
41
- const luxon_1 = require("luxon");
42
41
  const mongoose_1 = __importDefault(require("mongoose"));
43
42
  const errors_1 = require("../errors");
44
43
  const logger_1 = require("../logger");
@@ -49,9 +48,6 @@ const registry_1 = require("../sync/registry");
49
48
  const serialize_1 = require("../sync/serialize");
50
49
  const socketHandlers_1 = require("../sync/socketHandlers");
51
50
  const streams_1 = require("../sync/streams");
52
- const queryMatcher_1 = require("./queryMatcher");
53
- const queryStore_1 = require("./queryStore");
54
- const registry_2 = require("./registry");
55
51
  const socketUser_1 = require("./socketUser");
56
52
  let changeWatcher = null;
57
53
  /**
@@ -131,17 +127,12 @@ exports.DEFAULT_IGNORED_COLLECTIONS = [
131
127
  /**
132
128
  * Map MongoDB change stream operation types to our method names.
133
129
  *
134
- * Soft deletes (an `update` that sets `deleted: true`) are reclassified as
135
- * `"delete"` only when the model has `"delete"` enabled in its realtime
136
- * methods. Otherwise they fall back to `"update"` so models that subscribe
137
- * to updates (but not deletes) still see the change — without this fallback,
138
- * a model configured with `methods: ["create", "update"]` would silently
139
- * drop soft-delete events.
130
+ * Soft deletes (an `update` that sets `deleted: true`) are reclassified as `"delete"`.
140
131
  *
141
132
  * Exported for testing.
142
133
  */
143
134
  /** @internal */
144
- const mapOperationType = (operationType, change, enabledMethods = ["create", "update", "delete"]) => {
135
+ const mapOperationType = (operationType, change) => {
145
136
  if (operationType === "insert") {
146
137
  return "create";
147
138
  }
@@ -151,7 +142,7 @@ const mapOperationType = (operationType, change, enabledMethods = ["create", "up
151
142
  // callers/tests pass change objects without setting `operationType` on the change.
152
143
  const updateChange = change;
153
144
  const isSoftDelete = operationType === "update" && updateChange.updateDescription?.updatedFields?.deleted === true;
154
- if (isSoftDelete && enabledMethods.includes("delete")) {
145
+ if (isSoftDelete) {
155
146
  return "delete";
156
147
  }
157
148
  return "update";
@@ -182,39 +173,25 @@ const getSocketsInRoom = (io, room) => {
182
173
  return sockets;
183
174
  };
184
175
  const emitCollectionTag = (entry) => entry.collectionTag ?? (entry.routePath ? getCollectionTag(entry.routePath) : undefined);
185
- const canReadDocument = async (entry, user, doc) => (0, realtimeAccess_1.canReadDocumentRealtime)(entry, user, doc);
186
176
  /**
187
- * Determine which Socket.io rooms to emit to based on the room strategy.
188
- * Exported for testing.
177
+ * The change-stream post-image as the model document REST permission checks receive, so
178
+ * virtuals resolve: `Permissions.IsOwner` reads `ownerId`, which models owned through another
179
+ * field (GptHistory's `userId`) only have as a virtual. Falls back to the raw image when the
180
+ * model is not registered or the image does not hydrate.
189
181
  */
190
- /** @internal */
191
- const resolveRooms = (entry, doc, method) => {
192
- const { roomStrategy } = entry.config;
193
- // Use the collection tag (e.g. "todos") for model rooms, matching what the frontend subscribes to
194
- const collectionTag = getCollectionTag(entry.routePath);
195
- if (typeof roomStrategy === "function") {
196
- // Custom room resolver — pass a minimal pseudo-request. The strategy only inspects
197
- // doc/method; we never read fields off req here, so an empty cast is safe.
198
- return roomStrategy(doc, method, {});
182
+ const toPermissionDocument = (modelName, doc) => {
183
+ if (!doc || Object.keys(doc).length === 0 || !mongoose_1.default.modelNames().includes(modelName)) {
184
+ return doc;
199
185
  }
200
- switch (roomStrategy) {
201
- case "owner": {
202
- const ownerId = doc?.ownerId != null ? String(doc.ownerId) : undefined;
203
- if (ownerId) {
204
- return [`user:${ownerId}`];
205
- }
206
- // If no ownerId, fall back to model room
207
- return [`model:${collectionTag}`];
208
- }
209
- case "model":
210
- return [`model:${collectionTag}`];
211
- case "broadcast":
212
- return ["authenticated"];
213
- default:
214
- return [`model:${collectionTag}`];
186
+ try {
187
+ return mongoose_1.default.model(modelName).hydrate(doc);
188
+ }
189
+ catch (error) {
190
+ logger_1.logger.warn(`[realtime] Could not hydrate ${modelName} for a read check: ${error}`);
191
+ return doc;
215
192
  }
216
193
  };
217
- exports.resolveRooms = resolveRooms;
194
+ const canReadDocument = async (entry, user, doc) => (0, realtimeAccess_1.canReadDocumentRealtime)(entry, user, toPermissionDocument(entry.modelName, doc));
218
195
  /**
219
196
  * Ensure serialized documents include `id` to match REST API responses.
220
197
  * Change stream fullDocument payloads are raw BSON objects with `_id` only.
@@ -231,66 +208,14 @@ const ensureApiId = (data) => {
231
208
  return data;
232
209
  };
233
210
  exports.ensureApiId = ensureApiId;
234
- /**
235
- * Serialize a document for emission.
236
- *
237
- * Precedence:
238
- * 1. `realtimeResponseHandler` if provided (full control over what's emitted).
239
- * 2. modelRouter `responseHandler` if provided — invoked with a synthetic request
240
- * so the same stripping logic used for REST responses (e.g. removing `hash`/`salt`)
241
- * applies to realtime events. This prevents accidental leaks when an app only
242
- * configures sanitization in the REST `responseHandler`.
243
- * 3. `toJSON()` fallback.
244
- *
245
- * If a user-supplied handler throws, we re-throw so the caller's outer try/catch
246
- * records the failure and the event is dropped. Falling back to `toJSON()` here
247
- * would risk leaking unsanitized fields (e.g. `hash`/`salt`) that the handler
248
- * was supposed to strip.
249
- */
250
- /** @internal */
251
- const serializeDoc = async (entry, doc, method, user) => {
252
- if (entry.config.realtimeResponseHandler) {
253
- try {
254
- return (0, exports.ensureApiId)(await entry.config.realtimeResponseHandler(doc, method));
255
- }
256
- catch (error) {
257
- logger_1.logger.error(`[realtime] realtimeResponseHandler threw for ${entry.modelName}/${method}: ${error}. ` +
258
- "Dropping event to avoid leaking unsanitized data.");
259
- throw error;
260
- }
261
- }
262
- const responseHandler = entry.options?.responseHandler;
263
- if (responseHandler) {
264
- try {
265
- // The REST responseHandler signature expects a "list" | "create" | "read" | "update" method.
266
- // Map "delete" → "read" so handlers that branch on method receive a sane value.
267
- const restMethod = method === "delete" ? "read" : method;
268
- // Synthesize the minimal request shape responseHandlers commonly inspect.
269
- const syntheticReq = { params: {}, query: {}, user };
270
- const serialized = await responseHandler(doc, restMethod, syntheticReq, entry.options);
271
- const masked = await (0, realtimeAccess_1.maskRealtimeDocument)(entry, user, serialized, restMethod);
272
- return (0, exports.ensureApiId)(masked);
273
- }
274
- catch (error) {
275
- logger_1.logger.error(`[realtime] modelRouter responseHandler threw during realtime serialization for ` +
276
- `${entry.modelName}/${method}: ${error}. Dropping event to avoid leaking unsanitized data.`);
277
- throw error;
278
- }
279
- }
280
- const fallback = typeof doc.toJSON === "function" ? doc.toJSON() : doc;
281
- const maskedFallback = await (0, realtimeAccess_1.maskRealtimeDocument)(entry, user, fallback, method === "delete" ? "read" : method);
282
- return (0, exports.ensureApiId)(maskedFallback);
283
- };
284
- exports.serializeDoc = serializeDoc;
285
- /** Returned by a `buildPayload` callback to send nothing to that socket. */
211
+ /** Returned by a buildPayload callback to send nothing to that socket. */
286
212
  const SKIP_EMISSION = Symbol("skipEmission");
287
213
  /**
288
214
  * Generalized authorized-room emitter: iterates the sockets in `room`, runs the per-socket
289
215
  * read-permission check against `fullDocument`, builds the payload per socket (so
290
216
  * responseHandlers can tailor output to the receiving user), and emits `eventName`.
291
217
  *
292
- * `emitToAuthorizedRoom` (legacy "sync" events) and the sync layer's `sync:delta`
293
- * emission both delegate here.
218
+ * The sync layer's `sync:delta` emission delegates here.
294
219
  */
295
220
  const emitPayloadToAuthorizedRoom = async ({ io, room, eventName, entry, fullDocument, buildPayload, logDebug, }) => {
296
221
  const sockets = getSocketsInRoom(io, room);
@@ -337,277 +262,11 @@ const emitPayloadToAuthorizedRoom = async ({ io, room, eventName, entry, fullDoc
337
262
  }
338
263
  };
339
264
  exports.emitPayloadToAuthorizedRoom = emitPayloadToAuthorizedRoom;
340
- /** @internal */
341
- const emitToAuthorizedRoom = async (io, room, event, entry, fullDocument, logDebug) => (0, exports.emitPayloadToAuthorizedRoom)({
342
- buildPayload: async (user) => {
343
- if (!fullDocument) {
344
- return event;
345
- }
346
- const data = await (0, exports.serializeDoc)(entry, fullDocument, event.method, user);
347
- return { ...event, data };
348
- },
349
- entry,
350
- eventName: "sync",
351
- fullDocument,
352
- io,
353
- logDebug,
354
- room,
355
- });
356
- exports.emitToAuthorizedRoom = emitToAuthorizedRoom;
357
- /**
358
- * Query-room fan-out for routers with RBAC field views. Each recipient's match is evaluated
359
- * against the document as masked for that recipient, so a field hidden from them cannot
360
- * decide whether they receive a create, update, or delete.
361
- */
362
- const emitMaskedQueryRoomEvent = async ({ io, queryRoom, event, entry, fullDocument, query, logDebug, }) => (0, exports.emitPayloadToAuthorizedRoom)({
363
- buildPayload: async (user) => {
364
- const masked = await (0, realtimeAccess_1.maskRealtimeDocument)(entry, user, fullDocument, "read");
365
- const matches = typeof masked === "object" &&
366
- masked !== null &&
367
- !Array.isArray(masked) &&
368
- (0, queryMatcher_1.matchesQuery)(masked, query);
369
- let method;
370
- if (event.method === "update") {
371
- method = matches ? "update" : "delete";
372
- }
373
- else if (matches) {
374
- method = event.method;
375
- }
376
- if (!method) {
377
- return SKIP_EMISSION;
378
- }
379
- const data = await (0, exports.serializeDoc)(entry, fullDocument, method, user);
380
- return { ...event, data, method };
381
- },
382
- entry,
383
- eventName: "sync",
384
- fullDocument,
385
- io,
386
- logDebug,
387
- room: queryRoom,
388
- });
389
- /** Fan one change out to one query room. */
390
- const emitToQueryRoom = async ({ io, queryRoom, query, event, fullDocument, entry, hasFieldViews, isOwnerStrategy, logDebug, }) => {
391
- if (event.method === "delete") {
392
- if (!fullDocument) {
393
- // Hard delete with no document context. For owner-strategy collections we can't
394
- // tell which query rooms belong to the owner without leaking activity to others,
395
- // so skip query fanout entirely — subscribers will reconcile on next fetch.
396
- if (isOwnerStrategy) {
397
- logDebug(`[realtime] Skipping hard delete fanout to ${queryRoom} (owner strategy, no fullDocument)`);
398
- return;
399
- }
400
- if (entry) {
401
- await (0, exports.emitToAuthorizedRoom)(io, queryRoom, event, entry, fullDocument, logDebug);
402
- }
403
- else {
404
- io.to(queryRoom).emit("sync", event);
405
- }
406
- logDebug(`[realtime] Emitted hard delete to ${queryRoom}`);
407
- return;
408
- }
409
- if (entry && hasFieldViews) {
410
- await emitMaskedQueryRoomEvent({
411
- entry,
412
- event,
413
- fullDocument,
414
- io,
415
- logDebug,
416
- query,
417
- queryRoom,
418
- });
419
- return;
420
- }
421
- // Soft delete: only forward to query rooms whose filter the document satisfies.
422
- if ((0, queryMatcher_1.matchesQuery)(fullDocument, query)) {
423
- if (entry) {
424
- await (0, exports.emitToAuthorizedRoom)(io, queryRoom, event, entry, fullDocument, logDebug);
425
- }
426
- else {
427
- io.to(queryRoom).emit("sync", event);
428
- }
429
- logDebug(`[realtime] Emitted soft delete to ${queryRoom} (query matched)`);
430
- }
431
- return;
432
- }
433
- if (!fullDocument) {
434
- return;
435
- }
436
- if (entry && hasFieldViews) {
437
- await emitMaskedQueryRoomEvent({ entry, event, fullDocument, io, logDebug, query, queryRoom });
438
- return;
439
- }
440
- const docMatches = (0, queryMatcher_1.matchesQuery)(fullDocument, query);
441
- if (event.method === "create" && docMatches) {
442
- // New document matches the query — send create event
443
- if (entry) {
444
- await (0, exports.emitToAuthorizedRoom)(io, queryRoom, event, entry, fullDocument, logDebug);
445
- }
446
- else {
447
- io.to(queryRoom).emit("sync", event);
448
- }
449
- logDebug(`[realtime] Emitted create to ${queryRoom} (query matched)`);
450
- }
451
- else if (event.method === "update") {
452
- if (docMatches) {
453
- // Document still matches (or newly matches) — send update event
454
- if (entry) {
455
- await (0, exports.emitToAuthorizedRoom)(io, queryRoom, event, entry, fullDocument, logDebug);
456
- }
457
- else {
458
- io.to(queryRoom).emit("sync", event);
459
- }
460
- logDebug(`[realtime] Emitted update to ${queryRoom} (query matched)`);
461
- }
462
- else {
463
- // Document no longer matches the query — send delete event so client removes it
464
- const removeEvent = {
465
- ...event,
466
- method: "delete",
467
- };
468
- if (entry) {
469
- await (0, exports.emitToAuthorizedRoom)(io, queryRoom, removeEvent, entry, fullDocument, logDebug);
470
- }
471
- else {
472
- io.to(queryRoom).emit("sync", removeEvent);
473
- }
474
- logDebug(`[realtime] Emitted delete to ${queryRoom} (query no longer matched)`);
475
- }
476
- }
477
- };
478
- /**
479
- * Emit a sync event to document-specific and query rooms.
480
- *
481
- * Document rooms: `document:{collection}:{docId}` — clients subscribed to a single document.
482
- * Query rooms: `query:{queryId}` — clients subscribed to a query filter. The change stream
483
- * watcher evaluates whether the document matches each active query for the collection.
484
- *
485
- * For deletes, we are careful not to leak cross-user activity:
486
- * - Soft deletes (fullDocument present) are matched against each query like updates so
487
- * query subscribers only see deletes for docs that matched their filter.
488
- * - Hard deletes (fullDocument absent) on owner-strategy collections are NOT forwarded
489
- * to query rooms — subscribers will reconcile on their next fetch. Other strategies
490
- * forward the delete because the model/broadcast rooms are not user-scoped.
491
- *
492
- * Exported for testing.
493
- */
494
- /** @internal */
495
- const emitToDocumentAndQueryRooms = async (io, collection, event, fullDocument, logDebug, entry) => {
496
- // Emit to document-specific room
497
- const docRoom = `document:${collection}:${event.id}`;
498
- if (entry) {
499
- await (0, exports.emitToAuthorizedRoom)(io, docRoom, event, entry, fullDocument, logDebug);
500
- }
501
- else {
502
- io.to(docRoom).emit("sync", event);
503
- }
504
- logDebug(`[realtime] Emitted ${event.method} to ${docRoom}`);
505
- const isOwnerStrategy = entry?.config.roomStrategy === "owner";
506
- const hasFieldViews = Boolean(entry?.options.access && entry?.options.accessControl);
507
- // Evaluate query subscriptions
508
- const querySubscriptions = (0, queryStore_1.getQuerySubscriptionsForCollection)(collection);
509
- for (const subscription of querySubscriptions) {
510
- try {
511
- await emitToQueryRoom({
512
- entry,
513
- event,
514
- fullDocument,
515
- hasFieldViews,
516
- io,
517
- isOwnerStrategy,
518
- logDebug,
519
- query: subscription.query,
520
- queryRoom: `query:${subscription.queryId}`,
521
- });
522
- }
523
- catch (error) {
524
- // One subscription's failure must not stop the others or the change's sync:delta.
525
- logger_1.logger.warn(`[realtime] Query subscription ${subscription.queryId} failed to evaluate; skipping it: ${error}`);
526
- }
527
- }
528
- };
529
- exports.emitToDocumentAndQueryRooms = emitToDocumentAndQueryRooms;
530
- /**
531
- * Emit legacy realtime "sync" events for a change on a realtime-registered collection.
532
- * Extracted verbatim from the change handler so sync-delta emission (which is keyed off
533
- * the independent sync registry) runs even when the realtime path skips the change.
534
- */
535
- const processRealtimeChange = async ({ io, entry, change, docId, logDebug, logInfo, }) => {
536
- // Map to our method type. Pass enabledMethods so soft deletes only
537
- // remap to "delete" when the model actually subscribes to deletes —
538
- // otherwise the change is kept as "update" so update subscribers
539
- // still receive it.
540
- const method = (0, exports.mapOperationType)(change.operationType, change, entry.config.methods);
541
- if (!method) {
542
- return;
543
- }
544
- // Check if this method is enabled for this model
545
- if (!entry.config.methods.includes(method)) {
546
- logDebug(`[realtime] Method ${method} not enabled for ${entry.modelName}`);
547
- return;
548
- }
549
- // fullDocument is present on insert/update/replace; absent on delete.
550
- const fullDocument = change.operationType === "delete" ? undefined : change.fullDocument;
551
- // For hard deletes, we don't have the full document
552
- const isHardDelete = method === "delete" && !fullDocument;
553
- // Determine target rooms
554
- let rooms;
555
- if (isHardDelete) {
556
- // Hard delete: no fullDocument, so we can't resolve owner/custom rooms.
557
- // For owner strategy we cannot safely fan out to a model room without
558
- // leaking deletes across users — admins still receive the event via the
559
- // admin room and any document-specific subscribers via document rooms.
560
- if (entry.config.roomStrategy === "owner") {
561
- rooms = ["admin"];
562
- }
563
- else if (entry.config.roomStrategy === "broadcast") {
564
- rooms = ["authenticated"];
565
- }
566
- else {
567
- const collectionTag = getCollectionTag(entry.routePath);
568
- rooms = [`model:${collectionTag}`];
569
- }
570
- }
571
- else {
572
- rooms = (0, exports.resolveRooms)(entry, fullDocument ?? {}, method);
573
- }
574
- const collection = getCollectionTag(entry.routePath);
575
- const event = {
576
- collection,
577
- id: docId,
578
- method,
579
- model: entry.modelName,
580
- timestamp: luxon_1.DateTime.now().toMillis(),
581
- ...(change.operationType === "update" && change.updateDescription?.updatedFields
582
- ? { updatedFields: Object.keys(change.updateDescription.updatedFields) }
583
- : {}),
584
- };
585
- // Emit to strategy-based rooms (model/owner/broadcast)
586
- for (const room of rooms) {
587
- await (0, exports.emitToAuthorizedRoom)(io, room, event, entry, fullDocument, logDebug);
588
- }
589
- // Emit to document-specific and query rooms
590
- await (0, exports.emitToDocumentAndQueryRooms)(io, collection, event, fullDocument, logDebug, entry);
591
- logDebug(`[realtime] Emitted ${method} for ${entry.modelName}/${docId} to rooms: ${rooms.join(", ")}`);
592
- // Log only metadata — never the document payload, which may contain sensitive fields.
593
- const metadata = {
594
- collection: event.collection,
595
- id: event.id,
596
- method: event.method,
597
- model: event.model,
598
- timestamp: event.timestamp,
599
- };
600
- if (event.updatedFields) {
601
- metadata.updatedFields = event.updatedFields;
602
- }
603
- logInfo(`[realtime] sync event: ${JSON.stringify(metadata)}`);
604
- };
605
265
  /**
606
266
  * Emit `sync:delta` events for a change on a sync-registered collection.
607
267
  *
608
268
  * Deltas fan out to the dedicated `sync:{stream}` rooms joined via `sync:subscribe`
609
- * (independent of the legacy realtime rooms), with the same per-socket read-permission
610
- * checks as legacy events. `seq` and `stream` come from the post-image: the `syncPlugin`
269
+ * with per-socket read-permission checks. `seq` and `stream` come from the post-image: the `syncPlugin`
611
270
  * stamps `_syncSeq` on every synced write and the watcher runs `updateLookup`.
612
271
  *
613
272
  * Soft deletes (an update setting `deleted: true`, reclassified by `mapOperationType`)
@@ -626,9 +285,6 @@ const processRealtimeChange = async ({ io, entry, change, docId, logDebug, logIn
626
285
  * emit time, C1); the client advances its cursor to `min(delta.seq, delta.frontierSeq)`
627
286
  * so a delta observed out of commit order never advances a cursor past an uncommitted hole.
628
287
  *
629
- * A model with both `realtime` and `sync` configs emits both the legacy "sync" event and
630
- * "sync:delta" — distinct event names, no interference (documented as transitional).
631
- *
632
288
  * Exported for testing.
633
289
  */
634
290
  const emitSyncDeltaForChange = async ({ io, entry, change, docId, logDebug, }) => {
@@ -730,7 +386,7 @@ const emitSyncDeltaForChange = async ({ io, entry, change, docId, logDebug, }) =
730
386
  };
731
387
  exports.emitSyncDeltaForChange = emitSyncDeltaForChange;
732
388
  /**
733
- * Start watching MongoDB change streams and emitting real-time events.
389
+ * Start watching MongoDB change streams and emitting `sync:delta` events.
734
390
  *
735
391
  * Task 9.16: the stream is supervised — an `error`/`close`/`end` schedules a re-open with
736
392
  * exponential backoff, resuming from the last seen token. Call
@@ -857,39 +513,24 @@ const openChangeStream = ({ config, debug, io, isReopen = false, }) => {
857
513
  if (ignoredOps.has(change.operationType)) {
858
514
  return;
859
515
  }
860
- // Realtime and sync registries are independent: a model may be in either or both.
861
- // A model with both configs emits both the legacy "sync" event and "sync:delta".
862
- const entry = (0, registry_2.findRegistryEntryByCollection)(collectionName);
863
516
  const syncEntry = (0, registry_1.findSyncEntryByCollectionName)(collectionName);
864
- if (!entry && !syncEntry) {
865
- // Not a registered realtime or sync model — skip
866
- logDebug(`[realtime] No registry entry for collection: ${collectionName}`);
517
+ if (!syncEntry) {
518
+ // Not a sync-registered model — skip
519
+ logDebug(`[realtime] No sync registry entry for collection: ${collectionName}`);
867
520
  return;
868
521
  }
869
- if (entry) {
870
- // A legacy realtime failure must not skip the independent sync:delta emission.
522
+ // C8: serialize per entity so same-doc deltas emit in change-stream order;
523
+ // different docs still dispatch concurrently. See serializePerEntity + the
524
+ // per-entity LWW-by-seq contract documented in sync/types.ts (SyncDelta).
525
+ serializePerEntity(`${collectionName}:${docId}`, async () => {
871
526
  try {
872
- await processRealtimeChange({ change, docId, entry, io, logDebug, logInfo });
527
+ await (0, exports.emitSyncDeltaForChange)({ change, docId, entry: syncEntry, io, logDebug });
873
528
  }
874
529
  catch (error) {
875
- logger_1.logger.error(`[realtime] Error processing realtime change: ${error}`);
530
+ logger_1.logger.error(`[sync] Error emitting sync delta: ${error}`);
876
531
  Sentry.captureException(error);
877
532
  }
878
- }
879
- if (syncEntry) {
880
- // C8: serialize per entity so same-doc deltas emit in change-stream order;
881
- // different docs still dispatch concurrently. See serializePerEntity + the
882
- // per-entity LWW-by-seq contract documented in sync/types.ts (SyncDelta).
883
- serializePerEntity(`${collectionName}:${docId}`, async () => {
884
- try {
885
- await (0, exports.emitSyncDeltaForChange)({ change, docId, entry: syncEntry, io, logDebug });
886
- }
887
- catch (error) {
888
- logger_1.logger.error(`[sync] Error emitting sync delta: ${error}`);
889
- Sentry.captureException(error);
890
- }
891
- });
892
- }
533
+ });
893
534
  }
894
535
  catch (error) {
895
536
  logger_1.logger.error(`[realtime] Error processing change event: ${error}`);
@@ -3,15 +3,8 @@ import type express from "express";
3
3
  import { Server } from "socket.io";
4
4
  import type { TerrenoApp } from "../terrenoApp";
5
5
  import type { TerrenoPlugin } from "../terrenoPlugin";
6
- import { type SocketWithDecodedToken } from "./socketUser";
6
+ import type { SocketWithDecodedToken } from "./socketUser";
7
7
  import type { RealtimeAppOptions } from "./types";
8
- /**
9
- * Caps on per-socket subscriptions. Prevents a malicious or buggy client from
10
- * exhausting server memory by opening unbounded subscriptions.
11
- */
12
- export declare const MAX_MODEL_SUBSCRIPTIONS = 50;
13
- export declare const MAX_DOCUMENT_SUBSCRIPTIONS = 500;
14
- export declare const MAX_QUERY_SUBSCRIPTIONS = 100;
15
8
  /**
16
9
  * Replace any userinfo (`user:password@`) component in a URL with `***@` so the
17
10
  * credentials are not written to logs. Falls back to a regex when the string
@@ -33,32 +26,25 @@ export interface RealtimeSocketLike extends SocketWithDecodedToken {
33
26
  on: (event: string, handler: (...args: never[]) => void | Promise<void>) => void;
34
27
  }
35
28
  /**
36
- * Install the realtime subscription handlers on a single socket. Extracted from the
37
- * RealtimeApp connection handler so this logic can be unit-tested with a mock socket
38
- * (no real Socket.io / HTTP server / JWT handshake required).
29
+ * Install the base socket handlers on a single socket: join the per-user, `authenticated`,
30
+ * and (for admins) `admin` rooms, and log disconnects. Extracted from the RealtimeApp
31
+ * connection handler so it can be unit-tested with a mock socket (no real Socket.io /
32
+ * HTTP server / JWT handshake required).
39
33
  *
40
- * Enforces:
41
- * - per-socket subscription caps (DoS protection)
42
- * - registry membership (only realtime-enabled collections can be subscribed)
43
- * - owner-strategy isolation (non-admin users cannot subscribe to other users' rooms)
44
- * - server-side queryId computation (clients can't hijack queries by colliding ids)
34
+ * Collection subscriptions go through the sync protocol (`sync:subscribe`), installed
35
+ * separately by `installSyncSocketHandlers`.
45
36
  */
46
37
  export declare const installRealtimeSocketHandlers: (socket: RealtimeSocketLike, options?: {
47
38
  logInfo?: (msg: string) => void;
48
39
  }) => void;
49
40
  /**
50
- * TerrenoPlugin that provides real-time sync via Socket.io and MongoDB change streams.
41
+ * TerrenoPlugin that hosts Socket.io and the MongoDB change stream watcher for
42
+ * `@terreno/syncdb`.
51
43
  *
52
44
  * Attaches a Socket.io server to the HTTP server created by TerrenoApp.start(),
53
- * sets up JWT and/or Better Auth authentication for socket connections, manages room subscriptions
54
- * (model, document, and query rooms), and starts a change stream watcher that
55
- * emits events to connected clients.
56
- *
57
- * ## Subscription types
58
- *
59
- * - **Model rooms**: `subscribe:model` / `unsubscribe:model` — receive all events for a collection
60
- * - **Document rooms**: `subscribe:document` / `unsubscribe:document` — receive events for a single document
61
- * - **Query rooms**: `subscribe:query` / `unsubscribe:query` — receive events matching a MongoDB query
45
+ * sets up JWT and/or Better Auth authentication for socket connections, installs the
46
+ * sync protocol handlers (`sync:subscribe` / `sync:mutate`), and starts a change stream
47
+ * watcher that emits `sync:delta` events for models registered with `sync`.
62
48
  *
63
49
  * @example
64
50
  * ```typescript
@@ -66,7 +52,8 @@ export declare const installRealtimeSocketHandlers: (socket: RealtimeSocketLike,
66
52
  * userModel: User,
67
53
  * realtime: { debug: true },
68
54
  * })
69
- * .register(todoRouter) // todoRouter has realtime config
55
+ * .register(todoRouter) // todoRouter has a `sync` config
56
+ * .register(new SyncApp())
70
57
  * .start();
71
58
  * ```
72
59
  */