@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,84 +1,45 @@
1
1
  /**
2
2
  * Tests for the realtime module's pure functions and classes:
3
3
  * - queryMatcher.ts (matchesQuery)
4
- * - queryStore.ts (addQuerySubscription, removeQuerySubscription, etc.)
5
- * - registry.ts (registerRealtime, getRealtimeRegistry, etc.)
6
4
  * - realtimeApp.ts (RealtimeApp class — register, getIo, close)
7
- * - realtimeApp.ts (installRealtimeSocketHandlers — permission and rate-limit logic)
8
- * - changeStreamWatcher.ts (serializeDoc — responseHandler fallback)
5
+ * - realtimeApp.ts (installRealtimeSocketHandlers — per-user room joins)
6
+ * - changeStreamWatcher.ts (authorized room emitter, watcher lifecycle)
9
7
  */
10
8
 
11
- import {afterEach, beforeAll, beforeEach, describe, expect, it, mock} from "bun:test";
12
- import {assert} from "chai";
9
+ import {afterEach, beforeEach, describe, expect, it, mock} from "bun:test";
13
10
  import express from "express";
14
- import mongoose, {type Model} from "mongoose";
11
+ import mongoose from "mongoose";
15
12
  import type {Server} from "socket.io";
16
13
 
17
- import type {JSONValue, ModelRouterOptions} from "../api";
18
-
19
14
  import {clearAdminBroadcastScopes, registerAdminBroadcastScope} from "../sync/adminBroadcastScope";
20
15
  import {
21
- emitToAuthorizedRoom,
22
- emitToDocumentAndQueryRooms,
16
+ type AuthorizedEmitEntry,
17
+ emitPayloadToAuthorizedRoom,
23
18
  ensureApiId,
24
19
  mapOperationType,
25
- resolveRooms,
26
- serializeDoc,
27
20
  startChangeStreamWatcher,
28
21
  stopChangeStreamWatcher,
29
22
  } from "./changeStreamWatcher";
30
23
  import {matchesQuery} from "./queryMatcher";
31
- import {
32
- addQuerySubscription,
33
- clearQueryStore,
34
- computeQueryId,
35
- getQuerySubscriptionsForCollection,
36
- removeAllSocketQueries,
37
- removeQuerySubscription,
38
- } from "./queryStore";
39
24
  import {
40
25
  installRealtimeSocketHandlers,
41
- MAX_MODEL_SUBSCRIPTIONS,
42
- MAX_QUERY_SUBSCRIPTIONS,
43
26
  RealtimeApp,
44
27
  type RealtimeSocketLike,
45
28
  redactCredentials,
46
29
  } from "./realtimeApp";
47
- import {
48
- clearRealtimeRegistry,
49
- findRegistryEntryByCollection,
50
- findRegistryEntryByRoutePath,
51
- getRealtimeRegistry,
52
- type RealtimeRegistryEntry,
53
- registerRealtime,
54
- updateRealtimeRegistryOptions,
55
- } from "./registry";
56
30
  import type {DecodedRealtimeToken} from "./socketUser";
57
- import type {RealtimeConfig, RealtimeEvent} from "./types";
58
31
 
59
32
  type ChangeStreamDoc = Parameters<typeof mapOperationType>[1];
60
33
 
61
34
  const asChange = (change: Record<string, unknown>): ChangeStreamDoc =>
62
35
  change as unknown as ChangeStreamDoc;
63
36
 
64
- type ResponseHandler = NonNullable<ModelRouterOptions<unknown>["responseHandler"]>;
65
-
66
37
  interface MockRoomSocket {
67
38
  decodedToken?: DecodedRealtimeToken;
68
39
  emit: (event: string, payload: unknown) => void;
69
40
  id: string;
70
41
  }
71
42
 
72
- const permissiveOptions: ModelRouterOptions<unknown> = {
73
- permissions: {
74
- create: [() => true],
75
- delete: [() => true],
76
- list: [() => true],
77
- read: [() => true],
78
- update: [() => true],
79
- },
80
- };
81
-
82
43
  const setConnectionDb = (db: unknown): void => {
83
44
  (mongoose.connection as unknown as {db: unknown}).db = db;
84
45
  };
@@ -370,289 +331,6 @@ describe("matchesQuery", () => {
370
331
  });
371
332
  });
372
333
 
373
- // ─────────────────────────────────────────────────────────────────────────────
374
- // queryStore tests
375
- // ─────────────────────────────────────────────────────────────────────────────
376
-
377
- describe("queryStore", () => {
378
- beforeEach(() => {
379
- clearQueryStore();
380
- clearAdminBroadcastScopes();
381
- });
382
-
383
- afterEach(() => {
384
- clearQueryStore();
385
- clearAdminBroadcastScopes();
386
- });
387
-
388
- describe("computeQueryId", () => {
389
- it("produces a deterministic id from collection and query", () => {
390
- const id1 = computeQueryId("todos", {completed: false});
391
- const id2 = computeQueryId("todos", {completed: false});
392
- expect(id1).toBe(id2);
393
- });
394
-
395
- it("normalizes key order before computing id", () => {
396
- const id1 = computeQueryId("todos", {completed: false, ownerId: "abc"});
397
- const id2 = computeQueryId("todos", {completed: false, ownerId: "abc"});
398
- expect(id1).toBe(id2);
399
- });
400
-
401
- it("includes the collection name in the id", () => {
402
- const id = computeQueryId("todos", {completed: false});
403
- expect(id.startsWith("todos:")).toBe(true);
404
- });
405
-
406
- it("produces different ids for different collections", () => {
407
- const id1 = computeQueryId("todos", {completed: false});
408
- const id2 = computeQueryId("items", {completed: false});
409
- expect(id1).not.toBe(id2);
410
- });
411
-
412
- it("produces different ids for different queries", () => {
413
- const id1 = computeQueryId("todos", {completed: false});
414
- const id2 = computeQueryId("todos", {completed: true});
415
- expect(id1).not.toBe(id2);
416
- });
417
- });
418
-
419
- describe("addQuerySubscription", () => {
420
- it("stores a subscription and makes it retrievable", () => {
421
- addQuerySubscription("socket1", "todos", {completed: false}, "todos:q1");
422
- const subs = getQuerySubscriptionsForCollection("todos");
423
- expect(subs).toHaveLength(1);
424
- expect(subs[0].queryId).toBe("todos:q1");
425
- });
426
-
427
- it("allows the same socket to subscribe to multiple queries", () => {
428
- addQuerySubscription("socket1", "todos", {completed: false}, "todos:q1");
429
- addQuerySubscription("socket1", "todos", {completed: true}, "todos:q2");
430
- const subs = getQuerySubscriptionsForCollection("todos");
431
- expect(subs).toHaveLength(2);
432
- });
433
-
434
- it("allows multiple sockets to subscribe to the same query", () => {
435
- addQuerySubscription("socket1", "todos", {completed: false}, "todos:q1");
436
- addQuerySubscription("socket2", "todos", {completed: false}, "todos:q1");
437
- const subs = getQuerySubscriptionsForCollection("todos");
438
- // Same queryId — deduplicated in the store
439
- expect(subs).toHaveLength(1);
440
- });
441
- });
442
-
443
- describe("removeQuerySubscription", () => {
444
- it("removes a specific query for a socket", () => {
445
- addQuerySubscription("socket1", "todos", {completed: false}, "todos:q1");
446
- removeQuerySubscription("socket1", "todos:q1");
447
- const subs = getQuerySubscriptionsForCollection("todos");
448
- expect(subs).toHaveLength(0);
449
- });
450
-
451
- it("does not remove a query if another socket still uses it", () => {
452
- addQuerySubscription("socket1", "todos", {completed: false}, "todos:q1");
453
- addQuerySubscription("socket2", "todos", {completed: false}, "todos:q1");
454
- removeQuerySubscription("socket1", "todos:q1");
455
- const subs = getQuerySubscriptionsForCollection("todos");
456
- expect(subs).toHaveLength(1);
457
- });
458
-
459
- it("is safe to call for a socket that has no subscriptions", () => {
460
- expect(() => removeQuerySubscription("nonexistent", "todos:q1")).not.toThrow();
461
- });
462
- });
463
-
464
- describe("removeAllSocketQueries", () => {
465
- it("removes all subscriptions for a socket", () => {
466
- addQuerySubscription("socket1", "todos", {completed: false}, "todos:q1");
467
- addQuerySubscription("socket1", "todos", {completed: true}, "todos:q2");
468
- removeAllSocketQueries("socket1");
469
- const subs = getQuerySubscriptionsForCollection("todos");
470
- expect(subs).toHaveLength(0);
471
- });
472
-
473
- it("preserves subscriptions for other sockets", () => {
474
- addQuerySubscription("socket1", "todos", {completed: false}, "todos:q1");
475
- addQuerySubscription("socket2", "todos", {completed: true}, "todos:q2");
476
- removeAllSocketQueries("socket1");
477
- const subs = getQuerySubscriptionsForCollection("todos");
478
- expect(subs).toHaveLength(1);
479
- expect(subs[0].queryId).toBe("todos:q2");
480
- });
481
-
482
- it("is safe to call for a socket that has no subscriptions", () => {
483
- expect(() => removeAllSocketQueries("nonexistent")).not.toThrow();
484
- });
485
-
486
- it("only removes a shared query if no other sockets use it", () => {
487
- addQuerySubscription("socket1", "todos", {completed: false}, "todos:q1");
488
- addQuerySubscription("socket2", "todos", {completed: false}, "todos:q1");
489
- removeAllSocketQueries("socket1");
490
- // socket2 still subscribes — query should remain
491
- const subs = getQuerySubscriptionsForCollection("todos");
492
- expect(subs).toHaveLength(1);
493
- });
494
- });
495
-
496
- describe("getQuerySubscriptionsForCollection", () => {
497
- it("returns only subscriptions for the given collection", () => {
498
- addQuerySubscription("socket1", "todos", {completed: false}, "todos:q1");
499
- addQuerySubscription("socket2", "items", {status: "active"}, "items:q1");
500
- const todoSubs = getQuerySubscriptionsForCollection("todos");
501
- expect(todoSubs).toHaveLength(1);
502
- expect(todoSubs[0].queryId).toBe("todos:q1");
503
- });
504
-
505
- it("returns an empty array when no subscriptions exist for collection", () => {
506
- const subs = getQuerySubscriptionsForCollection("nonexistent");
507
- expect(subs).toHaveLength(0);
508
- });
509
-
510
- it("returns query data for each subscription", () => {
511
- const query = {completed: false, ownerId: "user1"};
512
- addQuerySubscription("socket1", "todos", query, "todos:q1");
513
- const subs = getQuerySubscriptionsForCollection("todos");
514
- expect(subs[0].query).toEqual(query);
515
- });
516
- });
517
-
518
- describe("clearQueryStore", () => {
519
- it("removes all subscriptions", () => {
520
- addQuerySubscription("socket1", "todos", {completed: false}, "todos:q1");
521
- addQuerySubscription("socket2", "items", {status: "active"}, "items:q1");
522
- clearQueryStore();
523
- expect(getQuerySubscriptionsForCollection("todos")).toHaveLength(0);
524
- expect(getQuerySubscriptionsForCollection("items")).toHaveLength(0);
525
- });
526
- });
527
- });
528
-
529
- // ─────────────────────────────────────────────────────────────────────────────
530
- // registry tests
531
- // ─────────────────────────────────────────────────────────────────────────────
532
-
533
- describe("realtimeRegistry", () => {
534
- const makeEntry = (overrides: Partial<RealtimeRegistryEntry> = {}): RealtimeRegistryEntry => ({
535
- collectionName: "todos",
536
- config: {
537
- methods: ["create" as const, "update" as const, "delete" as const],
538
- roomStrategy: "owner" as const,
539
- },
540
- modelName: "Todo",
541
- options: permissiveOptions,
542
- routePath: "/todos",
543
- ...overrides,
544
- });
545
-
546
- beforeEach(() => {
547
- clearRealtimeRegistry();
548
- });
549
-
550
- afterEach(() => {
551
- clearRealtimeRegistry();
552
- });
553
-
554
- describe("registerRealtime", () => {
555
- it("adds an entry to the registry", () => {
556
- registerRealtime(makeEntry());
557
- expect(getRealtimeRegistry()).toHaveLength(1);
558
- });
559
-
560
- it("allows multiple entries", () => {
561
- registerRealtime(makeEntry({modelName: "Todo", routePath: "/todos"}));
562
- registerRealtime(
563
- makeEntry({collectionName: "items", modelName: "Item", routePath: "/items"})
564
- );
565
- expect(getRealtimeRegistry()).toHaveLength(2);
566
- });
567
- });
568
-
569
- describe("getRealtimeRegistry", () => {
570
- it("returns all registered entries", () => {
571
- registerRealtime(makeEntry({modelName: "Todo"}));
572
- registerRealtime(
573
- makeEntry({collectionName: "items", modelName: "Item", routePath: "/items"})
574
- );
575
- const registry = getRealtimeRegistry();
576
- expect(registry).toHaveLength(2);
577
- expect(registry.map((e) => e.modelName)).toEqual(["Todo", "Item"]);
578
- });
579
-
580
- it("returns empty array when nothing is registered", () => {
581
- expect(getRealtimeRegistry()).toHaveLength(0);
582
- });
583
- });
584
-
585
- describe("findRegistryEntryByCollection", () => {
586
- it("finds an entry by collection name", () => {
587
- registerRealtime(makeEntry({collectionName: "todos"}));
588
- const entry = findRegistryEntryByCollection("todos");
589
- expect(entry).toBeDefined();
590
- expect(entry?.collectionName).toBe("todos");
591
- });
592
-
593
- it("returns undefined for unknown collection", () => {
594
- const entry = findRegistryEntryByCollection("nonexistent");
595
- expect(entry).toBeUndefined();
596
- });
597
-
598
- it("returns first match when multiple entries exist", () => {
599
- registerRealtime(makeEntry({collectionName: "todos", modelName: "Todo1"}));
600
- registerRealtime(makeEntry({collectionName: "todos", modelName: "Todo2"}));
601
- const entry = findRegistryEntryByCollection("todos");
602
- expect(entry?.modelName).toBe("Todo1");
603
- });
604
- });
605
-
606
- describe("findRegistryEntryByRoutePath", () => {
607
- it("finds an entry by exact route path with leading slash", () => {
608
- registerRealtime(makeEntry({routePath: "/todos"}));
609
- const entry = findRegistryEntryByRoutePath("todos");
610
- expect(entry).toBeDefined();
611
- expect(entry?.routePath).toBe("/todos");
612
- });
613
-
614
- it("finds an entry when collection matches routePath exactly", () => {
615
- registerRealtime(makeEntry({routePath: "todos"}));
616
- const entry = findRegistryEntryByRoutePath("todos");
617
- expect(entry).toBeDefined();
618
- });
619
-
620
- it("returns undefined for unknown route path", () => {
621
- registerRealtime(makeEntry({routePath: "/todos"}));
622
- const entry = findRegistryEntryByRoutePath("items");
623
- expect(entry).toBeUndefined();
624
- });
625
- });
626
-
627
- describe("clearRealtimeRegistry", () => {
628
- it("removes all entries", () => {
629
- registerRealtime(makeEntry());
630
- clearRealtimeRegistry();
631
- expect(getRealtimeRegistry()).toHaveLength(0);
632
- });
633
- });
634
-
635
- describe("updateRealtimeRegistryOptions", () => {
636
- it("replaces options on an existing entry by route path", () => {
637
- registerRealtime(makeEntry({routePath: "/todos"}));
638
- const updatedOptions: ModelRouterOptions<unknown> = {
639
- permissions: {create: [], delete: [], list: [], read: [], update: []},
640
- };
641
- updateRealtimeRegistryOptions("/todos", updatedOptions);
642
-
643
- expect(getRealtimeRegistry()[0]?.options).toBe(updatedOptions);
644
- });
645
-
646
- it("no-ops when the route path is not registered", () => {
647
- registerRealtime(makeEntry({routePath: "/todos"}));
648
- const originalOptions = getRealtimeRegistry()[0]?.options;
649
- updateRealtimeRegistryOptions("/missing", {permissions: {}} as ModelRouterOptions<unknown>);
650
-
651
- expect(getRealtimeRegistry()[0]?.options).toBe(originalOptions);
652
- });
653
- });
654
- });
655
-
656
334
  // ─────────────────────────────────────────────────────────────────────────────
