@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.
- package/CHANGELOG.md +43 -0
- package/README.md +1 -1
- package/biome.jsonc +2 -2
- package/dist/api.d.ts +0 -13
- package/dist/api.js +0 -9
- package/dist/auth.d.ts +3 -2
- package/dist/auth.js +95 -5
- package/dist/authRecovery.d.ts +2 -1
- package/dist/authRecovery.js +35 -17
- package/dist/collectionRegistry.d.ts +3 -4
- package/dist/collectionRegistry.js +0 -1
- package/dist/consentApp.d.ts +1 -1
- package/dist/consentApp.js +58 -2
- package/dist/index.d.ts +4 -5
- package/dist/index.js +8 -20
- package/dist/mcp/adminTracking.js +1 -1
- package/dist/mcp/serviceTokens.d.ts +21 -1
- package/dist/mcp/serviceTokens.js +159 -183
- package/dist/migrations/builtin/mcpServiceTokenStringIds.d.ts +18 -0
- package/dist/migrations/builtin/mcpServiceTokenStringIds.js +67 -0
- package/dist/models/mcpRequestLog.js +1 -1
- package/dist/models/mcpServiceToken.js +36 -4
- package/dist/openApiBuilder.d.ts +4 -0
- package/dist/openApiBuilder.js +2 -0
- package/dist/rbac/realtimeAccess.d.ts +5 -4
- package/dist/rbac/realtimeAccess.js +17 -64
- package/dist/realtime/changeStreamWatcher.d.ts +8 -63
- package/dist/realtime/changeStreamWatcher.js +32 -391
- package/dist/realtime/realtimeApp.d.ts +14 -27
- package/dist/realtime/realtimeApp.js +14 -220
- package/dist/realtime/types.d.ts +0 -64
- package/dist/sync/executors.js +14 -2
- package/dist/sync/socketHandlers.d.ts +1 -1
- package/dist/sync/socketHandlers.js +1 -1
- package/dist/terrenoApp.d.ts +7 -5
- package/dist/terrenoApp.js +18 -14
- package/dist/tests/openApiResponseSchema.d.ts +39 -0
- package/dist/tests/openApiResponseSchema.js +56 -0
- package/dist/tests.d.ts +1 -0
- package/dist/tests.js +4 -1
- package/dist/types/mcpAdmin.d.ts +1 -1
- package/dist/types/mcpServiceToken.d.ts +7 -4
- package/dist/versionCheckPlugin.d.ts +1 -1
- package/dist/versionCheckPlugin.js +25 -2
- package/package.json +10 -6
- package/src/__snapshots__/openApi.test.ts.snap +4986 -2478
- package/src/__snapshots__/openApiBuilder.test.ts.snap +836 -0
- package/src/__tests__/openApiResponseSchema.test.ts +148 -0
- package/src/__tests__/versionCheckPlugin.test.ts +72 -0
- package/src/api.test.ts +9 -7
- package/src/api.ts +0 -24
- package/src/auth.ts +116 -5
- package/src/authOpenApi.test.ts +316 -0
- package/src/authRecovery.ts +47 -19
- package/src/betterAuthOAuthHandoff.test.ts +13 -5
- package/src/collectionRegistry.ts +3 -5
- package/src/consentApp.test.ts +98 -0
- package/src/consentApp.ts +67 -2
- package/src/index.ts +6 -28
- package/src/mcp/actionTools.test.ts +2 -2
- package/src/mcp/adminTracking.ts +1 -1
- package/src/mcp/auth.test.ts +7 -3
- package/src/mcp/oauth.test.ts +12 -12
- package/src/mcp/serviceTokens.sync.test.ts +230 -0
- package/src/mcp/serviceTokens.test.ts +112 -61
- package/src/mcp/serviceTokens.ts +193 -212
- package/src/migrations/builtin/mcpServiceTokenStringIds.test.ts +194 -0
- package/src/migrations/builtin/mcpServiceTokenStringIds.ts +121 -0
- package/src/models/mcpRequestLog.ts +1 -1
- package/src/models/mcpServiceToken.test.ts +52 -5
- package/src/models/mcpServiceToken.ts +51 -14
- package/src/openApiBuilder.test.ts +34 -1
- package/src/openApiBuilder.ts +5 -0
- package/src/rateLimit/rateLimit.test.ts +25 -10
- package/src/rbac/realtimeAccess.test.ts +20 -172
- package/src/rbac/realtimeAccess.ts +17 -82
- package/src/realtime/changeStreamWatcher.ts +43 -506
- package/src/realtime/realtime.test.ts +205 -2545
- package/src/realtime/realtimeApp.ts +16 -295
- package/src/realtime/types.ts +0 -72
- package/src/sync/executors.test.ts +28 -0
- package/src/sync/executors.ts +23 -2
- package/src/sync/socketHandlers.ts +1 -1
- package/src/sync/syncSocket.test.ts +77 -113
- package/src/terrenoApp.mcpServiceTokens.test.ts +14 -6
- package/src/terrenoApp.ts +24 -18
- package/src/tests/openApiResponseSchema.ts +104 -0
- package/src/tests.ts +7 -0
- package/src/types/mcpAdmin.ts +1 -1
- package/src/types/mcpServiceToken.ts +7 -4
- package/src/versionCheckPlugin.ts +41 -2
- package/dist/realtime/deprecation.d.ts +0 -13
- package/dist/realtime/deprecation.js +0 -31
- package/dist/realtime/queryStore.d.ts +0 -37
- package/dist/realtime/queryStore.js +0 -103
- package/dist/realtime/registry.d.ts +0 -15
- package/dist/realtime/registry.js +0 -52
- package/src/realtime/deprecation.test.ts +0 -60
- package/src/realtime/deprecation.ts +0 -33
- package/src/realtime/queryStore.ts +0 -122
- 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
|
|
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
|
|
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
|
|
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
|
|
199
|
-
* `
|
|
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
|
-
*
|
|
219
|
-
*
|
|
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
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
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
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
|
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
|
-
|
|
1100
|
-
|
|
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
|
-
|
|
1106
|
-
|
|
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
|
|
659
|
+
await emitSyncDeltaForChange({change, docId, entry: syncEntry, io, logDebug});
|
|
1109
660
|
} catch (error) {
|
|
1110
|
-
logger.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);
|