@terreno/api 0.14.0 → 0.14.2

package/src/realtime/realtime.test.ts

@@ -9,15 +9,19 @@
  *   - changeStreamWatcher.ts (serializeDoc — responseHandler fallback)
  */
 
-import {afterEach, beforeEach, describe, expect, it, mock} from "bun:test";
+import {afterEach, beforeAll, beforeEach, describe, expect, it, mock} from "bun:test";
 import express from "express";
+import mongoose from "mongoose";
 
 import {
   emitToAuthorizedRoom,
   emitToDocumentAndQueryRooms,
+  ensureApiId,
   mapOperationType,
   resolveRooms,
   serializeDoc,
+  startChangeStreamWatcher,
+  stopChangeStreamWatcher,
 } from "./changeStreamWatcher";
 import {matchesQuery} from "./queryMatcher";
 import {
@@ -1734,6 +1738,1416 @@ describe("emitToDocumentAndQueryRooms", () => {
 // redactCredentials — Redis URL logging
 // ─────────────────────────────────────────────────────────────────────────────
 
+// ─────────────────────────────────────────────────────────────────────────────
+// startChangeStreamWatcher / stopChangeStreamWatcher — MongoDB change stream
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("startChangeStreamWatcher", () => {
+  let originalDb: typeof mongoose.connection.db;
+
+  beforeEach(() => {
+    originalDb = mongoose.connection.db;
+    clearRealtimeRegistry();
+  });
+
+  afterEach(async () => {
+    (mongoose.connection as any).db = originalDb;
+    clearRealtimeRegistry();
+    // Ensure the watcher is stopped between tests
+    const {stopChangeStreamWatcher: stop} = await import("./changeStreamWatcher");
+    await stop();
+  });
+
+  const createMockChangeStream = () => {
+    const listeners = new Map<string, (...args: any[]) => void>();
+    return {
+      close: mock(async () => {}),
+      listeners,
+      on(event: string, handler: (...args: any[]) => void) {
+        listeners.set(event, handler);
+        return this;
+      },
+      trigger(event: string, ...args: any[]) {
+        const handler = listeners.get(event);
+        if (handler) {
+          handler(...args);
+        }
+      },
+    };
+  };
+
+  const createMockIo = () => {
+    const rooms = new Map<string, Set<string>>();
+    const sockets = new Map<string, any>();
+    return {
+      sockets: {
+        adapter: {rooms},
+        sockets,
+      },
+      to: (_room: string) => ({
+        emit: (_event: string, _data: any) => {},
+      }),
+    } as unknown as import("socket.io").Server;
+  };
+
+  it("initializes and registers change/error/close/end listeners", async () => {
+    const mockStream = createMockChangeStream();
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    startChangeStreamWatcher(io, {}, true);
+
+    expect(mockDb.watch).toHaveBeenCalled();
+    expect(mockStream.listeners.has("change")).toBe(true);
+    expect(mockStream.listeners.has("error")).toBe(true);
+    expect(mockStream.listeners.has("close")).toBe(true);
+    expect(mockStream.listeners.has("end")).toBe(true);
+  });
+
+  it("throws when mongoose connection db is unavailable", async () => {
+    (mongoose.connection as any).db = undefined;
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    expect(() => startChangeStreamWatcher(io)).toThrow(
+      "MongoDB connection not available for change stream"
+    );
+  });
+
+  it("throws when watch returns null", async () => {
+    const mockDb = {
+      watch: mock(() => null),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    expect(() => startChangeStreamWatcher(io)).toThrow("Failed to create change stream watcher");
+  });
+
+  it("handles change events for registered models", async () => {
+    const mockStream = createMockChangeStream();
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    registerRealtime({
+      collectionName: "todos",
+      config: {
+        methods: ["create", "update", "delete"],
+        roomStrategy: "model",
+      },
+      modelName: "Todo",
+      options: {
+        permissions: {
+          create: [() => true],
+          delete: [() => true],
+          list: [() => true],
+          read: [() => true],
+          update: [() => true],
+        },
+      },
+      routePath: "/todos",
+    });
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    startChangeStreamWatcher(io, {}, true);
+
+    // Trigger an insert change event
+    const changeHandler = mockStream.listeners.get("change");
+    expect(changeHandler).toBeDefined();
+    await changeHandler!({
+      documentKey: {_id: "doc-1"},
+      fullDocument: {_id: "doc-1", name: "Test Todo"},
+      ns: {coll: "todos"},
+      operationType: "insert",
+    });
+  });
+
+  it("skips events for unregistered collections", async () => {
+    const mockStream = createMockChangeStream();
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    startChangeStreamWatcher(io, {}, true);
+
+    const changeHandler = mockStream.listeners.get("change");
+    // Trigger for an unregistered collection — should not throw
+    await changeHandler!({
+      documentKey: {_id: "doc-1"},
+      fullDocument: {_id: "doc-1"},
+      ns: {coll: "unknown_collection"},
+      operationType: "insert",
+    });
+  });
+
+  it("skips events when method is not enabled for the model", async () => {
+    const mockStream = createMockChangeStream();
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    registerRealtime({
+      collectionName: "todos",
+      config: {
+        methods: ["create"], // only create enabled
+        roomStrategy: "model",
+      },
+      modelName: "Todo",
+      options: {
+        permissions: {
+          create: [() => true],
+          delete: [],
+          list: [() => true],
+          read: [() => true],
+          update: [],
+        },
+      },
+      routePath: "/todos",
+    });
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    startChangeStreamWatcher(io, {}, true);
+
+    const changeHandler = mockStream.listeners.get("change");
+    // Update event should be skipped because "update" not in methods
+    await changeHandler!({
+      documentKey: {_id: "doc-1"},
+      fullDocument: {_id: "doc-1", name: "Updated"},
+      ns: {coll: "todos"},
+      operationType: "update",
+      updateDescription: {updatedFields: {name: "Updated"}},
+    });
+  });
+
+  it("handles delete events for owner-strategy models", async () => {
+    const mockStream = createMockChangeStream();
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    registerRealtime({
+      collectionName: "todos",
+      config: {
+        methods: ["create", "update", "delete"],
+        roomStrategy: "owner",
+      },
+      modelName: "Todo",
+      options: {
+        permissions: {
+          create: [() => true],
+          delete: [() => true],
+          list: [() => true],
+          read: [() => true],
+          update: [() => true],
+        },
+      },
+      routePath: "/todos",
+    });
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    startChangeStreamWatcher(io, {}, true);
+
+    const changeHandler = mockStream.listeners.get("change");
+    // Hard delete (no fullDocument)
+    await changeHandler!({
+      documentKey: {_id: "doc-1"},
+      ns: {coll: "todos"},
+      operationType: "delete",
+    });
+  });
+
+  it("handles delete events for broadcast-strategy models", async () => {
+    const mockStream = createMockChangeStream();
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    registerRealtime({
+      collectionName: "broadcasts",
+      config: {
+        methods: ["create", "update", "delete"],
+        roomStrategy: "broadcast",
+      },
+      modelName: "Broadcast",
+      options: {
+        permissions: {
+          create: [() => true],
+          delete: [() => true],
+          list: [() => true],
+          read: [() => true],
+          update: [() => true],
+        },
+      },
+      routePath: "/broadcasts",
+    });
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    startChangeStreamWatcher(io, {}, true);
+
+    const changeHandler = mockStream.listeners.get("change");
+    // Hard delete for broadcast strategy
+    await changeHandler!({
+      documentKey: {_id: "doc-1"},
+      ns: {coll: "broadcasts"},
+      operationType: "delete",
+    });
+  });
+
+  it("includes updatedFields in event for update operations", async () => {
+    const mockStream = createMockChangeStream();
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    registerRealtime({
+      collectionName: "todos",
+      config: {
+        methods: ["create", "update", "delete"],
+        roomStrategy: "model",
+      },
+      modelName: "Todo",
+      options: {
+        permissions: {
+          create: [() => true],
+          delete: [() => true],
+          list: [() => true],
+          read: [() => true],
+          update: [() => true],
+        },
+      },
+      routePath: "/todos",
+    });
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    startChangeStreamWatcher(io, {}, true);
+
+    const changeHandler = mockStream.listeners.get("change");
+    await changeHandler!({
+      documentKey: {_id: "doc-1"},
+      fullDocument: {_id: "doc-1", name: "Updated", status: "done"},
+      ns: {coll: "todos"},
+      operationType: "update",
+      updateDescription: {updatedFields: {name: "Updated", status: "done"}},
+    });
+  });
+
+  it("respects ignoredCollections config", async () => {
+    const mockStream = createMockChangeStream();
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    startChangeStreamWatcher(io, {ignoredCollections: ["audit_logs"]}, true);
+
+    // Verify the pipeline passed to watch includes the ignored collections
+    const pipeline = (mockDb.watch.mock.calls[0] as any[])[0];
+    const matchStage = pipeline[0].$match;
+    expect(matchStage["ns.coll"].$nin).toContain("audit_logs");
+    expect(matchStage["ns.coll"].$nin).toContain("socketio");
+    expect(matchStage["ns.coll"].$nin).toContain("sessions");
+  });
+
+  it("respects ignoredOperations config", async () => {
+    const mockStream = createMockChangeStream();
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    registerRealtime({
+      collectionName: "todos",
+      config: {
+        methods: ["create", "update", "delete"],
+        roomStrategy: "model",
+      },
+      modelName: "Todo",
+      options: {
+        permissions: {
+          create: [() => true],
+          delete: [() => true],
+          list: [() => true],
+          read: [() => true],
+          update: [() => true],
+        },
+      },
+      routePath: "/todos",
+    });
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    startChangeStreamWatcher(io, {ignoredOperations: ["insert"]}, true);
+
+    const changeHandler = mockStream.listeners.get("change");
+    // This insert should be skipped because "insert" is ignored
+    await changeHandler!({
+      documentKey: {_id: "doc-1"},
+      fullDocument: {_id: "doc-1"},
+      ns: {coll: "todos"},
+      operationType: "insert",
+    });
+  });
+
+  it("skips events with no collectionName or docId", async () => {
+    const mockStream = createMockChangeStream();
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    startChangeStreamWatcher(io, {}, true);
+
+    const changeHandler = mockStream.listeners.get("change");
+    // Missing ns.coll
+    await changeHandler!({
+      documentKey: {_id: "doc-1"},
+      ns: {},
+      operationType: "insert",
+    });
+    // Missing documentKey
+    await changeHandler!({
+      documentKey: {},
+      ns: {coll: "todos"},
+      operationType: "insert",
+    });
+  });
+
+  it("skips non-CRUD operation types", async () => {
+    const mockStream = createMockChangeStream();
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    startChangeStreamWatcher(io, {}, true);
+
+    const changeHandler = mockStream.listeners.get("change");
+    // "drop" is not in our pipeline filter, should be skipped
+    await changeHandler!({
+      operationType: "drop",
+    });
+  });
+
+  it("handles error/close/end events gracefully", async () => {
+    const mockStream = createMockChangeStream();
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    startChangeStreamWatcher(io, {}, true);
+
+    // Trigger error, close, end — should not throw
+    mockStream.trigger("error", new Error("test error"));
+    mockStream.trigger("close");
+    mockStream.trigger("end");
+  });
+
+  it("uses custom batchSize and fullDocument config", async () => {
+    const mockStream = createMockChangeStream();
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+    const io = createMockIo();
+
+    startChangeStreamWatcher(io, {batchSize: 100, fullDocument: "whenAvailable"}, true);
+
+    const options = (mockDb.watch.mock.calls[0] as any[])[1];
+    expect(options.batchSize).toBe(100);
+    expect(options.fullDocument).toBe("whenAvailable");
+  });
+
+  it("catches errors thrown in the change handler", async () => {
+    const mockStream = createMockChangeStream();
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    (mongoose.connection as any).db = mockDb;
+
+    // Register with a model that will throw during permission check
+    registerRealtime({
+      collectionName: "todos",
+      config: {
+        methods: ["create", "update", "delete"],
+        roomStrategy: "model",
+      },
+      modelName: "Todo",
+      options: {
+        permissions: {
+          create: [() => true],
+          delete: [() => true],
+          list: [() => true],
+          read: [
+            () => {
+              throw new Error("permission check error");
+            },
+          ],
+          update: [() => true],
+        },
+      },
+      routePath: "/todos",
+    });
+
+    const {startChangeStreamWatcher} = await import("./changeStreamWatcher");
+
+    // Create an IO with a socket in the target room
+    const emissions: any[] = [];
+    const mockSocket = {
+      decodedToken: {id: "user-1"},
+      emit: (_event: string, _data: any) => {
+        emissions.push({_data, _event});
+      },
+      id: "sock-1",
+    };
+    const rooms = new Map<string, Set<string>>();
+    rooms.set("model:todos", new Set(["sock-1"]));
+    const sockets = new Map<string, any>();
+    sockets.set("sock-1", mockSocket);
+    const io = {
+      sockets: {
+        adapter: {rooms},
+        sockets,
+      },
+      to: () => ({emit: () => {}}),
+    } as unknown as import("socket.io").Server;
+
+    startChangeStreamWatcher(io, {}, true);
+
+    const changeHandler = mockStream.listeners.get("change");
+    // Should not throw even though permission check throws
+    await changeHandler!({
+      documentKey: {_id: "doc-1"},
+      fullDocument: {_id: "doc-1", name: "Test"},
+      ns: {coll: "todos"},
+      operationType: "insert",
+    });
+  });
+});
+
+describe("stopChangeStreamWatcher", () => {
+  it("closes and nullifies the active watcher", async () => {
+    const mockStream = {
+      close: mock(async () => {}),
+      on: () => {},
+    };
+    const mockDb = {
+      watch: mock(() => mockStream),
+    };
+    const originalDb = mongoose.connection.db;
+    (mongoose.connection as any).db = mockDb;
+
+    const {startChangeStreamWatcher, stopChangeStreamWatcher} = await import(
+      "./changeStreamWatcher"
+    );
+    const io = {
+      sockets: {
+        adapter: {rooms: new Map()},
+        sockets: new Map(),
+      },
+      to: () => ({emit: () => {}}),
+    } as unknown as import("socket.io").Server;
+
+    startChangeStreamWatcher(io);
+    await stopChangeStreamWatcher();
+    expect(mockStream.close).toHaveBeenCalled();
+
+    // Calling again should be a no-op
+    await stopChangeStreamWatcher();
+
+    (mongoose.connection as any).db = originalDb;
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// RealtimeApp.onServerCreated / setupAdapter
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("RealtimeApp.onServerCreated", () => {
+  const servers: import("http").Server[] = [];
+
+  afterEach(async () => {
+    for (const s of servers) {
+      s.close();
+    }
+    servers.length = 0;
+  });
+
+  const makeServer = (): import("http").Server => {
+    const http = require("http");
+    const server = http.createServer();
+    servers.push(server);
+    return server;
+  };
+
+  it("throws when TOKEN_SECRET is missing", () => {
+    const originalSecret = process.env.TOKEN_SECRET;
+    process.env.TOKEN_SECRET = "";
+
+    const app = new RealtimeApp({tokenSecret: undefined});
+    const server = makeServer();
+
+    expect(() => app.onServerCreated(server)).toThrow("TOKEN_SECRET is required");
+
+    process.env.TOKEN_SECRET = originalSecret;
+  });
+
+  it("sets up Socket.io with valid config", async () => {
+    const app = new RealtimeApp({
+      adapter: "none",
+      tokenSecret: "test-secret",
+    });
+    const server = makeServer();
+
+    // Mock mongoose.connection.db for changeStreamWatcher
+    const originalDb = mongoose.connection.db;
+    const mockStream = {close: async () => {}, on: () => mockStream};
+    (mongoose.connection as any).db = {watch: () => mockStream};
+
+    app.onServerCreated(server);
+    expect(app.getIo()).toBeDefined();
+
+    await app.close();
+    (mongoose.connection as any).db = originalDb;
+  });
+});
+
+describe("RealtimeApp.setupAdapter (private, via onServerCreated config)", () => {
+  const servers: import("http").Server[] = [];
+
+  afterEach(async () => {
+    for (const s of servers) {
+      s.close();
+    }
+    servers.length = 0;
+  });
+
+  const makeServer = (): import("http").Server => {
+    const http = require("http");
+    const server = http.createServer();
+    servers.push(server);
+    return server;
+  };
+
+  it("logs warning when redis adapter requested but no URL found", async () => {
+    const originalValkey = process.env.VALKEY_URL;
+    const originalRedis = process.env.REDIS_URL;
+    const originalDb = mongoose.connection.db;
+    process.env.VALKEY_URL = "";
+    process.env.REDIS_URL = "";
+
+    const mockStream = {close: async () => {}, on: () => mockStream};
+    (mongoose.connection as any).db = {watch: () => mockStream};
+
+    const app = new RealtimeApp({
+      adapter: "redis",
+      tokenSecret: "test-secret",
+    });
+    const server = makeServer();
+
+    app.onServerCreated(server);
+    await app.close();
+
+    process.env.VALKEY_URL = originalValkey;
+    process.env.REDIS_URL = originalRedis;
+    (mongoose.connection as any).db = originalDb;
+  });
+
+  it("logs info when redis adapter has a URL", async () => {
+    const originalValkey = process.env.VALKEY_URL;
+    const originalDb = mongoose.connection.db;
+    process.env.VALKEY_URL = "redis://user:pass@localhost:6379/0";
+
+    const mockStream = {close: async () => {}, on: () => mockStream};
+    (mongoose.connection as any).db = {watch: () => mockStream};
+
+    const app = new RealtimeApp({
+      adapter: "redis",
+      debug: true,
+      tokenSecret: "test-secret",
+    });
+    const server = makeServer();
+
+    app.onServerCreated(server);
+    await app.close();
+
+    process.env.VALKEY_URL = originalValkey;
+    (mongoose.connection as any).db = originalDb;
+  });
+
+  it("no-op adapter mode 'none'", async () => {
+    const originalDb = mongoose.connection.db;
+    const mockStream = {close: async () => {}, on: () => mockStream};
+    (mongoose.connection as any).db = {watch: () => mockStream};
+
+    const app = new RealtimeApp({
+      adapter: "none",
+      tokenSecret: "test-secret",
+    });
+    const server = makeServer();
+
+    app.onServerCreated(server);
+    expect(app.getIo()).toBeDefined();
+
+    await app.close();
+    (mongoose.connection as any).db = originalDb;
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ensureApiId
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("ensureApiId", () => {
+  it("returns null as-is", () => {
+    expect(ensureApiId(null)).toBeNull();
+  });
+
+  it("returns undefined as-is", () => {
+    expect(ensureApiId(undefined)).toBeUndefined();
+  });
+
+  it("returns arrays as-is", () => {
+    const arr = [1, 2, 3];
+    expect(ensureApiId(arr)).toBe(arr);
+  });
+
+  it("returns primitive values as-is (non-object)", () => {
+    expect(ensureApiId("string")).toBe("string");
+  });
+
+  it("adds id from _id when id is missing", () => {
+    expect(ensureApiId({_id: "abc"})).toEqual({_id: "abc", id: "abc"});
+  });
+
+  it("does not overwrite existing id", () => {
+    expect(ensureApiId({_id: "abc", id: "existing"})).toEqual({_id: "abc", id: "existing"});
+  });
+
+  it("returns object without _id unchanged", () => {
+    const obj = {name: "test"};
+    expect(ensureApiId(obj)).toBe(obj);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// startChangeStreamWatcher & stopChangeStreamWatcher
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("startChangeStreamWatcher & stopChangeStreamWatcher", () => {
+  const makeMockIo = (): any => {
+    const emissions: any[] = [];
+    const rooms = new Map<string, Set<string>>();
+    const sockets = new Map<string, any>();
+    return {
+      emissions,
+      sockets: {
+        adapter: {rooms},
+        sockets,
+      },
+      to: (_room: string) => ({
+        emit: (): void => {},
+      }),
+    };
+  };
+
+  afterEach(async () => {
+    await stopChangeStreamWatcher();
+    clearRealtimeRegistry();
+  });
+
+  it("starts and stops without error when MongoDB is connected", async () => {
+    const io = makeMockIo();
+    expect(() => startChangeStreamWatcher(io, {}, false)).not.toThrow();
+    await stopChangeStreamWatcher();
+  });
+
+  it("starts with debug mode enabled", async () => {
+    const io = makeMockIo();
+    expect(() => startChangeStreamWatcher(io, {}, true)).not.toThrow();
+    await stopChangeStreamWatcher();
+  });
+
+  it("starts with custom config options", async () => {
+    const io = makeMockIo();
+    expect(() =>
+      startChangeStreamWatcher(
+        io,
+        {
+          batchSize: 10,
+          fullDocument: "whenAvailable",
+          ignoredCollections: ["logs"],
+          ignoredOperations: ["delete"],
+        },
+        false
+      )
+    ).not.toThrow();
+    await stopChangeStreamWatcher();
+  });
+
+  it("stopChangeStreamWatcher is safe to call when no watcher is active", async () => {
+    await expect(stopChangeStreamWatcher()).resolves.toBeUndefined();
+  });
+
+  it("stopChangeStreamWatcher can be called multiple times", async () => {
+    const io = makeMockIo();
+    startChangeStreamWatcher(io, {}, false);
+    await stopChangeStreamWatcher();
+    await stopChangeStreamWatcher();
+  });
+});
+
+// Change streams require a MongoDB replica set. CI (api-ci.yml) runs standalone MongoDB,
+// so these tests are skipped when replica sets are not available.
+const hasReplicaSet = async (): Promise<boolean> => {
+  try {
+    const mongoose = require("mongoose");
+    const admin = mongoose.connection.db.admin();
+    const status = await admin.command({replSetGetStatus: 1});
+    return !!status.ok;
+  } catch {
+    return false;
+  }
+};
+
+describe("startChangeStreamWatcher — change event integration", () => {
+  const mongoose = require("mongoose");
+  let replicaSetAvailable = false;
+
+  const realtimeTestSchema = new mongoose.Schema(
+    {
+      deleted: {default: false, type: Boolean},
+      name: {type: String},
+      ownerId: {type: String},
+    },
+    {collection: "realtimetests", strict: "throw"}
+  );
+
+  let RealtimeTestModel: any;
+  try {
+    RealtimeTestModel = mongoose.model("RealtimeTest");
+  } catch {
+    RealtimeTestModel = mongoose.model("RealtimeTest", realtimeTestSchema);
+  }
+
+  const makeTrackedIo = (): any => {
+    const emissions: any[] = [];
+    const rooms = new Map<string, Set<string>>();
+    const sockets = new Map<string, any>();
+
+    const addSocketToRoom = (
+      room: string,
+      decodedToken: {id?: string; admin?: boolean} = {admin: true, id: "admin"}
+    ): void => {
+      const socketId = `socket-${Math.random().toString(36).slice(2, 9)}`;
+      if (!rooms.has(room)) {
+        rooms.set(room, new Set());
+      }
+      rooms.get(room)?.add(socketId);
+      sockets.set(socketId, {
+        decodedToken,
+        emit: (event: string, payload: unknown): void => {
+          emissions.push({event, payload, room, socketId});
+        },
+        id: socketId,
+      });
+    };
+
+    return {
+      addSocketToRoom,
+      emissions,
+      sockets: {
+        adapter: {rooms},
+        sockets,
+      },
+      to: (room: string) => ({
+        emit: (event: string, payload: unknown): void => {
+          emissions.push({event, payload, room});
+        },
+      }),
+    };
+  };
+
+  beforeAll(async () => {
+    replicaSetAvailable = await hasReplicaSet();
+  });
+
+  beforeEach(async () => {
+    clearRealtimeRegistry();
+    clearQueryStore();
+    await RealtimeTestModel.deleteMany({});
+  });
+
+  afterEach(async () => {
+    await stopChangeStreamWatcher();
+    clearRealtimeRegistry();
+    clearQueryStore();
+    await RealtimeTestModel.deleteMany({});
+  });
+
+  it("processes insert events from MongoDB change stream", async () => {
+    if (!replicaSetAvailable) {
+      return;
+    }
+    registerRealtime({
+      collectionName: "realtimetests",
+      config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
+      modelName: "RealtimeTest",
+      options: {
+        permissions: {
+          create: [() => true],
+          delete: [() => true],
+          list: [() => true],
+          read: [() => true],
+          update: [() => true],
+        },
+      } as any,
+      routePath: "/realtimetests",
+    });
+
+    const io = makeTrackedIo();
+    io.addSocketToRoom("model:realtimetests");
+    startChangeStreamWatcher(io, {}, true);
+
+    await RealtimeTestModel.create({name: "test-item", ownerId: "user-1"});
+
+    // Wait for the change stream event to be processed
+    await new Promise((resolve) => setTimeout(resolve, 1500));
+
+    const createEmissions = io.emissions.filter(
+      (e: any) => e.event === "sync" && e.payload?.method === "create"
+    );
+    expect(createEmissions.length).toBeGreaterThanOrEqual(1);
+    await stopChangeStreamWatcher();
+  });
+
+  it("processes update events from MongoDB change stream", async () => {
+    if (!replicaSetAvailable) {
+      return;
+    }
+    registerRealtime({
+      collectionName: "realtimetests",
+      config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
+      modelName: "RealtimeTest",
+      options: {
+        permissions: {
+          create: [() => true],
+          delete: [() => true],
+          list: [() => true],
+          read: [() => true],
+          update: [() => true],
+        },
+      } as any,
+      routePath: "/realtimetests",
+    });
+
+    const doc = await RealtimeTestModel.create({name: "item-to-update", ownerId: "user-1"});
+
+    const io = makeTrackedIo();
+    io.addSocketToRoom("model:realtimetests");
+    startChangeStreamWatcher(io, {}, true);
+
+    await RealtimeTestModel.updateOne({_id: doc._id}, {$set: {name: "updated-item"}});
+
+    await new Promise((resolve) => setTimeout(resolve, 1500));
+
+    const updateEmissions = io.emissions.filter(
+      (e: any) => e.event === "sync" && e.payload?.method === "update"
+    );
+    expect(updateEmissions.length).toBeGreaterThanOrEqual(1);
+    await stopChangeStreamWatcher();
+  });
+
+  it("processes hard delete events from MongoDB change stream", async () => {
+    if (!replicaSetAvailable) {
+      return;
+    }
+    registerRealtime({
+      collectionName: "realtimetests",
+      config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
+      modelName: "RealtimeTest",
+      options: {
+        permissions: {
+          create: [() => true],
+          delete: [() => true],
+          list: [() => true],
+          read: [() => true],
+          update: [() => true],
+        },
+      } as any,
+      routePath: "/realtimetests",
+    });
+
+    const doc = await RealtimeTestModel.create({name: "item-to-delete"});
+
+    const io = makeTrackedIo();
+    io.addSocketToRoom("model:realtimetests");
+    startChangeStreamWatcher(io, {}, true);
+
+    await RealtimeTestModel.deleteOne({_id: doc._id});
+
+    await new Promise((resolve) => setTimeout(resolve, 1500));
+
+    const deleteEmissions = io.emissions.filter(
+      (e: any) => e.event === "sync" && e.payload?.method === "delete"
+    );
+    expect(deleteEmissions.length).toBeGreaterThanOrEqual(1);
+    await stopChangeStreamWatcher();
+  });
+
+  it("processes soft delete events from MongoDB change stream", async () => {
+    if (!replicaSetAvailable) {
+      return;
+    }
+    registerRealtime({
+      collectionName: "realtimetests",
+      config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
+      modelName: "RealtimeTest",
+      options: {
+        permissions: {
+          create: [() => true],
+          delete: [() => true],
+          list: [() => true],
+          read: [() => true],
+          update: [() => true],
+        },
+      } as any,
+      routePath: "/realtimetests",
+    });
+
+    const doc = await RealtimeTestModel.create({name: "item-to-soft-delete"});
+
+    const io = makeTrackedIo();
+    io.addSocketToRoom("model:realtimetests");
+    startChangeStreamWatcher(io, {}, true);
+
+    await RealtimeTestModel.updateOne({_id: doc._id}, {$set: {deleted: true}});
+
+    await new Promise((resolve) => setTimeout(resolve, 1500));
+
+    const deleteEmissions = io.emissions.filter(
+      (e: any) => e.event === "sync" && e.payload?.method === "delete"
+    );
+    expect(deleteEmissions.length).toBeGreaterThanOrEqual(1);
+    await stopChangeStreamWatcher();
+  });
+
+  it("includes updatedFields and emits to document rooms", async () => {
+    if (!replicaSetAvailable) {
+      return;
+    }
+    registerRealtime({
+      collectionName: "realtimetests",
+      config: {methods: ["create", "update", "delete"], roomStrategy: "model"},
+      modelName: "RealtimeTest",
+      options: {
+        permissions: {
+          create: [() => true],
+          delete: [() => true],
+          list: [() => true],
+          read: [() => true],
+          update: [() => true],
+        },
+      } as any,
+      routePath: "/realtimetests",
+    });
+
+    const doc = await RealtimeTestModel.create({name: "fields-test"});
+    const docId = doc._id.toString();
+
+    const io = makeTrackedIo();
+    io.addSocketToRoom("model:realtimetests");
+    io.addSocketToRoom(`document:realtimetests:${docId}`);
+    startChangeStreamWatcher(io, {}, true);
+
+    await RealtimeTestModel.updateOne({_id: doc._id}, {$set: {name: "fields-updated"}});
+
+    await new Promise((resolve) => setTimeout(resolve, 1500));
+
+    const updateEmissions = io.emissions.filter(
+      (e: any) => e.event === "sync" && e.payload?.method === "update"
+    );
+    expect(updateEmissions.length).toBeGreaterThanOrEqual(1);
+    if (updateEmissions.length > 0) {
+      expect(updateEmissions[0].payload.updatedFields).toBeDefined();
+      expect(updateEmissions[0].payload.updatedFields).toContain("name");
+    }
+    await stopChangeStreamWatcher();
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// emitToDocumentAndQueryRooms — no-entry path
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("emitToDocumentAndQueryRooms — no registry entry", () => {
+  const makeIoSimple = (): any => {
+    const emissions: Array<{room: string; event: string; payload: unknown}> = [];
+    return {
+      emissions,
+      sockets: {
+        adapter: {rooms: new Map()},
+        sockets: new Map(),
+      },
+      to: (room: string) => ({
+        emit: (event: string, payload: unknown): void => {
+          emissions.push({event, payload, room});
+        },
+      }),
+    };
+  };
+
+  beforeEach(() => {
+    clearQueryStore();
+  });
+
+  afterEach(() => {
+    clearQueryStore();
+  });
+
+  it("emits to document room via io.to when no entry is provided", async () => {
+    const io = makeIoSimple();
+    const event: any = {
+      collection: "items",
+      id: "doc-1",
+      method: "update",
+      model: "Item",
+      timestamp: 1,
+    };
+    await emitToDocumentAndQueryRooms(io, "items", event, {}, () => {});
+    expect(io.emissions.some((e: any) => e.room === "document:items:doc-1")).toBe(true);
+  });
+
+  it("emits hard deletes to query rooms via io.to when no entry", async () => {
+    const queryId = computeQueryId("items", {status: "active"});
+    addQuerySubscription("socket-a", "items", {status: "active"}, queryId);
+    const io = makeIoSimple();
+    const event: any = {
+      collection: "items",
+      id: "doc-1",
+      method: "delete",
+      model: "Item",
+      timestamp: 1,
+    };
+    await emitToDocumentAndQueryRooms(io, "items", event, undefined, () => {});
+    expect(io.emissions.some((e: any) => e.room === `query:${queryId}`)).toBe(true);
+  });
+
+  it("emits soft delete to query rooms via io.to when no entry and doc matches", async () => {
+    const queryId = computeQueryId("items", {status: "active"});
+    addQuerySubscription("socket-a", "items", {status: "active"}, queryId);
+    const io = makeIoSimple();
+    const event: any = {
+      collection: "items",
+      id: "doc-1",
+      method: "delete",
+      model: "Item",
+      timestamp: 1,
+    };
+    await emitToDocumentAndQueryRooms(io, "items", event, {status: "active"}, () => {});
+    expect(io.emissions.some((e: any) => e.room === `query:${queryId}`)).toBe(true);
+  });
+
+  it("emits create events to query rooms via io.to when no entry and doc matches", async () => {
+    const queryId = computeQueryId("items", {status: "active"});
+    addQuerySubscription("socket-a", "items", {status: "active"}, queryId);
+    const io = makeIoSimple();
+    const event: any = {
+      collection: "items",
+      id: "doc-1",
+      method: "create",
+      model: "Item",
+      timestamp: 1,
+    };
+    await emitToDocumentAndQueryRooms(io, "items", event, {status: "active"}, () => {});
+    expect(io.emissions.some((e: any) => e.room === `query:${queryId}`)).toBe(true);
+  });
+
+  it("emits update events to query rooms via io.to when no entry and doc matches", async () => {
+    const queryId = computeQueryId("items", {status: "active"});
+    addQuerySubscription("socket-a", "items", {status: "active"}, queryId);
+    const io = makeIoSimple();
+    const event: any = {
+      collection: "items",
+      id: "doc-1",
+      method: "update",
+      model: "Item",
+      timestamp: 1,
+    };
+    await emitToDocumentAndQueryRooms(io, "items", event, {status: "active"}, () => {});
+    expect(io.emissions.some((e: any) => e.room === `query:${queryId}`)).toBe(true);
+  });
+
+  it("emits delete to query rooms via io.to when update no longer matches and no entry", async () => {
+    const queryId = computeQueryId("items", {status: "active"});
+    addQuerySubscription("socket-a", "items", {status: "active"}, queryId);
+    const io = makeIoSimple();
+    const event: any = {
+      collection: "items",
+      id: "doc-1",
+      method: "update",
+      model: "Item",
+      timestamp: 1,
+    };
+    await emitToDocumentAndQueryRooms(io, "items", event, {status: "inactive"}, () => {});
+    const queryEmissions = io.emissions.filter((e: any) => e.room === `query:${queryId}`);
+    expect(queryEmissions.length).toBe(1);
+    expect(queryEmissions[0].payload).toMatchObject({method: "delete"});
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// RealtimeApp — onServerCreated, setupAdapter, close
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("RealtimeApp — onServerCreated and setupAdapter", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = {
+      ...originalEnv,
+      TOKEN_SECRET: "test-secret",
+    };
+  });
+
+  afterEach(async () => {
+    process.env = originalEnv;
+    clearRealtimeRegistry();
+  });
+
+  it("register adds /realtime/health endpoint with debug flag", async () => {
+    const expressApp = express();
+    const app = new RealtimeApp({debug: true});
+    app.register(expressApp);
+    const supertest = await import("supertest");
+    const st = supertest.default(expressApp);
+    const res = await st.get("/realtime/health").expect(200);
+    expect(res.body.status).toBe("not_started");
+    expect(res.body.debug).toBe(true);
+    expect(res.body.clients).toBe(0);
+  });
+
+  it("onServerCreated sets up Socket.io with JWT auth", async () => {
+    const http = await import("node:http");
+    const app = new RealtimeApp({debug: true, tokenSecret: "test-secret"});
+    const expressApp = express();
+    app.register(expressApp);
+    const server = http.createServer(expressApp);
+
+    app.onServerCreated(server);
+    expect(app.getIo()).not.toBeNull();
+
+    await app.close();
+    server.close();
+  });
+
+  it("onServerCreated throws when TOKEN_SECRET is missing", () => {
+    const http = require("node:http");
+    const origSecret = process.env.TOKEN_SECRET;
+    process.env.TOKEN_SECRET = "";
+    const app = new RealtimeApp({});
+    const expressApp = express();
+    app.register(expressApp);
+    const server = http.createServer(expressApp);
+
+    expect(() => app.onServerCreated(server)).toThrow("TOKEN_SECRET is required");
+    process.env.TOKEN_SECRET = origSecret;
+    server.close();
+  });
+
+  it("onServerCreated uses default TOKEN_SECRET from env", async () => {
+    const http = await import("node:http");
+    process.env.TOKEN_SECRET = "env-secret";
+    const app = new RealtimeApp({debug: false});
+    const expressApp = express();
+    app.register(expressApp);
+    const server = http.createServer(expressApp);
+
+    app.onServerCreated(server);
+    expect(app.getIo()).not.toBeNull();
+
+    await app.close();
+    server.close();
+  });
+
+  it("setupAdapter logs info for redis adapter with URL", async () => {
+    const http = await import("node:http");
+    const app = new RealtimeApp({
+      adapter: "redis",
+      debug: true,
+      redisUrl: "redis://user:pass@localhost:6379",
+      tokenSecret: "test-secret",
+    });
+    const expressApp = express();
+    app.register(expressApp);
+    const server = http.createServer(expressApp);
+
+    app.onServerCreated(server);
+    expect(app.getIo()).not.toBeNull();
+
+    await app.close();
+    server.close();
+  });
+
+  it("setupAdapter warns when redis adapter has no URL", async () => {
+    const http = await import("node:http");
+    const origValkey = process.env.VALKEY_URL;
+    const origRedis = process.env.REDIS_URL;
+    delete process.env.VALKEY_URL;
+    delete process.env.REDIS_URL;
+
+    const app = new RealtimeApp({
+      adapter: "redis",
+      debug: true,
+      tokenSecret: "test-secret",
+    });
+    const expressApp = express();
+    app.register(expressApp);
+    const server = http.createServer(expressApp);
+
+    app.onServerCreated(server);
+    expect(app.getIo()).not.toBeNull();
+
+    await app.close();
+    server.close();
+    process.env.VALKEY_URL = origValkey;
+    process.env.REDIS_URL = origRedis;
+  });
+
+  it("setupAdapter with none adapter does nothing extra", async () => {
+    const http = await import("node:http");
+    const app = new RealtimeApp({
+      adapter: "none",
+      debug: true,
+      tokenSecret: "test-secret",
+    });
+    const expressApp = express();
+    app.register(expressApp);
+    const server = http.createServer(expressApp);
+
+    app.onServerCreated(server);
+    expect(app.getIo()).not.toBeNull();
+
+    await app.close();
+    server.close();
+  });
+
+  it("close is safe after onServerCreated", async () => {
+    const http = await import("node:http");
+    const app = new RealtimeApp({tokenSecret: "test-secret"});
+    const expressApp = express();
+    app.register(expressApp);
+    const server = http.createServer(expressApp);
+
+    app.onServerCreated(server);
+    await app.close();
+    expect(app.getIo()).toBeNull();
+    server.close();
+  });
+
+  it("health endpoint reports running after onServerCreated", async () => {
+    const http = await import("node:http");
+    const app = new RealtimeApp({tokenSecret: "test-secret"});
+    const expressApp = express();
+    app.register(expressApp);
+    const server = http.createServer(expressApp);
+
+    app.onServerCreated(server);
+
+    const supertest = await import("supertest");
+    const st = supertest.default(expressApp);
+    const res = await st.get("/realtime/health").expect(200);
+    expect(res.body.status).toBe("running");
+
+    await app.close();
+    server.close();
+  });
+
+  it("onServerCreated with custom cors option", async () => {
+    const http = await import("node:http");
+    const app = new RealtimeApp({
+      cors: {methods: ["GET"], origin: "https://example.com"},
+      tokenSecret: "test-secret",
+    });
+    const expressApp = express();
+    app.register(expressApp);
+    const server = http.createServer(expressApp);
+
+    app.onServerCreated(server);
+    expect(app.getIo()).not.toBeNull();
+
+    await app.close();
+    server.close();
+  });
+
+  it("setupAdapter uses VALKEY_URL when redisUrl not provided", async () => {
+    const http = await import("node:http");
+    process.env.VALKEY_URL = "redis://localhost:6379";
+    const app = new RealtimeApp({
+      adapter: "redis",
+      debug: true,
+      tokenSecret: "test-secret",
+    });
+    const expressApp = express();
+    app.register(expressApp);
+    const server = http.createServer(expressApp);
+
+    app.onServerCreated(server);
+    expect(app.getIo()).not.toBeNull();
+
+    await app.close();
+    server.close();
+    delete process.env.VALKEY_URL;
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// redactCredentials — Redis URL logging
+// ─────────────────────────────────────────────────────────────────────────────
+
 describe("redactCredentials", () => {
   it("redacts user:password@ in a redis URL", () => {
     expect(redactCredentials("redis://user:secret@host:6379/0")).toBe("redis://***@host:6379/0");