657
335
  // RealtimeApp tests
658
336
  // ─────────────────────────────────────────────────────────────────────────────
@@ -746,648 +424,63 @@ const createMockSocket = (decodedToken?: DecodedRealtimeToken): MockSocket => {
746
424
  };
747
425
 
748
426
  describe("installRealtimeSocketHandlers", () => {
749
- beforeEach(() => {
750
- clearRealtimeRegistry();
751
- clearQueryStore();
752
- });
753
-
754
- afterEach(() => {
755
- clearRealtimeRegistry();
756
- clearQueryStore();
757
- });
758
-
759
- const registerOwnerCollection = (): void => {
760
- registerRealtime({
761
- collectionName: "todos",
762
- config: {methods: ["create", "update", "delete"], roomStrategy: "owner"},
763
- modelName: "Todo",
764
- options: {
765
- permissions: {
766
- create: [() => true],
767
- delete: [() => true],
768
- list: [() => true],
769
- read: [() => true],
770
- update: [() => true],
771
- },
772
- queryFields: ["completed", "priority"],
773
- },
774
- routePath: "/todos",
775
- });
776
- };
777
-
778
- const registerModelCollection = (): void => {
779
- registerRealtime({
780
- collectionName: "broadcasts",
781
- config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
782
- modelName: "Broadcast",
783
- options: {
784
- permissions: {
785
- create: [() => true],
786
- delete: [() => true],
787
- list: [() => true],
788
- read: [() => true],
789
- update: [() => true],
790
- },
791
- queryFields: ["priority"],
792
- },
793
- routePath: "/broadcasts",
794
- });
795
- };
796
-
797
- const registerAdminOnlyCollection = (): void => {
798
- registerRealtime({
799
- collectionName: "secrets",
800
- config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
801
- modelName: "Secret",
802
- options: {
803
- permissions: {
804
- create: [(_method: string, user?: {admin?: boolean}) => user?.admin === true],
805
- delete: [(_method: string, user?: {admin?: boolean}) => user?.admin === true],
806
- list: [(_method: string, user?: {admin?: boolean}) => user?.admin === true],
807
- read: [(_method: string, user?: {admin?: boolean}) => user?.admin === true],
808
- update: [(_method: string, user?: {admin?: boolean}) => user?.admin === true],
809
- },
810
- queryFields: ["classification"],
811
- },
812
- routePath: "/secrets",
813
- });
427
+ // joinUserRooms is fire-and-forget — give microtasks a chance to flush.
428
+ const flushJoins = async (): Promise<void> => {
429
+ await Promise.resolve();
430
+ await Promise.resolve();
814
431
  };
815
432
 
816
- describe("connection setup", () => {
817
- it("joins user-specific and authenticated rooms when token has userId", async () => {
818
- const socket = createMockSocket({id: "user1"});
819
- installRealtimeSocketHandlers(socket);
820
- // joinUserRooms is fire-and-forget — give microtasks a chance to flush.
821
- await Promise.resolve();
822
- await Promise.resolve();
823
- expect(socket.rooms.has("user:user1")).toBe(true);
824
- expect(socket.rooms.has("authenticated")).toBe(true);
825
- });
826
-
827
- it("joins admin room for admin tokens", async () => {
828
- const socket = createMockSocket({admin: true, id: "admin1"});
829
- installRealtimeSocketHandlers(socket);
830
- await Promise.resolve();
831
- await Promise.resolve();
832
- expect(socket.rooms.has("admin")).toBe(true);
833
- });
834
-
835
- it("does not join admin room for non-admin tokens", async () => {
836
- const socket = createMockSocket({admin: false, id: "user1"});
837
- installRealtimeSocketHandlers(socket);
838
- await Promise.resolve();
839
- await Promise.resolve();
840
- expect(socket.rooms.has("admin")).toBe(false);
841
- });
842
- });
843
-
844
- describe("subscribe:model permission", () => {
845
- it("denies unregistered collections", async () => {
846
- const socket = createMockSocket({id: "user1"});
847
- installRealtimeSocketHandlers(socket);
848
- await socket.trigger("subscribe:model", "nonexistent");
849
- expect(socket.rooms.has("model:nonexistent")).toBe(false);
850
- });
851
-
852
- it("denies owner-strategy model room for non-admin users", async () => {
853
- registerOwnerCollection();
854
- const socket = createMockSocket({admin: false, id: "user1"});
855
- installRealtimeSocketHandlers(socket);
856
- await socket.trigger("subscribe:model", "todos");
857
- expect(socket.rooms.has("model:todos")).toBe(false);
858
- });
859
-
860
- it("allows owner-strategy model room for admins", async () => {
861
- registerOwnerCollection();
862
- const socket = createMockSocket({admin: true, id: "admin1"});
863
- installRealtimeSocketHandlers(socket);
864
- await socket.trigger("subscribe:model", "todos");
865
- expect(socket.rooms.has("model:todos")).toBe(true);
866
- });
867
-
868
- it("allows non-admins to subscribe to model-strategy collections", async () => {
869
- registerModelCollection();
870
- const socket = createMockSocket({admin: false, id: "user1"});
871
- installRealtimeSocketHandlers(socket);
872
- await socket.trigger("subscribe:model", "broadcasts");
873
- expect(socket.rooms.has("model:broadcasts")).toBe(true);
874
- });
875
-
876
- it("denies model-strategy collections when modelRouter list permission fails", async () => {
877
- registerAdminOnlyCollection();
878
- const socket = createMockSocket({admin: false, id: "user1"});
879
- installRealtimeSocketHandlers(socket);
880
- await socket.trigger("subscribe:model", "secrets");
881
- expect(socket.rooms.has("model:secrets")).toBe(false);
882
- });
883
-
884
- it("allows model-strategy collections when modelRouter list permission passes", async () => {
885
- registerAdminOnlyCollection();
886
- const socket = createMockSocket({admin: true, id: "admin1"});
887
- installRealtimeSocketHandlers(socket);
888
- await socket.trigger("subscribe:model", "secrets");
889
- expect(socket.rooms.has("model:secrets")).toBe(true);
890
- });
891
-
892
- it("ignores empty or non-string model names", async () => {
893
- registerModelCollection();
894
- const socket = createMockSocket({id: "user1"});
895
- installRealtimeSocketHandlers(socket);
896
- await socket.trigger("subscribe:model", "");
897
- await socket.trigger("subscribe:model", 123);
898
- await socket.trigger("subscribe:model", null);
899
- const modelRooms = Array.from(socket.rooms).filter((r) => r.startsWith("model:"));
900
- expect(modelRooms).toHaveLength(0);
901
- });
902
-
903
- it("enforces MAX_MODEL_SUBSCRIPTIONS cap", async () => {
904
- // Register MAX + 5 model-strategy collections.
905
- for (let i = 0; i < MAX_MODEL_SUBSCRIPTIONS + 5; i++) {
906
- registerRealtime({
907
- collectionName: `coll${i}`,
908
- config: {methods: ["create"], roomStrategy: "model"},
909
- modelName: `Coll${i}`,
910
- options: {
911
- permissions: {
912
- create: [() => true],
913
- delete: [() => true],
914
- list: [() => true],
915
- read: [() => true],
916
- update: [() => true],
917
- },
918
- },
919
- routePath: `/coll${i}`,
920
- });
921
- }
922
- const socket = createMockSocket({id: "user1"});
923
- installRealtimeSocketHandlers(socket);
924
- for (let i = 0; i < MAX_MODEL_SUBSCRIPTIONS + 5; i++) {
925
- await socket.trigger("subscribe:model", `coll${i}`);
926
- }
927
- const modelRooms = Array.from(socket.rooms).filter((r) => r.startsWith("model:"));
928
- expect(modelRooms.length).toBe(MAX_MODEL_SUBSCRIPTIONS);
929
- });
930
- });
931
-
932
- describe("subscribe:document permission", () => {
933
- it("denies unregistered collections", async () => {
934
- const socket = createMockSocket({id: "user1"});
935
- installRealtimeSocketHandlers(socket);
936
- await socket.trigger("subscribe:document", {collection: "nonexistent", id: "abc"});
937
- const docRooms = Array.from(socket.rooms).filter((r) => r.startsWith("document:"));
938
- expect(docRooms).toHaveLength(0);
939
- });
940
-
941
- it("denies owner-strategy document subscription for non-admin", async () => {
942
- registerOwnerCollection();
943
- const socket = createMockSocket({admin: false, id: "user1"});
944
- installRealtimeSocketHandlers(socket);
945
- await socket.trigger("subscribe:document", {collection: "todos", id: "doc1"});
946
- expect(socket.rooms.has("document:todos:doc1")).toBe(false);
947
- });
948
-
949
- it("allows owner-strategy document subscription for admins", async () => {
950
- registerOwnerCollection();
951
- const socket = createMockSocket({admin: true, id: "admin1"});
952
- installRealtimeSocketHandlers(socket);
953
- await socket.trigger("subscribe:document", {collection: "todos", id: "doc1"});
954
- expect(socket.rooms.has("document:todos:doc1")).toBe(true);
955
- });
956
-
957
- it("allows model-strategy document subscription for non-admin", async () => {
958
- registerModelCollection();
959
- const socket = createMockSocket({admin: false, id: "user1"});
960
- installRealtimeSocketHandlers(socket);
961
- await socket.trigger("subscribe:document", {collection: "broadcasts", id: "doc1"});
962
- expect(socket.rooms.has("document:broadcasts:doc1")).toBe(true);
963
- });
964
-
965
- it("denies document subscriptions when modelRouter read permission fails", async () => {
966
- registerAdminOnlyCollection();
967
- const socket = createMockSocket({admin: false, id: "user1"});
968
- installRealtimeSocketHandlers(socket);
969
- await socket.trigger("subscribe:document", {collection: "secrets", id: "doc1"});
970
- expect(socket.rooms.has("document:secrets:doc1")).toBe(false);
971
- });
972
-
973
- it("ignores malformed payloads", async () => {
974
- registerModelCollection();
975
- const socket = createMockSocket({id: "user1"});
976
- installRealtimeSocketHandlers(socket);
977
- await socket.trigger("subscribe:document", null);
978
- await socket.trigger("subscribe:document", {});
979
- await socket.trigger("subscribe:document", {collection: "broadcasts"});
980
- await socket.trigger("subscribe:document", {id: "doc1"});
981
- await socket.trigger("subscribe:document", {collection: 123, id: "doc1"});
982
- const docRooms = Array.from(socket.rooms).filter((r) => r.startsWith("document:"));
983
- expect(docRooms).toHaveLength(0);
984
- });
985
- });
986
-
987
- describe("subscribe:query permission", () => {
988
- it("denies unregistered collections", async () => {
989
- const socket = createMockSocket({id: "user1"});
990
- installRealtimeSocketHandlers(socket);
991
- await socket.trigger("subscribe:query", {collection: "nope", query: {a: 1}});
992
- const queryRooms = Array.from(socket.rooms).filter((r) => r.startsWith("query:"));
993
- expect(queryRooms).toHaveLength(0);
994
- });
995
-
996
- it("injects ownerId for owner-strategy non-admin subscribers", async () => {
997
- registerOwnerCollection();
998
- const socket = createMockSocket({admin: false, id: "user1"});
999
- installRealtimeSocketHandlers(socket);
1000
- await socket.trigger("subscribe:query", {
1001
- collection: "todos",
1002
- query: {completed: false},
1003
- });
1004
-
1005
- // queryId emitted back must encode the injected ownerId
1006
- const subscribed = socket.emitted.find((e) => e.event === "query:subscribed");
1007
- expect(subscribed).toBeDefined();
1008
- if (!subscribed) {
1009
- throw new Error("Expected a query subscription event");
1010
- }
1011
- expect((subscribed.payload as {queryId: string}).queryId).toContain("user1");
1012
- });
1013
-
1014
- it("does NOT inject ownerId for admins (admins see all)", async () => {
1015
- registerOwnerCollection();
1016
- const socket = createMockSocket({admin: true, id: "admin1"});
1017
- installRealtimeSocketHandlers(socket);
1018
- await socket.trigger("subscribe:query", {
1019
- collection: "todos",
1020
- query: {completed: false},
1021
- });
1022
- const subscribed = socket.emitted.find((e) => e.event === "query:subscribed");
1023
- expect(subscribed).toBeDefined();
1024
- if (!subscribed) {
1025
- throw new Error("Expected a query subscription event");
1026
- }
1027
- expect((subscribed.payload as {queryId: string}).queryId).not.toContain("admin1");
1028
- });
1029
-
1030
- it("ignores subscriptions when user has no id (anonymous) for owner strategy", async () => {
1031
- registerOwnerCollection();
1032
- const socket = createMockSocket({admin: false}); // no id
1033
- installRealtimeSocketHandlers(socket);
1034
- await socket.trigger("subscribe:query", {
1035
- collection: "todos",
1036
- query: {completed: false},
1037
- });
1038
- const queryRooms = Array.from(socket.rooms).filter((r) => r.startsWith("query:"));
1039
- expect(queryRooms).toHaveLength(0);
1040
- });
1041
-
1042
- it("computes the queryId server-side regardless of client-provided value", async () => {
1043
- registerOwnerCollection();
1044
- const socket = createMockSocket({admin: true, id: "admin1"});
1045
- installRealtimeSocketHandlers(socket);
1046
- await socket.trigger("subscribe:query", {
1047
- collection: "todos",
1048
- query: {completed: false},
1049
- queryId: "EVIL_HIJACK", // client-provided is ignored
1050
- });
1051
- const subscribed = socket.emitted.find((e) => e.event === "query:subscribed");
1052
- const payload = subscribed?.payload as {queryId: string};
1053
- expect(payload.queryId).not.toBe("EVIL_HIJACK");
1054
- // Must match what the server computes
1055
- expect(payload.queryId).toBe(computeQueryId("todos", {completed: false}));
1056
- });
1057
-
1058
- it("denies query subscriptions when modelRouter list permission fails", async () => {
1059
- registerAdminOnlyCollection();
1060
- const socket = createMockSocket({admin: false, id: "user1"});
1061
- installRealtimeSocketHandlers(socket);
1062
- await socket.trigger("subscribe:query", {
1063
- collection: "secrets",
1064
- query: {classification: "restricted"},
1065
- });
1066
- const queryRooms = Array.from(socket.rooms).filter((r) => r.startsWith("query:"));
1067
- expect(queryRooms).toHaveLength(0);
1068
- expect(getQuerySubscriptionsForCollection("secrets")).toHaveLength(0);
1069
- });
1070
-
1071
- it("applies modelRouter queryFilter before storing a query subscription", async () => {
1072
- registerRealtime({
1073
- collectionName: "filtered",
1074
- config: {methods: ["create"], roomStrategy: "model"},
1075
- modelName: "Filtered",
1076
- options: {
1077
- permissions: {
1078
- create: [() => true],
1079
- delete: [() => true],
1080
- list: [() => true],
1081
- read: [() => true],
1082
- update: [() => true],
1083
- },
1084
- queryFields: ["status"],
1085
- queryFilter: () => ({tenantId: "tenant-1"}),
1086
- },
1087
- routePath: "/filtered",
1088
- });
1089
- const socket = createMockSocket({id: "user1"});
1090
- installRealtimeSocketHandlers(socket);
1091
- await socket.trigger("subscribe:query", {
1092
- collection: "filtered",
1093
- query: {status: "active"},
1094
- });
1095
- const subs = getQuerySubscriptionsForCollection("filtered");
1096
- expect(subs).toHaveLength(1);
1097
- expect(subs[0].query).toEqual({status: "active", tenantId: "tenant-1"});
1098
- });
1099
-
1100
- it("denies query subscriptions when modelRouter queryFilter throws", async () => {
1101
- registerRealtime({
1102
- collectionName: "filtered",
1103
- config: {methods: ["create"], roomStrategy: "model"},
1104
- modelName: "Filtered",
1105
- options: {
1106
- permissions: {
1107
- create: [() => true],
1108
- delete: [() => true],
1109
- list: [() => true],
1110
- read: [() => true],
1111
- update: [() => true],
1112
- },
1113
- queryFields: ["status"],
1114
- queryFilter: () => {
1115
- throw new Error("tenant lookup failed");
1116
- },
1117
- },
1118
- routePath: "/filtered",
1119
- });
1120
- const socket = createMockSocket({id: "user1"});
1121
- installRealtimeSocketHandlers(socket);
1122
- await socket.trigger("subscribe:query", {
1123
- collection: "filtered",
1124
- query: {status: "active"},
1125
- });
1126
- const queryRooms = Array.from(socket.rooms).filter((r) => r.startsWith("query:"));
1127
- expect(queryRooms).toHaveLength(0);
1128
- expect(getQuerySubscriptionsForCollection("filtered")).toHaveLength(0);
1129
- expect(socket.emitted.some((e) => e.event === "query:subscribed")).toBe(false);
1130
- });
1131
-
1132
- it("denies query keys outside the modelRouter queryFields allowlist", async () => {
1133
- registerRealtime({
1134
- collectionName: "charts",
1135
- config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
1136
- modelName: "Chart",
1137
- options: {...permissiveOptions, queryFields: ["status"]},
1138
- routePath: "/charts",
1139
- });
1140
- const socket = createMockSocket({id: "user1"});
1141
- installRealtimeSocketHandlers(socket);
1142
- await socket.trigger("subscribe:query", {
1143
- collection: "charts",
1144
- query: {diagnosis: {$in: ["F32.1"]}},
1145
- });
1146
- await socket.trigger("subscribe:query", {
1147
- collection: "charts",
1148
- query: {$or: [{status: "open"}, {diagnosis: "F41.1"}]},
1149
- });
1150
- await socket.trigger("subscribe:query", {
1151
- collection: "charts",
1152
- query: {"diagnosis.code": "F41", status: "open"},
1153
- });
1154
- expect(getQuerySubscriptionsForCollection("charts")).toHaveLength(0);
1155
- expect(socket.emitted.some((e) => e.event === "query:subscribed")).toBe(false);
1156
-
1157
- await socket.trigger("subscribe:query", {
1158
- collection: "charts",
1159
- query: {$or: [{status: "open"}, {status: {$in: ["closed"]}}]},
1160
- });
1161
- expect(getQuerySubscriptionsForCollection("charts")).toHaveLength(1);
1162
- });
1163
-
1164
- it("ignores malformed query payloads", async () => {
1165
- registerOwnerCollection();
1166
- const socket = createMockSocket({id: "user1"});
1167
- installRealtimeSocketHandlers(socket);
1168
- await socket.trigger("subscribe:query", null);
1169
- await socket.trigger("subscribe:query", {});
1170
- await socket.trigger("subscribe:query", {collection: "todos"});
1171
- await socket.trigger("subscribe:query", {collection: "todos", query: [1, 2, 3]});
1172
- await socket.trigger("subscribe:query", {collection: "todos", query: {$and: [null]}});
1173
- await socket.trigger("subscribe:query", {collection: "todos", query: {$or: "priority"}});
1174
- const queryRooms = Array.from(socket.rooms).filter((r) => r.startsWith("query:"));
1175
- expect(queryRooms).toHaveLength(0);
1176
- });
1177
-
1178
- it("enforces MAX_QUERY_SUBSCRIPTIONS cap", async () => {
1179
- registerOwnerCollection();
1180
- const socket = createMockSocket({admin: true, id: "admin1"});
1181
- installRealtimeSocketHandlers(socket);
1182
- for (let i = 0; i < MAX_QUERY_SUBSCRIPTIONS + 5; i++) {
1183
- await socket.trigger("subscribe:query", {
1184
- collection: "todos",
1185
- query: {priority: i},
1186
- });
1187
- }
1188
- const queryRooms = Array.from(socket.rooms).filter((r) => r.startsWith("query:"));
1189
- expect(queryRooms.length).toBe(MAX_QUERY_SUBSCRIPTIONS);
1190
- });
1191
- });
1192
-
1193
- describe("unsubscribe and counters", () => {
1194
- it("unsubscribe:model frees a slot so further subscriptions are allowed", async () => {
1195
- registerModelCollection();
1196
- registerRealtime({
1197
- collectionName: "other",
1198
- config: {methods: ["create"], roomStrategy: "model"},
1199
- modelName: "Other",
1200
- options: {
1201
- permissions: {
1202
- create: [() => true],
1203
- delete: [() => true],
1204
- list: [() => true],
1205
- read: [() => true],
1206
- update: [() => true],
1207
- },
1208
- },
1209
- routePath: "/other",
1210
- });
1211
- const socket = createMockSocket({id: "user1"});
1212
- installRealtimeSocketHandlers(socket);
1213
- await socket.trigger("subscribe:model", "broadcasts");
1214
- expect(socket.rooms.has("model:broadcasts")).toBe(true);
1215
- await socket.trigger("unsubscribe:model", "broadcasts");
1216
- expect(socket.rooms.has("model:broadcasts")).toBe(false);
1217
- // can re-subscribe
1218
- await socket.trigger("subscribe:model", "other");
1219
- expect(socket.rooms.has("model:other")).toBe(true);
1220
- });
1221
-
1222
- it("unsubscribe:document removes the room and decrements the counter", async () => {
1223
- registerModelCollection();
1224
- const socket = createMockSocket({id: "user1"});
1225
- installRealtimeSocketHandlers(socket);
1226
- await socket.trigger("subscribe:document", {collection: "broadcasts", id: "doc1"});
1227
- expect(socket.rooms.has("document:broadcasts:doc1")).toBe(true);
1228
- await socket.trigger("unsubscribe:document", {collection: "broadcasts", id: "doc1"});
1229
- expect(socket.rooms.has("document:broadcasts:doc1")).toBe(false);
1230
- });
1231
-
1232
- it("unsubscribe:document ignores malformed payloads", async () => {
1233
- const socket = createMockSocket({id: "user1"});
1234
- installRealtimeSocketHandlers(socket);
1235
- // None of these should throw or affect rooms
1236
- await socket.trigger("unsubscribe:document", null);
1237
- await socket.trigger("unsubscribe:document", {});
1238
- await socket.trigger("unsubscribe:document", {collection: "broadcasts"});
1239
- await socket.trigger("unsubscribe:document", {id: "doc1"});
1240
- const docRooms = Array.from(socket.rooms).filter((r) => r.startsWith("document:"));
1241
- expect(docRooms).toHaveLength(0);
1242
- });
1243
-
1244
- it("unsubscribe:query removes the query subscription and leaves the room", async () => {
1245
- registerModelCollection();
1246
- const socket = createMockSocket({id: "user1"});
1247
- installRealtimeSocketHandlers(socket);
1248
- await socket.trigger("subscribe:query", {collection: "broadcasts", query: {priority: 1}});
1249
- const subscribed = socket.emitted.find((e) => e.event === "query:subscribed");
1250
- expect(subscribed).toBeDefined();
1251
- if (!subscribed) {
1252
- throw new Error("Expected a query subscription event");
1253
- }
1254
- const queryId = (subscribed.payload as {queryId: string}).queryId;
1255
- expect(socket.rooms.has(`query:${queryId}`)).toBe(true);
1256
- expect(getQuerySubscriptionsForCollection("broadcasts").length).toBe(1);
1257
- await socket.trigger("unsubscribe:query", {queryId});
1258
- expect(socket.rooms.has(`query:${queryId}`)).toBe(false);
1259
- expect(getQuerySubscriptionsForCollection("broadcasts").length).toBe(0);
1260
- });
1261
-
1262
- it("unsubscribe:query ignores malformed payloads", async () => {
1263
- const socket = createMockSocket({id: "user1"});
1264
- installRealtimeSocketHandlers(socket);
1265
- await socket.trigger("unsubscribe:query", null);
1266
- await socket.trigger("unsubscribe:query", {});
1267
- // No assertion needed — just exercises the no-op path
1268
- });
1269
-
1270
- it("disconnect removes all query subscriptions for the socket", async () => {
1271
- registerOwnerCollection();
1272
- const socket = createMockSocket({admin: true, id: "admin1"});
1273
- installRealtimeSocketHandlers(socket);
1274
- await socket.trigger("subscribe:query", {collection: "todos", query: {priority: 1}});
1275
- await socket.trigger("subscribe:query", {collection: "todos", query: {priority: 2}});
1276
- expect(getQuerySubscriptionsForCollection("todos").length).toBeGreaterThan(0);
1277
- await socket.trigger("disconnect");
1278
- // The mock leaves rooms intact but the store should be cleared for this socket.
1279
- // Other sockets aren't subscribed, so the store should be empty.
1280
- expect(getQuerySubscriptionsForCollection("todos").length).toBe(0);
1281
- });
1282
- });
1283
- });
1284
-
1285
- // ─────────────────────────────────────────────────────────────────────────────
1286
- // serializeDoc — responseHandler fallback for change stream events
1287
- // ─────────────────────────────────────────────────────────────────────────────
1288
-
1289
- describe("serializeDoc (change stream serializer)", () => {
1290
- const makeEntry = (overrides: Partial<RealtimeRegistryEntry> = {}): RealtimeRegistryEntry => ({
1291
- collectionName: "users",
1292
- config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
1293
- modelName: "User",
1294
- options: permissiveOptions,
1295
- routePath: "/users",
1296
- ...overrides,
1297
- });
1298
-
1299
- it("prefers realtimeResponseHandler when provided", async () => {
1300
- const entry = makeEntry({
1301
- config: {
1302
- methods: ["update"],
1303
- realtimeResponseHandler: (doc) => ({customized: doc.name}),
1304
- roomStrategy: "model",
1305
- },
1306
- });
1307
- const result = await serializeDoc(entry, {name: "Alice", secret: "x"}, "update");
1308
- expect(result).toEqual({customized: "Alice"});
1309
- });
1310
-
1311
- it("falls back to modelRouter responseHandler when no realtime handler is set", async () => {
1312
- // Mimics a stripping responseHandler like the example-backend users router.
1313
- const handler: ResponseHandler = async (doc) => {
1314
- const record = {...(doc as unknown as Record<string, unknown>)};
1315
- delete record.hash;
1316
- delete record.salt;
1317
- return record as unknown as JSONValue;
1318
- };
1319
- const responseHandler = mock(handler);
1320
- const entry = makeEntry({options: {...permissiveOptions, responseHandler}});
1321
- const result = await serializeDoc(
1322
- entry,
1323
- {email: "a@b.com", hash: "h", name: "Alice", salt: "s"},
1324
- "update"
1325
- );
1326
- expect(result).toEqual({email: "a@b.com", name: "Alice"});
1327
- expect(responseHandler).toHaveBeenCalled();
1328
- });
1329
-
1330
- it("maps 'delete' method to 'read' when invoking the REST responseHandler", async () => {
1331
- let observedMethod: string | undefined;
1332
- const responseHandler: ResponseHandler = async (doc, method) => {
1333
- observedMethod = method;
1334
- return doc as unknown as JSONValue;
1335
- };
1336
- const entry = makeEntry({options: {...permissiveOptions, responseHandler}});
1337
- await serializeDoc(entry, {name: "Alice"}, "delete");
1338
- expect(observedMethod).toBe("read");
1339
- });
1340
-
1341
- it("re-throws when modelRouter responseHandler throws (event dropped, no leak)", async () => {
1342
- // Critical: do NOT fall back to toJSON, which would skip the handler's sanitization
1343
- // (e.g. stripping hash/salt) and leak the raw document.
1344
- const responseHandler: ResponseHandler = async () => {
1345
- throw new Error("boom");
1346
- };
1347
- const entry = makeEntry({options: {...permissiveOptions, responseHandler}});
1348
- const doc = {hash: "h", name: "Alice", salt: "s", toJSON: () => ({hash: "h", name: "Alice"})};
1349
- await expect(serializeDoc(entry, doc, "update")).rejects.toThrow("boom");
1350
- });
1351
-
1352
- it("re-throws when realtimeResponseHandler throws (event dropped, no leak)", async () => {
1353
- const entry = makeEntry({
1354
- config: {
1355
- methods: ["update"],
1356
- realtimeResponseHandler: () => {
1357
- throw new Error("boom");
1358
- },
1359
- roomStrategy: "model",
1360
- },
1361
- });
1362
- const doc = {name: "Alice", toJSON: () => ({name: "Alice-json"})};
1363
- await expect(serializeDoc(entry, doc, "update")).rejects.toThrow("boom");
1364
- });
1365
-
1366
- it("returns toJSON output when no handlers are configured", async () => {
1367
- const entry = makeEntry();
1368
- const doc = {name: "Alice", toJSON: () => ({id: "1", name: "Alice"})};
1369
- const result = await serializeDoc(entry, doc, "create");
1370
- expect(result).toEqual({id: "1", name: "Alice"});
1371
- });
1372
-
1373
- it("returns raw doc when toJSON is missing and no handlers configured", async () => {
1374
- const entry = makeEntry();
1375
- const result = await serializeDoc(entry, {name: "Alice"}, "create");
1376
- expect(result).toEqual({name: "Alice"});
433
+ it("joins user-specific and authenticated rooms when token has userId", async () => {
434
+ const socket = createMockSocket({id: "user1"});
435
+ installRealtimeSocketHandlers(socket);
436
+ await flushJoins();
437
+ expect(socket.rooms.has("user:user1")).toBe(true);
438
+ expect(socket.rooms.has("authenticated")).toBe(true);
439
+ });
440
+
441
+ it("joins admin room for admin tokens", async () => {
442
+ const socket = createMockSocket({admin: true, id: "admin1"});
443
+ installRealtimeSocketHandlers(socket);
444
+ await flushJoins();
445
+ expect(socket.rooms.has("admin")).toBe(true);
446
+ });
447
+
448
+ it("does not join admin room for non-admin tokens", async () => {
449
+ const socket = createMockSocket({admin: false, id: "user1"});
450
+ installRealtimeSocketHandlers(socket);
451
+ await flushJoins();
452
+ expect(socket.rooms.has("admin")).toBe(false);
453
+ });
454
+
455
+ it("joins no rooms when the token has no user id", async () => {
456
+ const socket = createMockSocket();
457
+ installRealtimeSocketHandlers(socket);
458
+ await flushJoins();
459
+ expect(socket.rooms.size).toBe(0);
460
+ });
461
+
462
+ it("installs no legacy RTK subscription handlers", () => {
463
+ const socket = createMockSocket({id: "user1"});
464
+ installRealtimeSocketHandlers(socket);
465
+ for (const event of [
466
+ "subscribe:model",
467
+ "unsubscribe:model",
468
+ "subscribe:document",
469
+ "unsubscribe:document",
470
+ "subscribe:query",
471
+ "unsubscribe:query",
472
+ ]) {
473
+ expect(socket.listeners.has(event)).toBe(false);
474
+ }
475
+ expect([...socket.listeners.keys()]).toEqual(["disconnect"]);
1377
476
  });
1378
477
 
1379
- it("adds id from _id when handlers omit it (change stream raw document shape)", async () => {
1380
- const entry = makeEntry();
1381
- const result = await serializeDoc(
1382
- entry,
1383
- {_id: "507f1f77bcf86cd799439011", name: "Alice"},
1384
- "create"
1385
- );
1386
- expect(result).toEqual({
1387
- _id: "507f1f77bcf86cd799439011",
1388
- id: "507f1f77bcf86cd799439011",
1389
- name: "Alice",
1390
- });
478
+ it("logs disconnects", async () => {
479
+ const logInfo = mock((_msg: string): void => {});
480
+ const socket = createMockSocket({id: "user1"});
481
+ installRealtimeSocketHandlers(socket, {logInfo});
482
+ await socket.trigger("disconnect");
483
+ expect(logInfo).toHaveBeenCalledWith("[realtime] User user1 disconnected");
1391
484
  });
1392
485
  });
1393
486
 
@@ -1410,27 +503,12 @@ describe("mapOperationType", () => {
1410
503
  expect(mapOperationType("replace", asChange({}))).toBe("update");
1411
504
  });
1412
505
 
1413
- it("maps update with deleted=true to delete (soft delete) when delete is enabled", () => {
506
+ it("maps update with deleted=true to delete (soft delete)", () => {
1414
507
  expect(
1415
- mapOperationType("update", asChange({updateDescription: {updatedFields: {deleted: true}}}), [
1416
- "create",
1417
- "update",
1418
- "delete",
1419
- ])
508
+ mapOperationType("update", asChange({updateDescription: {updatedFields: {deleted: true}}}))
1420
509
  ).toBe("delete");
1421
510
  });
1422
511
 
1423
- it("keeps soft delete as update when delete is NOT in the enabled methods", () => {
1424
- // A model configured with methods: ["create", "update"] must still see
1425
- // soft-delete events as updates — otherwise they'd be silently dropped.
1426
- expect(
1427
- mapOperationType("update", asChange({updateDescription: {updatedFields: {deleted: true}}}), [
1428
- "create",
1429
- "update",
1430
- ])
1431
- ).toBe("update");
1432
- });
1433
-
1434
512
  it("maps delete to delete", () => {
1435
513
  expect(mapOperationType("delete", asChange({}))).toBe("delete");
1436
514
  });
@@ -1441,72 +519,11 @@ describe("mapOperationType", () => {
1441
519
  });
1442
520
  });
1443
521
 
1444
- describe("resolveRooms", () => {
1445
- const baseEntry: RealtimeRegistryEntry = {
1446
- collectionName: "todos",
1447
- config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
1448
- modelName: "Todo",
1449
- options: permissiveOptions,
1450
- routePath: "/todos",
1451
- };
1452
-
1453
- it("returns user-specific room for owner strategy with ownerId", () => {
1454
- const entry = {...baseEntry, config: {...baseEntry.config, roomStrategy: "owner" as const}};
1455
- const rooms = resolveRooms(entry, {ownerId: "user-1"}, "create");
1456
- expect(rooms).toEqual(["user:user-1"]);
1457
- });
1458
-
1459
- it("converts ObjectId-like ownerId to string", () => {
1460
- const entry = {...baseEntry, config: {...baseEntry.config, roomStrategy: "owner" as const}};
1461
- const ownerId = {toString: (): string => "owner-from-obj"};
1462
- const rooms = resolveRooms(entry, {ownerId}, "create");
1463
- expect(rooms).toEqual(["user:owner-from-obj"]);
1464
- });
1465
-
1466
- it("falls back to model room when owner strategy has no ownerId", () => {
1467
- const entry = {...baseEntry, config: {...baseEntry.config, roomStrategy: "owner" as const}};
1468
- const rooms = resolveRooms(entry, {}, "create");
1469
- expect(rooms).toEqual(["model:todos"]);
1470
- });
1471
-
1472
- it("returns model room for model strategy", () => {
1473
- const entry = {...baseEntry, config: {...baseEntry.config, roomStrategy: "model" as const}};
1474
- const rooms = resolveRooms(entry, {}, "create");
1475
- expect(rooms).toEqual(["model:todos"]);
1476
- });
1477
-
1478
- it("returns authenticated room for broadcast strategy", () => {
1479
- const entry = {...baseEntry, config: {...baseEntry.config, roomStrategy: "broadcast" as const}};
1480
- const rooms = resolveRooms(entry, {}, "create");
1481
- expect(rooms).toEqual(["authenticated"]);
1482
- });
1483
-
1484
- it("defaults to model room for unknown strategy", () => {
1485
- const entry = {
1486
- ...baseEntry,
1487
- config: {
1488
- ...baseEntry.config,
1489
- roomStrategy: "unknown" as unknown as RealtimeConfig["roomStrategy"],
1490
- },
1491
- };
1492
- const rooms = resolveRooms(entry, {}, "create");
1493
- expect(rooms).toEqual(["model:todos"]);
1494
- });
1495
-
1496
- it("invokes custom function room resolver", () => {
1497
- const entry: RealtimeRegistryEntry = {
1498
- ...baseEntry,
1499
- config: {
1500
- ...baseEntry.config,
1501
- roomStrategy: (doc, method): string[] => [`custom:${method}:${String(doc.id)}`],
1502
- },
1503
- };
1504
- const rooms = resolveRooms(entry, {id: "42"}, "update");
1505
- expect(rooms).toEqual(["custom:update:42"]);
1506
- });
1507
- });
522
+ // ─────────────────────────────────────────────────────────────────────────────
523
+ // emitPayloadToAuthorizedRoom — per-socket authorization for sync:delta fan-out
524
+ // ─────────────────────────────────────────────────────────────────────────────
1508
525
 
1509
- describe("emitToDocumentAndQueryRooms", () => {
526
+ describe("emitPayloadToAuthorizedRoom", () => {
1510
527
  const makeIo = (): {
1511
528
  addSocketToRoom: (room: string, decodedToken?: DecodedRealtimeToken) => void;
1512
529
  emissions: Array<{room: string; event: string; payload: unknown}>;
@@ -1539,373 +556,91 @@ describe("emitToDocumentAndQueryRooms", () => {
1539
556
  adapter: {rooms: roomSockets},
1540
557
  sockets,
1541
558
  },
1542
- to: (room: string) => ({
1543
- emit: (event: string, payload: unknown): void => {
1544
- emissions.push({event, payload, room});
1545
- },
1546
- }),
1547
559
  } as unknown as Server;
1548
560
  return {addSocketToRoom, emissions, io};
1549
561
  };
1550
562
 
1551
- beforeEach(() => {
1552
- clearQueryStore();
1553
- });
563
+ const ownerReadEntry: AuthorizedEmitEntry = {
564
+ collectionTag: "todos",
565
+ modelName: "Todo",
566
+ options: {
567
+ permissions: {
568
+ read: [
569
+ (_method, user?: {admin?: boolean; id?: string}, obj?: unknown) =>
570
+ user?.admin === true || user?.id === (obj as {ownerId?: string} | undefined)?.ownerId,
571
+ ],
572
+ },
573
+ },
574
+ };
1554
575
 
1555
576
  afterEach(() => {
1556
- clearQueryStore();
577
+ clearAdminBroadcastScopes();
1557
578
  });
1558
579
 
1559
- it("emits to the document room", async () => {
1560
- const {emissions, io} = makeIo();
1561
- const event: RealtimeEvent = {
1562
- collection: "todos",
1563
- id: "doc-1",
1564
- method: "update",
1565
- model: "Todo",
1566
- timestamp: 1,
1567
- };
1568
- await emitToDocumentAndQueryRooms(io, "todos", event, {}, () => {});
1569
- expect(emissions.some((e) => e.room === "document:todos:doc-1")).toBe(true);
580
+ it("emits a per-socket payload only to sockets that can read the document", async () => {
581
+ const room = "sync:todos|owner:owner-1";
582
+ const {addSocketToRoom, emissions, io} = makeIo();
583
+ addSocketToRoom(room, {id: "owner-1"});
584
+ addSocketToRoom(room, {id: "other-user"});
585
+
586
+ await emitPayloadToAuthorizedRoom({
587
+ buildPayload: (user) => ({id: "todo-1", visibleTo: user?.id}),
588
+ entry: ownerReadEntry,
589
+ eventName: "sync:delta",
590
+ fullDocument: {_id: "todo-1", ownerId: "owner-1"},
591
+ io,
592
+ logDebug: () => {},
593
+ room,
594
+ });
595
+
596
+ expect(emissions).toEqual([
597
+ {event: "sync:delta", payload: {id: "todo-1", visibleTo: "owner-1"}, room},
598
+ ]);
1570
599
  });
1571
600
 
1572
- it("keeps fanning out to later query rooms when one subscription fails", async () => {
1573
- addQuerySubscription("socket-a", "todos", {priority: 1}, "failing");
1574
- const healthyId = computeQueryId("todos", {priority: 1});
1575
- addQuerySubscription("socket-b", "todos", {priority: 1}, healthyId);
601
+ it("continues emitting to other sockets when building one payload fails", async () => {
602
+ const room = "sync:todos|broadcast";
1576
603
  const {addSocketToRoom, emissions, io} = makeIo();
1577
- addSocketToRoom(`query:${healthyId}`);
1578
- const throwingIo = {
1579
- ...io,
1580
- to: (room: string) => {
1581
- if (room === "query:failing") {
1582
- throw new Error("emit failed");
604
+ addSocketToRoom(room, {id: "bad-user"});
605
+ addSocketToRoom(room, {id: "good-user"});
606
+
607
+ await emitPayloadToAuthorizedRoom({
608
+ buildPayload: (user) => {
609
+ if (user?.id === "bad-user") {
610
+ throw new Error("cannot serialize for bad user");
1583
611
  }
1584
- return io.to(room);
612
+ return {visibleTo: user?.id};
1585
613
  },
1586
- } as unknown as Server;
1587
- const event: RealtimeEvent = {
1588
- collection: "todos",
1589
- id: "doc-1",
1590
- method: "create",
1591
- model: "Todo",
1592
- timestamp: 1,
1593
- };
1594
-
1595
- await emitToDocumentAndQueryRooms(
1596
- throwingIo,
1597
- "todos",
1598
- event,
1599
- {name: "x", priority: 1},
1600
- () => {}
1601
- );
614
+ entry: {...ownerReadEntry, options: {permissions: {read: [() => true]}}},
615
+ eventName: "sync:delta",
616
+ fullDocument: {_id: "todo-1"},
617
+ io,
618
+ logDebug: () => {},
619
+ room,
620
+ });
1602
621
 
1603
- expect(emissions.some((e) => e.room === `query:${healthyId}`)).toBe(true);
622
+ expect(emissions).toEqual([{event: "sync:delta", payload: {visibleTo: "good-user"}, room}]);
1604
623
  });
1605
624
 
1606
- it("forwards hard deletes to every query room for non-owner strategies", async () => {
1607
- const queryId = computeQueryId("todos", {priority: 1});
1608
- addQuerySubscription("socket-a", "todos", {priority: 1}, queryId);
625
+ it("allows admin broadcast sockets without running product read permissions", async () => {
1609
626
  const {addSocketToRoom, emissions, io} = makeIo();
1610
- addSocketToRoom(`query:${queryId}`);
1611
- const event: RealtimeEvent = {
1612
- collection: "todos",
1613
- id: "doc-1",
1614
- method: "delete",
1615
- model: "Todo",
1616
- timestamp: 1,
1617
- };
1618
- const entry: RealtimeRegistryEntry = {
1619
- collectionName: "todos",
1620
- config: {methods: ["delete"], roomStrategy: "model"},
1621
- modelName: "Todo",
1622
- options: permissiveOptions,
1623
- routePath: "/todos",
1624
- };
1625
- await emitToDocumentAndQueryRooms(io, "todos", event, undefined, () => {}, entry);
1626
- expect(emissions.some((e) => e.room === `query:${queryId}` && e.event === "sync")).toBe(true);
1627
- });
627
+ addSocketToRoom("sync:todos|admin", {admin: true, id: "admin-user"});
628
+ registerAdminBroadcastScope("Todo", {
629
+ listPermissions: [() => true],
630
+ readPermissions: [() => true],
631
+ });
1628
632
 
1629
- it("does NOT forward hard deletes to query rooms for owner-strategy collections", async () => {
1630
- const queryId = computeQueryId("todos", {ownerId: "user-1"});
1631
- addQuerySubscription("socket-a", "todos", {ownerId: "user-1"}, queryId);
1632
- const {addSocketToRoom, emissions, io} = makeIo();
1633
- addSocketToRoom("document:todos:doc-1");
1634
- addSocketToRoom(`query:${queryId}`);
1635
- const event: RealtimeEvent = {
1636
- collection: "todos",
1637
- id: "doc-1",
1638
- method: "delete",
1639
- model: "Todo",
1640
- timestamp: 1,
1641
- };
1642
- const entry: RealtimeRegistryEntry = {
1643
- collectionName: "todos",
1644
- config: {methods: ["delete"], roomStrategy: "owner"},
1645
- modelName: "Todo",
1646
- options: permissiveOptions,
1647
- routePath: "/todos",
1648
- };
1649
- await emitToDocumentAndQueryRooms(io, "todos", event, undefined, () => {}, entry);
1650
- // Document room still receives the event, but query rooms must not — otherwise users
1651
- // would see deletes for docs they don't own.
1652
- expect(emissions.some((e) => e.room === `query:${queryId}`)).toBe(false);
1653
- expect(emissions.some((e) => e.room === "document:todos:doc-1")).toBe(true);
1654
- });
1655
-
1656
- it("forwards soft deletes only to query rooms whose filter the document satisfies", async () => {
1657
- const matchingQueryId = computeQueryId("todos", {priority: 1});
1658
- const nonMatchingQueryId = computeQueryId("todos", {priority: 9});
1659
- addQuerySubscription("socket-a", "todos", {priority: 1}, matchingQueryId);
1660
- addQuerySubscription("socket-b", "todos", {priority: 9}, nonMatchingQueryId);
1661
- const {addSocketToRoom, emissions, io} = makeIo();
1662
- addSocketToRoom(`query:${matchingQueryId}`);
1663
- addSocketToRoom(`query:${nonMatchingQueryId}`);
1664
- const event: RealtimeEvent = {
1665
- collection: "todos",
1666
- data: {deleted: true, priority: 1},
1667
- id: "doc-1",
1668
- method: "delete",
1669
- model: "Todo",
1670
- timestamp: 1,
1671
- };
1672
- const entry: RealtimeRegistryEntry = {
1673
- collectionName: "todos",
1674
- config: {methods: ["delete"], roomStrategy: "owner"},
1675
- modelName: "Todo",
1676
- options: permissiveOptions,
1677
- routePath: "/todos",
1678
- };
1679
- await emitToDocumentAndQueryRooms(
1680
- io,
1681
- "todos",
1682
- event,
1683
- {deleted: true, priority: 1},
1684
- () => {},
1685
- entry
1686
- );
1687
- expect(emissions.some((e) => e.room === `query:${matchingQueryId}`)).toBe(true);
1688
- expect(emissions.some((e) => e.room === `query:${nonMatchingQueryId}`)).toBe(false);
1689
- });
1690
-
1691
- it("skips matching when fullDocument is missing on non-delete events", async () => {
1692
- const queryId = computeQueryId("todos", {priority: 1});
1693
- addQuerySubscription("socket-a", "todos", {priority: 1}, queryId);
1694
- const {emissions, io} = makeIo();
1695
- const event: RealtimeEvent = {
1696
- collection: "todos",
1697
- id: "doc-1",
1698
- method: "create",
1699
- model: "Todo",
1700
- timestamp: 1,
1701
- };
1702
- await emitToDocumentAndQueryRooms(io, "todos", event, undefined, () => {});
1703
- expect(emissions.some((e) => e.room === `query:${queryId}`)).toBe(false);
1704
- });
1705
-
1706
- it("emits create events to query rooms when the doc matches", async () => {
1707
- const queryId = computeQueryId("todos", {priority: 1});
1708
- addQuerySubscription("socket-a", "todos", {priority: 1}, queryId);
1709
- const {emissions, io} = makeIo();
1710
- const event: RealtimeEvent = {
1711
- collection: "todos",
1712
- id: "doc-1",
1713
- method: "create",
1714
- model: "Todo",
1715
- timestamp: 1,
1716
- };
1717
- await emitToDocumentAndQueryRooms(io, "todos", event, {priority: 1}, () => {});
1718
- const queryEmissions = emissions.filter((e) => e.room === `query:${queryId}`);
1719
- expect(queryEmissions.length).toBe(1);
1720
- expect(queryEmissions[0].payload).toMatchObject({method: "create"});
1721
- });
1722
-
1723
- it("does not emit create events to query rooms when the doc does not match", async () => {
1724
- const queryId = computeQueryId("todos", {priority: 1});
1725
- addQuerySubscription("socket-a", "todos", {priority: 1}, queryId);
1726
- const {emissions, io} = makeIo();
1727
- const event: RealtimeEvent = {
1728
- collection: "todos",
1729
- id: "doc-1",
1730
- method: "create",
1731
- model: "Todo",
1732
- timestamp: 1,
1733
- };
1734
- await emitToDocumentAndQueryRooms(io, "todos", event, {priority: 9}, () => {});
1735
- expect(emissions.some((e) => e.room === `query:${queryId}`)).toBe(false);
1736
- });
1737
-
1738
- it("emits update as-is when the document still matches the query", async () => {
1739
- const queryId = computeQueryId("todos", {priority: 1});
1740
- addQuerySubscription("socket-a", "todos", {priority: 1}, queryId);
1741
- const {emissions, io} = makeIo();
1742
- const event: RealtimeEvent = {
1743
- collection: "todos",
1744
- id: "doc-1",
1745
- method: "update",
1746
- model: "Todo",
1747
- timestamp: 1,
1748
- };
1749
- await emitToDocumentAndQueryRooms(io, "todos", event, {priority: 1}, () => {});
1750
- const queryEmissions = emissions.filter((e) => e.room === `query:${queryId}`);
1751
- expect(queryEmissions.length).toBe(1);
1752
- expect(queryEmissions[0].payload).toMatchObject({method: "update"});
1753
- });
1754
-
1755
- it("converts updates that no longer match into delete events for the query", async () => {
1756
- const queryId = computeQueryId("todos", {priority: 1});
1757
- addQuerySubscription("socket-a", "todos", {priority: 1}, queryId);
1758
- const {emissions, io} = makeIo();
1759
- const event: RealtimeEvent = {
1760
- collection: "todos",
1761
- id: "doc-1",
1762
- method: "update",
1763
- model: "Todo",
1764
- timestamp: 1,
1765
- };
1766
- await emitToDocumentAndQueryRooms(io, "todos", event, {priority: 9}, () => {});
1767
- const queryEmissions = emissions.filter((e) => e.room === `query:${queryId}`);
1768
- expect(queryEmissions.length).toBe(1);
1769
- expect(queryEmissions[0].payload).toMatchObject({method: "delete"});
1770
- });
1771
-
1772
- it("filters socket emissions by object read permission and responseHandler", async () => {
1773
- const {addSocketToRoom, emissions, io} = makeIo();
1774
- addSocketToRoom("model:todos", {id: "owner-1"});
1775
- addSocketToRoom("model:todos", {id: "other-user"});
1776
- const entry: RealtimeRegistryEntry = {
1777
- collectionName: "todos",
1778
- config: {methods: ["update"], roomStrategy: "model"},
1779
- modelName: "Todo",
1780
- options: {
1781
- permissions: {
1782
- create: [() => true],
1783
- delete: [() => true],
1784
- list: [() => true],
1785
- read: [
1786
- (_method: string, user?: {admin?: boolean; id?: string}, obj?: unknown) =>
1787
- user?.admin === true || user?.id === (obj as {ownerId?: string} | undefined)?.ownerId,
1788
- ],
1789
- update: [() => true],
1790
- },
1791
- responseHandler: async (doc, _method, req) => {
1792
- const record = doc as unknown as {_id?: unknown; title?: unknown};
1793
- return {
1794
- id: record._id,
1795
- title: record.title,
1796
- visibleTo: req.user?.id,
1797
- } as unknown as JSONValue;
1798
- },
1799
- },
1800
- routePath: "/todos",
1801
- };
1802
-
1803
- await emitToAuthorizedRoom(
633
+ await emitPayloadToAuthorizedRoom({
634
+ buildPayload: () => ({id: "todo-1"}),
635
+ entry: {...ownerReadEntry, options: {permissions: {read: [() => false]}}},
636
+ eventName: "sync:delta",
637
+ fullDocument: {_id: "todo-1", ownerId: "owner-1"},
1804
638
  io,
1805
- "model:todos",
1806
- {
1807
- collection: "todos",
1808
- id: "todo-1",
1809
- method: "update",
1810
- model: "Todo",
1811
- timestamp: 1,
1812
- },
1813
- entry,
1814
- {_id: "todo-1", ownerId: "owner-1", secret: "hidden", title: "Visible"},
1815
- () => {}
1816
- );
1817
-
1818
- expect(emissions).toHaveLength(1);
1819
- expect(emissions[0].payload).toMatchObject({
1820
- data: {id: "todo-1", title: "Visible", visibleTo: "owner-1"},
639
+ logDebug: () => {},
640
+ room: "sync:todos|admin",
1821
641
  });
1822
- });
1823
-
1824
- it("continues emitting to other sockets when per-socket serialization fails", async () => {
1825
- const {addSocketToRoom, emissions, io} = makeIo();
1826
- addSocketToRoom("model:todos", {id: "bad-user"});
1827
- addSocketToRoom("model:todos", {id: "good-user"});
1828
- const entry: RealtimeRegistryEntry = {
1829
- collectionName: "todos",
1830
- config: {methods: ["update"], roomStrategy: "model"},
1831
- modelName: "Todo",
1832
- options: {
1833
- permissions: {
1834
- create: [() => true],
1835
- delete: [() => true],
1836
- list: [() => true],
1837
- read: [() => true],
1838
- update: [() => true],
1839
- },
1840
- responseHandler: async (doc, _method, req) => {
1841
- if (req.user?.id === "bad-user") {
1842
- throw new Error("cannot serialize for bad user");
1843
- }
1844
-
1845
- return {
1846
- ...(doc as unknown as Record<string, unknown>),
1847
- visibleTo: req.user?.id,
1848
- } as unknown as JSONValue;
1849
- },
1850
- },
1851
- routePath: "/todos",
1852
- };
1853
-
1854
- await emitToAuthorizedRoom(
1855
- io,
1856
- "model:todos",
1857
- {
1858
- collection: "todos",
1859
- id: "todo-1",
1860
- method: "update",
1861
- model: "Todo",
1862
- timestamp: 1,
1863
- },
1864
- entry,
1865
- {_id: "todo-1", title: "Visible"},
1866
- () => {}
1867
- );
1868
642
 
1869
643
  expect(emissions).toHaveLength(1);
1870
- expect(emissions[0].payload).toMatchObject({
1871
- data: {id: "todo-1", title: "Visible", visibleTo: "good-user"},
1872
- });
1873
- });
1874
-
1875
- it("allows admin broadcast sockets without running product read permissions", async () => {
1876
- const {addSocketToRoom, emissions, io} = makeIo();
1877
- addSocketToRoom("sync:todos|admin", {admin: true, id: "admin-user"});
1878
- registerAdminBroadcastScope("Todo", {
1879
- listPermissions: [() => true],
1880
- readPermissions: [() => true],
1881
- });
1882
- const entry: RealtimeRegistryEntry = {
1883
- collectionName: "todos",
1884
- config: {methods: ["update"], roomStrategy: "model"},
1885
- modelName: "Todo",
1886
- options: {
1887
- ...permissiveOptions,
1888
- permissions: {...permissiveOptions.permissions, read: [() => false]},
1889
- },
1890
- routePath: "/todos",
1891
- };
1892
-
1893
- await emitToAuthorizedRoom(
1894
- io,
1895
- "sync:todos|admin",
1896
- {
1897
- collection: "todos",
1898
- id: "todo-1",
1899
- method: "update",
1900
- model: "Todo",
1901
- timestamp: 1,
1902
- },
1903
- entry,
1904
- {_id: "todo-1", ownerId: "owner-1"},
1905
- () => {}
1906
- );
1907
-
1908
- assert.lengthOf(emissions, 1);
1909
644
  });
1910
645
 
1911
646
  it("does not emit admin broadcast documents denied by the admin scope", async () => {
@@ -1915,245 +650,39 @@ describe("emitToDocumentAndQueryRooms", () => {
1915
650
  listPermissions: [() => false],
1916
651
  readPermissions: [() => true],
1917
652
  });
1918
- const entry: RealtimeRegistryEntry = {
1919
- collectionName: "todos",
1920
- config: {methods: ["update"], roomStrategy: "model"},
1921
- modelName: "Todo",
1922
- options: permissiveOptions,
1923
- routePath: "/todos",
1924
- };
1925
653
 
1926
- await emitToAuthorizedRoom(
654
+ await emitPayloadToAuthorizedRoom({
655
+ buildPayload: () => ({id: "todo-1"}),
656
+ entry: {...ownerReadEntry, options: {permissions: {read: [() => true]}}},
657
+ eventName: "sync:delta",
658
+ fullDocument: {_id: "todo-1", ownerId: "owner-1"},
1927
659
  io,
1928
- "sync:todos|admin",
1929
- {
1930
- collection: "todos",
1931
- id: "todo-1",
1932
- method: "update",
1933
- model: "Todo",
1934
- timestamp: 1,
1935
- },
1936
- entry,
1937
- {_id: "todo-1", ownerId: "owner-1"},
1938
- () => {}
1939
- );
660
+ logDebug: () => {},
661
+ room: "sync:todos|admin",
662
+ });
1940
663
 
1941
- assert.isEmpty(emissions);
664
+ expect(emissions).toEqual([]);
1942
665
  });
1943
666
 
1944
- it("does not emit hard delete metadata when read permission requires an object owner", async () => {
667
+ it("fails closed without a document when read permission requires an object owner", async () => {
668
+ const room = "sync:todos|owner:owner-1";
1945
669
  const {addSocketToRoom, emissions, io} = makeIo();
1946
- addSocketToRoom("model:todos", {id: "other-user"});
1947
- const entry: RealtimeRegistryEntry = {
1948
- collectionName: "todos",
1949
- config: {methods: ["delete"], roomStrategy: "model"},
1950
- modelName: "Todo",
1951
- options: {
1952
- permissions: {
1953
- create: [() => true],
1954
- delete: [() => true],
1955
- list: [() => true],
1956
- read: [
1957
- (_method: string, user?: {admin?: boolean; id?: string}, obj?: unknown) =>
1958
- user?.admin === true || user?.id === (obj as {ownerId?: string} | undefined)?.ownerId,
1959
- ],
1960
- update: [() => true],
1961
- },
1962
- },
1963
- routePath: "/todos",
1964
- };
670
+ addSocketToRoom(room, {id: "other-user"});
1965
671
 
1966
- await emitToAuthorizedRoom(
672
+ await emitPayloadToAuthorizedRoom({
673
+ buildPayload: () => ({deleted: true, id: "todo-1"}),
674
+ entry: ownerReadEntry,
675
+ eventName: "sync:delta",
676
+ fullDocument: undefined,
1967
677
  io,
1968
- "model:todos",
1969
- {
1970
- collection: "todos",
1971
- id: "todo-1",
1972
- method: "delete",
1973
- model: "Todo",
1974
- timestamp: 1,
1975
- },
1976
- entry,
1977
- undefined,
1978
- () => {}
1979
- );
1980
-
1981
- expect(emissions).toEqual([]);
1982
- });
1983
-
1984
- describe("query room fanout with a registry entry", () => {
1985
- const modelEntry: RealtimeRegistryEntry = {
1986
- collectionName: "todos",
1987
- config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
1988
- modelName: "Todo",
1989
- options: {
1990
- permissions: {
1991
- create: [() => true],
1992
- delete: [() => true],
1993
- list: [() => true],
1994
- read: [() => true],
1995
- update: [() => true],
1996
- },
1997
- },
1998
- routePath: "/todos",
1999
- };
2000
-
2001
- const makeEvent = (method: RealtimeEvent["method"]): RealtimeEvent => ({
2002
- collection: "todos",
2003
- id: "doc-1",
2004
- method,
2005
- model: "Todo",
2006
- timestamp: 1,
678
+ logDebug: () => {},
679
+ room,
2007
680
  });
2008
681
 
2009
- it("emits creates through the permission-filtered path", async () => {
2010
- const queryId = computeQueryId("todos", {priority: 1});
2011
- addQuerySubscription("socket-a", "todos", {priority: 1}, queryId);
2012
- const {addSocketToRoom, emissions, io} = makeIo();
2013
- addSocketToRoom(`query:${queryId}`, {id: "user-1"});
2014
-
2015
- await emitToDocumentAndQueryRooms(
2016
- io,
2017
- "todos",
2018
- makeEvent("create"),
2019
- {priority: 1},
2020
- () => {},
2021
- modelEntry
2022
- );
2023
-
2024
- const queryEmissions = emissions.filter((e) => e.room === `query:${queryId}`);
2025
- expect(queryEmissions).toHaveLength(1);
2026
- expect(queryEmissions[0].payload).toMatchObject({data: {priority: 1}, method: "create"});
2027
- });
2028
-
2029
- it("emits updates through the permission-filtered path when the doc still matches", async () => {
2030
- const queryId = computeQueryId("todos", {priority: 1});
2031
- addQuerySubscription("socket-a", "todos", {priority: 1}, queryId);
2032
- const {addSocketToRoom, emissions, io} = makeIo();
2033
- addSocketToRoom(`query:${queryId}`, {id: "user-1"});
2034
-
2035
- await emitToDocumentAndQueryRooms(
2036
- io,
2037
- "todos",
2038
- makeEvent("update"),
2039
- {priority: 1},
2040
- () => {},
2041
- modelEntry
2042
- );
2043
-
2044
- const queryEmissions = emissions.filter((e) => e.room === `query:${queryId}`);
2045
- expect(queryEmissions).toHaveLength(1);
2046
- expect(queryEmissions[0].payload).toMatchObject({method: "update"});
2047
- });
2048
-
2049
- it("converts non-matching updates into deletes through the permission-filtered path", async () => {
2050
- const queryId = computeQueryId("todos", {priority: 1});
2051
- addQuerySubscription("socket-a", "todos", {priority: 1}, queryId);
2052
- const {addSocketToRoom, emissions, io} = makeIo();
2053
- addSocketToRoom(`query:${queryId}`, {id: "user-1"});
2054
-
2055
- await emitToDocumentAndQueryRooms(
2056
- io,
2057
- "todos",
2058
- makeEvent("update"),
2059
- {priority: 9},
2060
- () => {},
2061
- modelEntry
2062
- );
2063
-
2064
- const queryEmissions = emissions.filter((e) => e.room === `query:${queryId}`);
2065
- expect(queryEmissions).toHaveLength(1);
2066
- expect(queryEmissions[0].payload).toMatchObject({method: "delete"});
2067
- });
2068
-
2069
- it("matches query rooms against the recipient's RBAC-masked document", async () => {
2070
- const fieldMaskRequests: unknown[] = [];
2071
- const rbacEntry: RealtimeRegistryEntry = {
2072
- ...modelEntry,
2073
- options: {
2074
- ...modelEntry.options,
2075
- access: {resource: "chart"},
2076
- accessControl: {
2077
- can: async () => ({allowed: true}),
2078
- fieldMask: async (args: unknown) => {
2079
- fieldMaskRequests.push(args);
2080
- return {omit: ["diagnosis"], read: "*", write: "*"};
2081
- },
2082
- statements: {chart: ["read", "list"]},
2083
- } as unknown as NonNullable<RealtimeRegistryEntry["options"]["accessControl"]>,
2084
- },
2085
- };
2086
- const matchingId = computeQueryId("todos", {diagnosis: "F32.1"});
2087
- const otherId = computeQueryId("todos", {diagnosis: "F41.1"});
2088
- addQuerySubscription("socket-a", "todos", {diagnosis: "F32.1"}, matchingId);
2089
- addQuerySubscription("socket-b", "todos", {diagnosis: "F41.1"}, otherId);
2090
- const {addSocketToRoom, emissions, io} = makeIo();
2091
- addSocketToRoom(`query:${matchingId}`, {id: "scheduler"});
2092
- addSocketToRoom(`query:${otherId}`, {id: "scheduler"});
2093
-
2094
- await emitToDocumentAndQueryRooms(
2095
- io,
2096
- "todos",
2097
- makeEvent("update"),
2098
- {_id: "doc-1", diagnosis: "F32.1", status: "open"},
2099
- () => {},
2100
- rbacEntry
2101
- );
2102
-
2103
- const methodFor = (queryId: string): unknown =>
2104
- (emissions.find((e) => e.room === `query:${queryId}`)?.payload as {method?: string})
2105
- ?.method;
2106
- // The hidden value must not decide which event each room receives.
2107
- expect(methodFor(matchingId)).toBe(methodFor(otherId));
2108
- expect(methodFor(matchingId)).toBe("delete");
2109
- for (const emission of emissions) {
2110
- expect((emission.payload as {data?: Record<string, unknown>}).data).not.toHaveProperty(
2111
- "diagnosis"
2112
- );
2113
- }
2114
- expect(fieldMaskRequests.length).toBeGreaterThan(0);
2115
- });
2116
-
2117
- it("skips query rooms whose subscribers cannot read the document", async () => {
2118
- const queryId = computeQueryId("todos", {priority: 1});
2119
- addQuerySubscription("socket-a", "todos", {priority: 1}, queryId);
2120
- const {addSocketToRoom, emissions, io} = makeIo();
2121
- addSocketToRoom(`query:${queryId}`, {id: "other-user"});
2122
- const ownerEntry: RealtimeRegistryEntry = {
2123
- ...modelEntry,
2124
- options: {
2125
- permissions: {
2126
- create: [() => true],
2127
- delete: [() => true],
2128
- list: [() => true],
2129
- read: [
2130
- (_method, user?: {admin?: boolean; id?: string}, obj?: unknown) =>
2131
- user?.admin === true ||
2132
- user?.id === (obj as {ownerId?: string} | undefined)?.ownerId,
2133
- ],
2134
- update: [() => true],
2135
- },
2136
- },
2137
- };
2138
-
2139
- await emitToDocumentAndQueryRooms(
2140
- io,
2141
- "todos",
2142
- makeEvent("create"),
2143
- {ownerId: "user-1", priority: 1},
2144
- () => {},
2145
- ownerEntry
2146
- );
2147
-
2148
- expect(emissions.some((e) => e.room === `query:${queryId}`)).toBe(false);
2149
- });
682
+ expect(emissions).toEqual([]);
2150
683
  });
2151
684
  });
2152
685
 
2153
- // ─────────────────────────────────────────────────────────────────────────────
2154
- // redactCredentials — Redis URL logging
2155
- // ─────────────────────────────────────────────────────────────────────────────
2156
-
2157
686
  // ─────────────────────────────────────────────────────────────────────────────
2158
687
  // startChangeStreamWatcher / stopChangeStreamWatcher — MongoDB change stream
2159
688
  // ─────────────────────────────────────────────────────────────────────────────
@@ -2163,12 +692,10 @@ describe("startChangeStreamWatcher", () => {
2163
692
 
2164
693
  beforeEach(() => {
2165
694
  originalDb = mongoose.connection.db;
2166
- clearRealtimeRegistry();
2167
695
  });
2168
696
 
2169
697
  afterEach(async () => {
2170
698
  setConnectionDb(originalDb);
2171
- clearRealtimeRegistry();
2172
699
  // Ensure the watcher is stopped between tests
2173
700
  const {stopChangeStreamWatcher: stop} = await import("./changeStreamWatcher.js");
2174
701
  await stop();
@@ -2250,352 +777,33 @@ describe("startChangeStreamWatcher", () => {
2250
777
  it("throws when watch returns null", async () => {
2251
778
  const mockDb = {
2252
779
  watch: mock(() => null),
2253
- };
2254
- setConnectionDb(mockDb);
2255
-
2256
- const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
2257
- const io = createMockIo();
2258
-
2259
- expect(() => startChangeStreamWatcher(io)).toThrow("Failed to create change stream watcher");
2260
- });
2261
-
2262
- it("handles change events for registered models", async () => {
2263
- const mockStream = createMockChangeStream();
2264
- const mockDb = {
2265
- watch: mock(() => mockStream),
2266
- };
2267
- setConnectionDb(mockDb);
2268
-
2269
- registerRealtime({
2270
- collectionName: "todos",
2271
- config: {
2272
- methods: ["create", "update", "delete"],
2273
- roomStrategy: "model",
2274
- },
2275
- modelName: "Todo",
2276
- options: {
2277
- permissions: {
2278
- create: [() => true],
2279
- delete: [() => true],
2280
- list: [() => true],
2281
- read: [() => true],
2282
- update: [() => true],
2283
- },
2284
- },
2285
- routePath: "/todos",
2286
- });
2287
-
2288
- const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
2289
- const io = createMockIo();
2290
-
2291
- startChangeStreamWatcher(io, {}, true);
2292
-
2293
- // Trigger an insert change event
2294
- await invokeRegisteredChangeHandler(mockStream, {
2295
- documentKey: {_id: "doc-1"},
2296
- fullDocument: {_id: "doc-1", name: "Test Todo"},
2297
- ns: {coll: "todos"},
2298
- operationType: "insert",
2299
- });
2300
- });
2301
-
2302
- it("skips events for unregistered collections", async () => {
2303
- const mockStream = createMockChangeStream();
2304
- const mockDb = {
2305
- watch: mock(() => mockStream),
2306
- };
2307
- setConnectionDb(mockDb);
2308
-
2309
- const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
2310
- const io = createMockIo();
2311
-
2312
- startChangeStreamWatcher(io, {}, true);
2313
-
2314
- // Trigger for an unregistered collection — should not throw
2315
- await invokeRegisteredChangeHandler(mockStream, {
2316
- documentKey: {_id: "doc-1"},
2317
- fullDocument: {_id: "doc-1"},
2318
- ns: {coll: "unknown_collection"},
2319
- operationType: "insert",
2320
- });
2321
- });
2322
-
2323
- it("skips events when method is not enabled for the model", async () => {
2324
- const mockStream = createMockChangeStream();
2325
- const mockDb = {
2326
- watch: mock(() => mockStream),
2327
- };
2328
- setConnectionDb(mockDb);
2329
-
2330
- registerRealtime({
2331
- collectionName: "todos",
2332
- config: {
2333
- methods: ["create"], // only create enabled
2334
- roomStrategy: "model",
2335
- },
2336
- modelName: "Todo",
2337
- options: {
2338
- permissions: {
2339
- create: [() => true],
2340
- delete: [],
2341
- list: [() => true],
2342
- read: [() => true],
2343
- update: [],
2344
- },
2345
- },
2346
- routePath: "/todos",
2347
- });
2348
-
2349
- const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
2350
- const io = createMockIo();
2351
-
2352
- startChangeStreamWatcher(io, {}, true);
2353
-
2354
- // Update event should be skipped because "update" not in methods
2355
- await invokeRegisteredChangeHandler(mockStream, {
2356
- documentKey: {_id: "doc-1"},
2357
- fullDocument: {_id: "doc-1", name: "Updated"},
2358
- ns: {coll: "todos"},
2359
- operationType: "update",
2360
- updateDescription: {updatedFields: {name: "Updated"}},
2361
- });
2362
- });
2363
-
2364
- it("handles delete events for owner-strategy models", async () => {
2365
- const mockStream = createMockChangeStream();
2366
- const mockDb = {
2367
- watch: mock(() => mockStream),
2368
- };
2369
- setConnectionDb(mockDb);
2370
-
2371
- registerRealtime({
2372
- collectionName: "todos",
2373
- config: {
2374
- methods: ["create", "update", "delete"],
2375
- roomStrategy: "owner",
2376
- },
2377
- modelName: "Todo",
2378
- options: {
2379
- permissions: {
2380
- create: [() => true],
2381
- delete: [() => true],
2382
- list: [() => true],
2383
- read: [() => true],
2384
- update: [() => true],
2385
- },
2386
- },
2387
- routePath: "/todos",
2388
- });
2389
-
2390
- const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
2391
- const io = createMockIo();
2392
-
2393
- startChangeStreamWatcher(io, {}, true);
2394
-
2395
- // Hard delete (no fullDocument)
2396
- await invokeRegisteredChangeHandler(mockStream, {
2397
- documentKey: {_id: "doc-1"},
2398
- ns: {coll: "todos"},
2399
- operationType: "delete",
2400
- });
2401
- });
2402
-
2403
- it("handles delete events for broadcast-strategy models", async () => {
2404
- const mockStream = createMockChangeStream();
2405
- const mockDb = {
2406
- watch: mock(() => mockStream),
2407
- };
2408
- setConnectionDb(mockDb);
2409
-
2410
- registerRealtime({
2411
- collectionName: "broadcasts",
2412
- config: {
2413
- methods: ["create", "update", "delete"],
2414
- roomStrategy: "broadcast",
2415
- },
2416
- modelName: "Broadcast",
2417
- options: {
2418
- permissions: {
2419
- create: [() => true],
2420
- delete: [() => true],
2421
- list: [() => true],
2422
- read: [() => true],
2423
- update: [() => true],
2424
- },
2425
- },
2426
- routePath: "/broadcasts",
2427
- });
2428
-
2429
- const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
2430
- const io = createMockIo();
2431
-
2432
- startChangeStreamWatcher(io, {}, true);
2433
-
2434
- // Hard delete for broadcast strategy
2435
- await invokeRegisteredChangeHandler(mockStream, {
2436
- documentKey: {_id: "doc-1"},
2437
- ns: {coll: "broadcasts"},
2438
- operationType: "delete",
2439
- });
2440
- });
2441
-
2442
- // Records every emission so hard-delete room routing can be asserted.
2443
- const createRecordingIo = (
2444
- room: string,
2445
- decodedToken: {admin?: boolean; id?: string} = {admin: true, id: "admin"}
2446
- ): {
2447
- emissions: Array<{event: string; payload: unknown}>;
2448
- io: import("socket.io").Server;
2449
- } => {
2450
- const emissions: Array<{event: string; payload: unknown}> = [];
2451
- const rooms = new Map<string, Set<string>>([[room, new Set(["socket-1"])]]);
2452
- const sockets = new Map<string, unknown>([
2453
- [
2454
- "socket-1",
2455
- {
2456
- decodedToken,
2457
- emit: (event: string, payload: unknown): void => {
2458
- emissions.push({event, payload});
2459
- },
2460
- id: "socket-1",
2461
- },
2462
- ],
2463
- ]);
2464
- return {
2465
- emissions,
2466
- io: {
2467
- sockets: {adapter: {rooms}, sockets},
2468
- to: (_room: string) => ({emit: (_event: string, _data: unknown) => {}}),
2469
- } as unknown as import("socket.io").Server,
2470
- };
2471
- };
2472
-
2473
- it("routes hard deletes for model-strategy models to the model room", async () => {
2474
- const mockStream = createMockChangeStream();
2475
- const mockDb = {
2476
- watch: mock(() => mockStream),
2477
- };
2478
- setConnectionDb(mockDb);
2479
-
2480
- registerRealtime({
2481
- collectionName: "todos",
2482
- config: {
2483
- methods: ["create", "update", "delete"],
2484
- roomStrategy: "model",
2485
- },
2486
- modelName: "Todo",
2487
- options: {
2488
- permissions: {
2489
- create: [() => true],
2490
- delete: [() => true],
2491
- list: [() => true],
2492
- read: [() => true],
2493
- update: [() => true],
2494
- },
2495
- },
2496
- routePath: "/todos",
2497
- });
2498
-
2499
- const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
2500
- const {emissions, io} = createRecordingIo("model:todos");
2501
-
2502
- startChangeStreamWatcher(io, {}, true);
2503
-
2504
- await invokeRegisteredChangeHandler(mockStream, {
2505
- documentKey: {_id: "doc-1"},
2506
- ns: {coll: "todos"},
2507
- operationType: "delete",
2508
- });
2509
-
2510
- expect(emissions).toHaveLength(1);
2511
- expect(emissions[0].payload).toMatchObject({id: "doc-1", method: "delete", model: "Todo"});
2512
- });
2513
-
2514
- it("swallows errors thrown while processing a change event", async () => {
2515
- const mockStream = createMockChangeStream();
2516
- const mockDb = {
2517
- watch: mock(() => mockStream),
2518
- };
2519
- setConnectionDb(mockDb);
2520
-
2521
- registerRealtime({
2522
- collectionName: "todos",
2523
- config: {
2524
- methods: ["create", "update", "delete"],
2525
- roomStrategy: "model",
2526
- },
2527
- modelName: "Todo",
2528
- options: {
2529
- permissions: {
2530
- create: [() => true],
2531
- delete: [() => true],
2532
- list: [() => true],
2533
- read: [() => true],
2534
- update: [() => true],
2535
- },
2536
- },
2537
- routePath: "/todos",
2538
- });
2539
-
2540
- const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
2541
- const roomLookup = mock(() => {
2542
- throw new Error("adapter unavailable");
2543
- });
2544
- const io = {
2545
- sockets: {adapter: {rooms: {get: roomLookup}}, sockets: new Map()},
2546
- to: (_room: string) => ({emit: (_event: string, _data: unknown) => {}}),
2547
- } as unknown as import("socket.io").Server;
2548
-
2549
- startChangeStreamWatcher(io, {}, true);
2550
-
2551
- // The handler must not reject — a failed emission cannot take down the change stream.
2552
- await invokeRegisteredChangeHandler(mockStream, {
2553
- documentKey: {_id: "doc-1"},
2554
- fullDocument: {_id: "doc-1", name: "Test Todo"},
2555
- ns: {coll: "todos"},
2556
- operationType: "insert",
2557
- });
780
+ };
781
+ setConnectionDb(mockDb);
782
+
783
+ const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
784
+ const io = createMockIo();
2558
785
 
2559
- expect(roomLookup).toHaveBeenCalled();
786
+ expect(() => startChangeStreamWatcher(io)).toThrow("Failed to create change stream watcher");
2560
787
  });
2561
788
 
2562
- it("includes updatedFields in event for update operations", async () => {
789
+ it("skips events for unregistered collections", async () => {
2563
790
  const mockStream = createMockChangeStream();
2564
791
  const mockDb = {
2565
792
  watch: mock(() => mockStream),
2566
793
  };
2567
794
  setConnectionDb(mockDb);
2568
795
 
2569
- registerRealtime({
2570
- collectionName: "todos",
2571
- config: {
2572
- methods: ["create", "update", "delete"],
2573
- roomStrategy: "model",
2574
- },
2575
- modelName: "Todo",
2576
- options: {
2577
- permissions: {
2578
- create: [() => true],
2579
- delete: [() => true],
2580
- list: [() => true],
2581
- read: [() => true],
2582
- update: [() => true],
2583
- },
2584
- },
2585
- routePath: "/todos",
2586
- });
2587
-
2588
796
  const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
2589
797
  const io = createMockIo();
2590
798
 
2591
799
  startChangeStreamWatcher(io, {}, true);
2592
800
 
801
+ // Trigger for an unregistered collection — should not throw
2593
802
  await invokeRegisteredChangeHandler(mockStream, {
2594
803
  documentKey: {_id: "doc-1"},
2595
- fullDocument: {_id: "doc-1", name: "Updated", status: "done"},
2596
- ns: {coll: "todos"},
2597
- operationType: "update",
2598
- updateDescription: {updatedFields: {name: "Updated", status: "done"}},
804
+ fullDocument: {_id: "doc-1"},
805
+ ns: {coll: "unknown_collection"},
806
+ operationType: "insert",
2599
807
  });
2600
808
  });
2601
809
 
@@ -2628,25 +836,6 @@ describe("startChangeStreamWatcher", () => {
2628
836
  };
2629
837
  setConnectionDb(mockDb);
2630
838
 
2631
- registerRealtime({
2632
- collectionName: "todos",
2633
- config: {
2634
- methods: ["create", "update", "delete"],
2635
- roomStrategy: "model",
2636
- },
2637
- modelName: "Todo",
2638
- options: {
2639
- permissions: {
2640
- create: [() => true],
2641
- delete: [() => true],
2642
- list: [() => true],
2643
- read: [() => true],
2644
- update: [() => true],
2645
- },
2646
- },
2647
- routePath: "/todos",
2648
- });
2649
-
2650
839
  const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
2651
840
  const io = createMockIo();
2652
841
 
@@ -2661,6 +850,34 @@ describe("startChangeStreamWatcher", () => {
2661
850
  });
2662
851
  });
2663
852
 
853
+ it("swallows errors thrown while processing a change event", async () => {
854
+ const mockStream = createMockChangeStream();
855
+ const mockDb = {
856
+ watch: mock(() => mockStream),
857
+ };
858
+ setConnectionDb(mockDb);
859
+
860
+ const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
861
+ const io = createMockIo();
862
+
863
+ startChangeStreamWatcher(io, {}, true);
864
+
865
+ const malformedEvent = {
866
+ documentKey: {_id: "doc-1"},
867
+ get ns(): never {
868
+ throw new Error("malformed change event");
869
+ },
870
+ operationType: "insert",
871
+ };
872
+ // The handler must not reject — one bad event cannot take down the change stream.
873
+ await expect(
874
+ invokeRegisteredChangeHandler(
875
+ mockStream,
876
+ malformedEvent as unknown as Record<string, unknown>
877
+ )
878
+ ).resolves.toBeUndefined();
879
+ });
880
+
2664
881
  it("skips events with no collectionName or docId", async () => {
2665
882
  const mockStream = createMockChangeStream();
2666
883
  const mockDb = {
@@ -2705,43 +922,6 @@ describe("startChangeStreamWatcher", () => {
2705
922
  });
2706
923
  });
2707
924
 
2708
- it("returns early when the mapped realtime operation is null", async () => {
2709
- const mockStream = createMockChangeStream();
2710
- const mockDb = {
2711
- watch: mock(() => mockStream),
2712
- };
2713
- setConnectionDb(mockDb);
2714
-
2715
- registerRealtime({
2716
- collectionName: "todos",
2717
- config: {
2718
- methods: ["create", "update", "delete"],
2719
- roomStrategy: "model",
2720
- },
2721
- modelName: "Todo",
2722
- options: {permissions: permissiveOptions.permissions},
2723
- routePath: "/todos",
2724
- });
2725
-
2726
- const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
2727
- const {emissions, io} = createRecordingIo("model:todos");
2728
- let operationTypeReads = 0;
2729
- startChangeStreamWatcher(io, {}, true);
2730
-
2731
- await invokeRegisteredChangeHandler(mockStream, {
2732
- documentKey: {_id: "doc-1"},
2733
- fullDocument: {_id: "doc-1"},
2734
- ns: {coll: "todos"},
2735
- get operationType(): string {
2736
- operationTypeReads += 1;
2737
- return operationTypeReads === 1 ? "insert" : "invalidate";
2738
- },
2739
- });
2740
-
2741
- assert.isAtLeast(operationTypeReads, 2);
2742
- assert.isEmpty(emissions);
2743
- });
2744
-
2745
925
  it("handles error/close/end events gracefully", async () => {
2746
926
  const mockStream = createMockChangeStream();
2747
927
  const mockDb = {
@@ -2761,7 +941,7 @@ describe("startChangeStreamWatcher", () => {
2761
941
  });
2762
942
 
2763
943
  // Task 9.16: a transient stream failure used to be logged and then permanently starve
2764
- // every realtime event and sync delta until the process restarted.
944
+ // every sync delta until the process restarted.
2765
945
  describe("restart with resume token (Task 9.16)", () => {
2766
946
  const waitFor = async (
2767
947
  predicate: () => boolean,
@@ -2778,65 +958,37 @@ describe("startChangeStreamWatcher", () => {
2778
958
  throw new Error(`Timed out after ${timeoutMs}ms waiting for ${label}`);
2779
959
  };
2780
960
 
2781
- const registerTodos = (): void => {
2782
- registerRealtime({
2783
- collectionName: "todos",
2784
- config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
2785
- modelName: "Todo",
2786
- options: {
2787
- permissions: {
2788
- create: [() => true],
2789
- delete: [() => true],
2790
- list: [() => true],
2791
- read: [() => true],
2792
- update: [() => true],
2793
- },
2794
- },
2795
- routePath: "/todos",
2796
- });
2797
- };
2798
-
2799
- /** An io whose room socket records deliveries, plus a recorded server-wide `emit`. */
961
+ /** An io with no sockets that records server-wide `emit` calls. */
2800
962
  const createRecordingIo = (): {
2801
963
  io: import("socket.io").Server;
2802
- deliveries: {event: string; payload: unknown}[];
2803
964
  serverEmissions: {event: string; payload: unknown}[];
2804
965
  } => {
2805
- const deliveries: {event: string; payload: unknown}[] = [];
2806
966
  const serverEmissions: {event: string; payload: unknown}[] = [];
2807
- const rooms = new Map<string, Set<string>>();
2808
- rooms.set("model:todos", new Set(["sock-1"]));
2809
- const sockets = new Map<string, MockRoomSocket>();
2810
- sockets.set("sock-1", {
2811
- decodedToken: {id: "user-1"},
2812
- emit: (event: string, payload: unknown) => {
2813
- deliveries.push({event, payload});
2814
- },
2815
- id: "sock-1",
2816
- });
2817
967
  return {
2818
- deliveries,
2819
968
  io: {
2820
969
  emit: (event: string, payload: unknown) => {
2821
970
  serverEmissions.push({event, payload});
2822
971
  },
2823
- sockets: {adapter: {rooms}, sockets},
972
+ sockets: {adapter: {rooms: new Map()}, sockets: new Map()},
2824
973
  to: () => ({emit: () => {}}),
2825
974
  } as unknown as import("socket.io").Server,
2826
975
  serverEmissions,
2827
976
  };
2828
977
  };
2829
978
 
2830
- it("reopens with resumeAfter after a stream error and keeps delivering changes", async () => {
979
+ const resumeAfterForCall = (watch: ReturnType<typeof mock>, callIndex: number): unknown =>
980
+ ((watch.mock.calls[callIndex] as unknown[])[1] as {resumeAfter?: unknown}).resumeAfter;
981
+
982
+ it("reopens with resumeAfter after a stream error and keeps tracking changes", async () => {
2831
983
  const firstStream = createMockChangeStream();
2832
984
  const secondStream = createMockChangeStream();
2833
- const streams = [firstStream, secondStream];
2834
- const mockDb = {watch: mock(() => streams.shift() ?? secondStream)};
985
+ const thirdStream = createMockChangeStream();
986
+ const streams = [firstStream, secondStream, thirdStream];
987
+ const mockDb = {watch: mock(() => streams.shift() ?? thirdStream)};
2835
988
  setConnectionDb(mockDb);
2836
- registerTodos();
2837
989
 
2838
990
  const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
2839
- const {deliveries, io} = createRecordingIo();
991
+ const {io} = createRecordingIo();
2840
992
  startChangeStreamWatcher(io, {}, true);
2841
993
 
2842
994
  // A change on the first stream establishes the resume position.
@@ -2844,28 +996,25 @@ describe("startChangeStreamWatcher", () => {
2844
996
  _id: {_data: "token-1"},
2845
997
  documentKey: {_id: "doc-1"},
2846
998
  fullDocument: {_id: "doc-1", name: "before the failure"},
2847
- ns: {coll: "todos"},
999
+ ns: {coll: "unregistered"},
2848
1000
  operationType: "insert",
2849
1001
  });
2850
- expect(deliveries).toHaveLength(1);
2851
1002
 
2852
1003
  firstStream.trigger("error", new Error("replica set election"));
2853
1004
  await waitFor(() => mockDb.watch.mock.calls.length >= 2, "the stream to reopen");
1005
+ expect(resumeAfterForCall(mockDb.watch, 1)).toEqual({_data: "token-1"});
2854
1006
 
2855
- const reopenOptions = (mockDb.watch.mock.calls[1] as unknown[])[1] as {
2856
- resumeAfter?: unknown;
2857
- };
2858
- expect(reopenOptions.resumeAfter).toEqual({_data: "token-1"});
2859
-
2860
- // The reopened stream is fully wired: later writes still fan out.
1007
+ // The reopened stream is fully wired: its changes advance the resume position.
2861
1008
  await invokeRegisteredChangeHandler(secondStream, {
2862
1009
  _id: {_data: "token-2"},
2863
1010
  documentKey: {_id: "doc-2"},
2864
1011
  fullDocument: {_id: "doc-2", name: "after the restart"},
2865
- ns: {coll: "todos"},
1012
+ ns: {coll: "unregistered"},
2866
1013
  operationType: "insert",
2867
1014
  });
2868
- expect(deliveries).toHaveLength(2);
1015
+ secondStream.trigger("error", new Error("network blip"));
1016
+ await waitFor(() => mockDb.watch.mock.calls.length >= 3, "the stream to reopen again");
1017
+ expect(resumeAfterForCall(mockDb.watch, 2)).toEqual({_data: "token-2"});
2869
1018
  });
2870
1019
 
2871
1020
  it("drops the resume token and asks clients to resync when the oplog history is lost", async () => {
@@ -2942,71 +1091,6 @@ describe("startChangeStreamWatcher", () => {
2942
1091
  expect(options.batchSize).toBe(100);
2943
1092
  expect(options.fullDocument).toBe("whenAvailable");
2944
1093
  });
2945
-
2946
- it("catches errors thrown in the change handler", async () => {
2947
- const mockStream = createMockChangeStream();
2948
- const mockDb = {
2949
- watch: mock(() => mockStream),
2950
- };
2951
- setConnectionDb(mockDb);
2952
-
2953
- // Register with a model that will throw during permission check
2954
- registerRealtime({
2955
- collectionName: "todos",
2956
- config: {
2957
- methods: ["create", "update", "delete"],
2958
- roomStrategy: "model",
2959
- },
2960
- modelName: "Todo",
2961
- options: {
2962
- permissions: {
2963
- create: [() => true],
2964
- delete: [() => true],
2965
- list: [() => true],
2966
- read: [
2967
- () => {
2968
- throw new Error("permission check error");
2969
- },
2970
- ],
2971
- update: [() => true],
2972
- },
2973
- },
2974
- routePath: "/todos",
2975
- });
2976
-
2977
- const {startChangeStreamWatcher} = await import("./changeStreamWatcher.js");
2978
-
2979
- // Create an IO with a socket in the target room
2980
- const emissions: Array<{_data: unknown; _event: string}> = [];
2981
- const mockSocket: MockRoomSocket = {
2982
- decodedToken: {id: "user-1"},
2983
- emit: (_event: string, _data: unknown) => {
2984
- emissions.push({_data, _event});
2985
- },
2986
- id: "sock-1",
2987
- };
2988
- const rooms = new Map<string, Set<string>>();
2989
- rooms.set("model:todos", new Set(["sock-1"]));
2990
- const sockets = new Map<string, MockRoomSocket>();
2991
- sockets.set("sock-1", mockSocket);
2992
- const io = {
2993
- sockets: {
2994
- adapter: {rooms},
2995
- sockets,
2996
- },
2997
- to: () => ({emit: () => {}}),
2998
- } as unknown as import("socket.io").Server;
2999
-
3000
- startChangeStreamWatcher(io, {}, true);
3001
-
3002
- // Should not throw even though permission check throws
3003
- await invokeRegisteredChangeHandler(mockStream, {
3004
- documentKey: {_id: "doc-1"},
3005
- fullDocument: {_id: "doc-1", name: "Test"},
3006
- ns: {coll: "todos"},
3007
- operationType: "insert",
3008
- });
3009
- });
3010
1094
  });
3011
1095
 
3012
1096
  describe("stopChangeStreamWatcher", () => {
@@ -3239,7 +1323,6 @@ describe("startChangeStreamWatcher & stopChangeStreamWatcher", () => {
3239
1323
 
3240
1324
  afterEach(async () => {
3241
1325
  await stopChangeStreamWatcher();
3242
- clearRealtimeRegistry();
3243
1326
  });
3244
1327
 
3245
1328
  it("starts and stops without error when MongoDB is connected", async () => {
@@ -3283,428 +1366,6 @@ describe("startChangeStreamWatcher & stopChangeStreamWatcher", () => {
3283
1366
  });
3284
1367
  });
3285
1368
 
3286
- // Change streams require a MongoDB replica set. CI (api-ci.yml) runs standalone MongoDB,
3287
- // so these tests are skipped when replica sets are not available.
3288
- const hasReplicaSet = async (): Promise<boolean> => {
3289
- try {
3290
- const mongoose = require("mongoose");
3291
- const admin = mongoose.connection.db.admin();
3292
- const status = await admin.command({replSetGetStatus: 1});
3293
- return !!status.ok;
3294
- } catch {
3295
- return false;
3296
- }
3297
- };
3298
-
3299
- describe("startChangeStreamWatcher — change event integration", () => {
3300
- const mongoose = require("mongoose");
3301
- let replicaSetAvailable = false;
3302
-
3303
- const realtimeTestSchema = new mongoose.Schema(
3304
- {
3305
- deleted: {default: false, type: Boolean},
3306
- name: {type: String},
3307
- ownerId: {type: String},
3308
- },
3309
- {collection: "realtimetests", strict: "throw"}
3310
- );
3311
-
3312
- interface RealtimeTestDoc {
3313
- deleted?: boolean;
3314
- name?: string;
3315
- ownerId?: string;
3316
- }
3317
-
3318
- let RealtimeTestModel: Model<RealtimeTestDoc>;
3319
- try {
3320
- RealtimeTestModel = mongoose.model("RealtimeTest");
3321
- } catch {
3322
- RealtimeTestModel = mongoose.model("RealtimeTest", realtimeTestSchema);
3323
- }
3324
-
3325
- interface TrackedEmission {
3326
- event: string;
3327
- payload: RealtimeEvent;
3328
- room?: string;
3329
- socketId?: string;
3330
- }
3331
-
3332
- const makeTrackedIo = (): Server & {
3333
- addSocketToRoom: (room: string, decodedToken?: DecodedRealtimeToken) => void;
3334
- emissions: TrackedEmission[];
3335
- } => {
3336
- const emissions: TrackedEmission[] = [];
3337
- const rooms = new Map<string, Set<string>>();
3338
- const sockets = new Map<string, MockRoomSocket>();
3339
-
3340
- const addSocketToRoom = (
3341
- room: string,
3342
- decodedToken: DecodedRealtimeToken = {admin: true, id: "admin"}
3343
- ): void => {
3344
- const socketId = `socket-${Math.random().toString(36).slice(2, 9)}`;
3345
- if (!rooms.has(room)) {
3346
- rooms.set(room, new Set());
3347
- }
3348
- rooms.get(room)?.add(socketId);
3349
- sockets.set(socketId, {
3350
- decodedToken,
3351
- emit: (event: string, payload: unknown): void => {
3352
- emissions.push({event, payload: payload as RealtimeEvent, room, socketId});
3353
- },
3354
- id: socketId,
3355
- });
3356
- };
3357
-
3358
- return {
3359
- addSocketToRoom,
3360
- emissions,
3361
- sockets: {
3362
- adapter: {rooms},
3363
- sockets,
3364
- },
3365
- to: (room: string) => ({
3366
- emit: (event: string, payload: unknown): void => {
3367
- emissions.push({event, payload: payload as RealtimeEvent, room});
3368
- },
3369
- }),
3370
- } as unknown as Server & {
3371
- addSocketToRoom: (room: string, decodedToken?: DecodedRealtimeToken) => void;
3372
- emissions: TrackedEmission[];
3373
- };
3374
- };
3375
-
3376
- beforeAll(async () => {
3377
- replicaSetAvailable = await hasReplicaSet();
3378
- });
3379
-
3380
- beforeEach(async () => {
3381
- clearRealtimeRegistry();
3382
- clearQueryStore();
3383
- await RealtimeTestModel.deleteMany({});
3384
- });
3385
-
3386
- afterEach(async () => {
3387
- await stopChangeStreamWatcher();
3388
- clearRealtimeRegistry();
3389
- clearQueryStore();
3390
- await RealtimeTestModel.deleteMany({});
3391
- });
3392
-
3393
- it("processes insert events from MongoDB change stream", async () => {
3394
- if (!replicaSetAvailable) {
3395
- return;
3396
- }
3397
- registerRealtime({
3398
- collectionName: "realtimetests",
3399
- config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
3400
- modelName: "RealtimeTest",
3401
- options: {
3402
- permissions: {
3403
- create: [() => true],
3404
- delete: [() => true],
3405
- list: [() => true],
3406
- read: [() => true],
3407
- update: [() => true],
3408
- },
3409
- },
3410
- routePath: "/realtimetests",
3411
- });
3412
-
3413
- const io = makeTrackedIo();
3414
- io.addSocketToRoom("model:realtimetests");
3415
- startChangeStreamWatcher(io, {}, true);
3416
-
3417
- await RealtimeTestModel.create({name: "test-item", ownerId: "user-1"});
3418
-
3419
- // Wait for the change stream event to be processed
3420
- await new Promise((resolve) => setTimeout(resolve, 1500));
3421
-
3422
- const createEmissions = io.emissions.filter(
3423
- (e) => e.event === "sync" && e.payload.method === "create"
3424
- );
3425
- expect(createEmissions.length).toBeGreaterThanOrEqual(1);
3426
- await stopChangeStreamWatcher();
3427
- });
3428
-
3429
- it("processes update events from MongoDB change stream", async () => {
3430
- if (!replicaSetAvailable) {
3431
- return;
3432
- }
3433
- registerRealtime({
3434
- collectionName: "realtimetests",
3435
- config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
3436
- modelName: "RealtimeTest",
3437
- options: {
3438
- permissions: {
3439
- create: [() => true],
3440
- delete: [() => true],
3441
- list: [() => true],
3442
- read: [() => true],
3443
- update: [() => true],
3444
- },
3445
- },
3446
- routePath: "/realtimetests",
3447
- });
3448
-
3449
- const doc = await RealtimeTestModel.create({name: "item-to-update", ownerId: "user-1"});
3450
-
3451
- const io = makeTrackedIo();
3452
- io.addSocketToRoom("model:realtimetests");
3453
- startChangeStreamWatcher(io, {}, true);
3454
-
3455
- await RealtimeTestModel.updateOne({_id: doc._id}, {$set: {name: "updated-item"}});
3456
-
3457
- await new Promise((resolve) => setTimeout(resolve, 1500));
3458
-
3459
- const updateEmissions = io.emissions.filter(
3460
- (e) => e.event === "sync" && e.payload?.method === "update"
3461
- );
3462
- expect(updateEmissions.length).toBeGreaterThanOrEqual(1);
3463
- await stopChangeStreamWatcher();
3464
- });
3465
-
3466
- it("processes hard delete events from MongoDB change stream", async () => {
3467
- if (!replicaSetAvailable) {
3468
- return;
3469
- }
3470
- registerRealtime({
3471
- collectionName: "realtimetests",
3472
- config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
3473
- modelName: "RealtimeTest",
3474
- options: {
3475
- permissions: {
3476
- create: [() => true],
3477
- delete: [() => true],
3478
- list: [() => true],
3479
- read: [() => true],
3480
- update: [() => true],
3481
- },
3482
- },
3483
- routePath: "/realtimetests",
3484
- });
3485
-
3486
- const doc = await RealtimeTestModel.create({name: "item-to-delete"});
3487
-
3488
- const io = makeTrackedIo();
3489
- io.addSocketToRoom("model:realtimetests");
3490
- startChangeStreamWatcher(io, {}, true);
3491
-
3492
- await RealtimeTestModel.deleteOne({_id: doc._id});
3493
-
3494
- await new Promise((resolve) => setTimeout(resolve, 1500));
3495
-
3496
- const deleteEmissions = io.emissions.filter(
3497
- (e) => e.event === "sync" && e.payload?.method === "delete"
3498
- );
3499
- expect(deleteEmissions.length).toBeGreaterThanOrEqual(1);
3500
- await stopChangeStreamWatcher();
3501
- });
3502
-
3503
- it("processes soft delete events from MongoDB change stream", async () => {
3504
- if (!replicaSetAvailable) {
3505
- return;
3506
- }
3507
- registerRealtime({
3508
- collectionName: "realtimetests",
3509
- config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
3510
- modelName: "RealtimeTest",
3511
- options: {
3512
- permissions: {
3513
- create: [() => true],
3514
- delete: [() => true],
3515
- list: [() => true],
3516
- read: [() => true],
3517
- update: [() => true],
3518
- },
3519
- },
3520
- routePath: "/realtimetests",
3521
- });
3522
-
3523
- const doc = await RealtimeTestModel.create({name: "item-to-soft-delete"});
3524
-
3525
- const io = makeTrackedIo();
3526
- io.addSocketToRoom("model:realtimetests");
3527
- startChangeStreamWatcher(io, {}, true);
3528
-
3529
- await RealtimeTestModel.updateOne({_id: doc._id}, {$set: {deleted: true}});
3530
-
3531
- await new Promise((resolve) => setTimeout(resolve, 1500));
3532
-
3533
- const deleteEmissions = io.emissions.filter(
3534
- (e) => e.event === "sync" && e.payload?.method === "delete"
3535
- );
3536
- expect(deleteEmissions.length).toBeGreaterThanOrEqual(1);
3537
- await stopChangeStreamWatcher();
3538
- });
3539
-
3540
- it("includes updatedFields and emits to document rooms", async () => {
3541
- if (!replicaSetAvailable) {
3542
- return;
3543
- }
3544
- registerRealtime({
3545
- collectionName: "realtimetests",
3546
- config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
3547
- modelName: "RealtimeTest",
3548
- options: {
3549
- permissions: {
3550
- create: [() => true],
3551
- delete: [() => true],
3552
- list: [() => true],
3553
- read: [() => true],
3554
- update: [() => true],
3555
- },
3556
- },
3557
- routePath: "/realtimetests",
3558
- });
3559
-
3560
- const doc = await RealtimeTestModel.create({name: "fields-test"});
3561
- const docId = doc._id.toString();
3562
-
3563
- const io = makeTrackedIo();
3564
- io.addSocketToRoom("model:realtimetests");
3565
- io.addSocketToRoom(`document:realtimetests:${docId}`);
3566
- startChangeStreamWatcher(io, {}, true);
3567
-
3568
- await RealtimeTestModel.updateOne({_id: doc._id}, {$set: {name: "fields-updated"}});
3569
-
3570
- await new Promise((resolve) => setTimeout(resolve, 1500));
3571
-
3572
- const updateEmissions = io.emissions.filter(
3573
- (e) => e.event === "sync" && e.payload?.method === "update"
3574
- );
3575
- expect(updateEmissions.length).toBeGreaterThanOrEqual(1);
3576
- if (updateEmissions.length > 0) {
3577
- expect(updateEmissions[0].payload.updatedFields).toBeDefined();
3578
- expect(updateEmissions[0].payload.updatedFields).toContain("name");
3579
- }
3580
- await stopChangeStreamWatcher();
3581
- });
3582
- });
3583
-
3584
- // ─────────────────────────────────────────────────────────────────────────────
3585
- // emitToDocumentAndQueryRooms — no-entry path
3586
- // ─────────────────────────────────────────────────────────────────────────────
3587
-
3588
- describe("emitToDocumentAndQueryRooms — no registry entry", () => {
3589
- const makeIoSimple = (): Server & {
3590
- emissions: Array<{room: string; event: string; payload: unknown}>;
3591
- } => {
3592
- const emissions: Array<{room: string; event: string; payload: unknown}> = [];
3593
- return {
3594
- emissions,
3595
- sockets: {
3596
- adapter: {rooms: new Map<string, Set<string>>()},
3597
- sockets: new Map<string, MockRoomSocket>(),
3598
- },
3599
- to: (room: string) => ({
3600
- emit: (event: string, payload: unknown): void => {
3601
- emissions.push({event, payload, room});
3602
- },
3603
- }),
3604
- } as unknown as Server & {
3605
- emissions: Array<{room: string; event: string; payload: unknown}>;
3606
- };
3607
- };
3608
-
3609
- beforeEach(() => {
3610
- clearQueryStore();
3611
- });
3612
-
3613
- afterEach(() => {
3614
- clearQueryStore();
3615
- });
3616
-
3617
- it("emits to document room via io.to when no entry is provided", async () => {
3618
- const io = makeIoSimple();
3619
- const event: RealtimeEvent = {
3620
- collection: "items",
3621
- id: "doc-1",
3622
- method: "update",
3623
- model: "Item",
3624
- timestamp: 1,
3625
- };
3626
- await emitToDocumentAndQueryRooms(io, "items", event, {}, () => {});
3627
- expect(io.emissions.some((e) => e.room === "document:items:doc-1")).toBe(true);
3628
- });
3629
-
3630
- it("emits hard deletes to query rooms via io.to when no entry", async () => {
3631
- const queryId = computeQueryId("items", {status: "active"});
3632
- addQuerySubscription("socket-a", "items", {status: "active"}, queryId);
3633
- const io = makeIoSimple();
3634
- const event: RealtimeEvent = {
3635
- collection: "items",
3636
- id: "doc-1",
3637
- method: "delete",
3638
- model: "Item",
3639
- timestamp: 1,
3640
- };
3641
- await emitToDocumentAndQueryRooms(io, "items", event, undefined, () => {});
3642
- expect(io.emissions.some((e) => e.room === `query:${queryId}`)).toBe(true);
3643
- });
3644
-
3645
- it("emits soft delete to query rooms via io.to when no entry and doc matches", async () => {
3646
- const queryId = computeQueryId("items", {status: "active"});
3647
- addQuerySubscription("socket-a", "items", {status: "active"}, queryId);
3648
- const io = makeIoSimple();
3649
- const event: RealtimeEvent = {
3650
- collection: "items",
3651
- id: "doc-1",
3652
- method: "delete",
3653
- model: "Item",
3654
- timestamp: 1,
3655
- };
3656
- await emitToDocumentAndQueryRooms(io, "items", event, {status: "active"}, () => {});
3657
- expect(io.emissions.some((e) => e.room === `query:${queryId}`)).toBe(true);
3658
- });
3659
-
3660
- it("emits create events to query rooms via io.to when no entry and doc matches", async () => {
3661
- const queryId = computeQueryId("items", {status: "active"});
3662
- addQuerySubscription("socket-a", "items", {status: "active"}, queryId);
3663
- const io = makeIoSimple();
3664
- const event: RealtimeEvent = {
3665
- collection: "items",
3666
- id: "doc-1",
3667
- method: "create",
3668
- model: "Item",
3669
- timestamp: 1,
3670
- };
3671
- await emitToDocumentAndQueryRooms(io, "items", event, {status: "active"}, () => {});
3672
- expect(io.emissions.some((e) => e.room === `query:${queryId}`)).toBe(true);
3673
- });
3674
-
3675
- it("emits update events to query rooms via io.to when no entry and doc matches", async () => {
3676
- const queryId = computeQueryId("items", {status: "active"});
3677
- addQuerySubscription("socket-a", "items", {status: "active"}, queryId);
3678
- const io = makeIoSimple();
3679
- const event: RealtimeEvent = {
3680
- collection: "items",
3681
- id: "doc-1",
3682
- method: "update",
3683
- model: "Item",
3684
- timestamp: 1,
3685
- };
3686
- await emitToDocumentAndQueryRooms(io, "items", event, {status: "active"}, () => {});
3687
- expect(io.emissions.some((e) => e.room === `query:${queryId}`)).toBe(true);
3688
- });
3689
-
3690
- it("emits delete to query rooms via io.to when update no longer matches and no entry", async () => {
3691
- const queryId = computeQueryId("items", {status: "active"});
3692
- addQuerySubscription("socket-a", "items", {status: "active"}, queryId);
3693
- const io = makeIoSimple();
3694
- const event: RealtimeEvent = {
3695
- collection: "items",
3696
- id: "doc-1",
3697
- method: "update",
3698
- model: "Item",
3699
- timestamp: 1,
3700
- };
3701
- await emitToDocumentAndQueryRooms(io, "items", event, {status: "inactive"}, () => {});
3702
- const queryEmissions = io.emissions.filter((e) => e.room === `query:${queryId}`);
3703
- expect(queryEmissions.length).toBe(1);
3704
- expect(queryEmissions[0].payload).toMatchObject({method: "delete"});
3705
- });
3706
- });
3707
-
3708
1369
  // ─────────────────────────────────────────────────────────────────────────────
3709
1370
  // RealtimeApp — onServerCreated, setupAdapter, close
3710
1371
  // ─────────────────────────────────────────────────────────────────────────────
@@ -3721,7 +1382,6 @@ describe("RealtimeApp — onServerCreated and setupAdapter", () => {
3721
1382
 
3722
1383
  afterEach(async () => {
3723
1384
  process.env = originalEnv;
3724
- clearRealtimeRegistry();
3725
1385
  });
3726
1386
 
3727
1387
  it("register adds /realtime/health endpoint with debug flag", async () => {