@terreno/api 0.13.2 → 0.14.0

package/dist/realtime/realtimeApp.d.ts

@@ -0,0 +1,93 @@
+import type http from "node:http";
+import type express from "express";
+import { Server } from "socket.io";
+import type { TerrenoPlugin } from "../terrenoPlugin";
+import { type SocketWithDecodedToken } from "./socketUser";
+import type { RealtimeAppOptions } from "./types";
+/**
+ * Caps on per-socket subscriptions. Prevents a malicious or buggy client from
+ * exhausting server memory by opening unbounded subscriptions.
+ */
+export declare const MAX_MODEL_SUBSCRIPTIONS = 50;
+export declare const MAX_DOCUMENT_SUBSCRIPTIONS = 500;
+export declare const MAX_QUERY_SUBSCRIPTIONS = 100;
+/**
+ * Replace any userinfo (`user:password@`) component in a URL with `***@` so the
+ * credentials are not written to logs. Falls back to a regex when the string
+ * isn't a valid URL the standard `URL` parser can read.
+ *
+ * Exported for testing.
+ */
+export declare const redactCredentials: (url: string) => string;
+/**
+ * Minimal shape this module requires from a Socket.io socket. Lets tests pass a
+ * mock without standing up a real server.
+ */
+export interface RealtimeSocketLike extends SocketWithDecodedToken {
+    id: string;
+    join: (room: string) => Promise<void> | void;
+    leave: (room: string) => Promise<void> | void;
+    emit: (event: string, payload: unknown) => void;
+    on: (event: string, handler: (...args: any[]) => any) => void;
+}
+/**
+ * Install the realtime subscription handlers on a single socket. Extracted from the
+ * RealtimeApp connection handler so this logic can be unit-tested with a mock socket
+ * (no real Socket.io / HTTP server / JWT handshake required).
+ *
+ * Enforces:
+ *   - per-socket subscription caps (DoS protection)
+ *   - registry membership (only realtime-enabled collections can be subscribed)
+ *   - owner-strategy isolation (non-admin users cannot subscribe to other users' rooms)
+ *   - server-side queryId computation (clients can't hijack queries by colliding ids)
+ */
+export declare const installRealtimeSocketHandlers: (socket: RealtimeSocketLike, options?: {
+    logInfo?: (msg: string) => void;
+}) => void;
+/**
+ * TerrenoPlugin that provides real-time sync via Socket.io and MongoDB change streams.
+ *
+ * Attaches a Socket.io server to the HTTP server created by TerrenoApp.start(),
+ * sets up JWT authentication for socket connections, manages room subscriptions
+ * (model, document, and query rooms), and starts a change stream watcher that
+ * emits events to connected clients.
+ *
+ * ## Subscription types
+ *
+ * - **Model rooms**: `subscribe:model` / `unsubscribe:model` — receive all events for a collection
+ * - **Document rooms**: `subscribe:document` / `unsubscribe:document` — receive events for a single document
+ * - **Query rooms**: `subscribe:query` / `unsubscribe:query` — receive events matching a MongoDB query
+ *
+ * @example
+ * ```typescript
+ * const app = new TerrenoApp({
+ *   userModel: User,
+ *   realtime: { debug: true },
+ * })
+ *   .register(todoRouter)   // todoRouter has realtime config
+ *   .start();
+ * ```
+ */
+export declare class RealtimeApp implements TerrenoPlugin {
+    private io;
+    private config;
+    constructor(config?: RealtimeAppOptions);
+    /**
+     * Register routes and middleware. Adds a /realtime/health endpoint.
+     */
+    register(app: express.Application): void;
+    /**
+     * Called after the HTTP server is created. Sets up Socket.io, auth, rooms,
+     * and starts the change stream watcher.
+     */
+    onServerCreated(server: http.Server): void;
+    /**
+     * Get the Socket.io server instance.
+     */
+    getIo(): Server | null;
+    /**
+     * Gracefully shut down the real-time server.
+     */
+    close(): Promise<void>;
+    private setupAdapter;
+}

package/dist/realtime/realtimeApp.js

@@ -0,0 +1,560 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealtimeApp = exports.installRealtimeSocketHandlers = exports.redactCredentials = exports.MAX_QUERY_SUBSCRIPTIONS = exports.MAX_DOCUMENT_SUBSCRIPTIONS = exports.MAX_MODEL_SUBSCRIPTIONS = void 0;
+var Sentry = __importStar(require("@sentry/bun"));
+var socketio_jwt_1 = require("@thream/socketio-jwt");
+var socket_io_1 = require("socket.io");
+var logger_1 = require("../logger");
+var permissions_1 = require("../permissions");
+var changeStreamWatcher_1 = require("./changeStreamWatcher");
+var queryStore_1 = require("./queryStore");
+var registry_1 = require("./registry");
+var socketUser_1 = require("./socketUser");
+/**
+ * Caps on per-socket subscriptions. Prevents a malicious or buggy client from
+ * exhausting server memory by opening unbounded subscriptions.
+ */
+exports.MAX_MODEL_SUBSCRIPTIONS = 50;
+exports.MAX_DOCUMENT_SUBSCRIPTIONS = 500;
+exports.MAX_QUERY_SUBSCRIPTIONS = 100;
+/**
+ * Replace any userinfo (`user:password@`) component in a URL with `***@` so the
+ * credentials are not written to logs. Falls back to a regex when the string
+ * isn't a valid URL the standard `URL` parser can read.
+ *
+ * Exported for testing.
+ */
+var redactCredentials = function (url) {
+    try {
+        var parsed = new URL(url);
+        if (parsed.username || parsed.password) {
+            parsed.username = "";
+            parsed.password = "";
+            // URL serialization drops the empty userinfo; reinsert a sentinel so logs make it
+            // obvious credentials were stripped rather than silently absent from the source URL.
+            return parsed.toString().replace("".concat(parsed.protocol, "//"), "".concat(parsed.protocol, "//***@"));
+        }
+        return parsed.toString();
+    }
+    catch (_a) {
+        return url.replace(/^(\w+):\/\/[^@/]*@/, "$1://***@");
+    }
+};
+exports.redactCredentials = redactCredentials;
+var canSubscribe = function (entry, method, user) { return __awaiter(void 0, void 0, void 0, function () {
+    var permissions;
+    return __generator(this, function (_a) {
+        permissions = entry.options.permissions[method];
+        return [2 /*return*/, (0, permissions_1.checkPermissions)(method, permissions, user)];
+    });
+}); };
+var getAuthorizedQuery = function (entry, query, user) { return __awaiter(void 0, void 0, void 0, function () {
+    var filteredQuery, error_1;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0: return [4 /*yield*/, canSubscribe(entry, "list", user)];
+            case 1:
+                if (!(_a.sent())) {
+                    return [2 /*return*/, null];
+                }
+                if (!entry.options.queryFilter) {
+                    return [2 /*return*/, query];
+                }
+                _a.label = 2;
+            case 2:
+                _a.trys.push([2, 4, , 5]);
+                return [4 /*yield*/, entry.options.queryFilter(user, query)];
+            case 3:
+                filteredQuery = _a.sent();
+                return [3 /*break*/, 5];
+            case 4:
+                error_1 = _a.sent();
+                logger_1.logger.error("[realtime] queryFilter threw for ".concat(entry.modelName, "/list: ").concat(error_1, ". Denying query subscription."));
+                Sentry.captureException(error_1);
+                return [2 /*return*/, null];
+            case 5:
+                if (filteredQuery === null) {
+                    return [2 /*return*/, null];
+                }
+                return [2 /*return*/, __assign(__assign({}, query), filteredQuery)];
+        }
+    });
+}); };
+/**
+ * Install the realtime subscription handlers on a single socket. Extracted from the
+ * RealtimeApp connection handler so this logic can be unit-tested with a mock socket
+ * (no real Socket.io / HTTP server / JWT handshake required).
+ *
+ * Enforces:
+ *   - per-socket subscription caps (DoS protection)
+ *   - registry membership (only realtime-enabled collections can be subscribed)
+ *   - owner-strategy isolation (non-admin users cannot subscribe to other users' rooms)
+ *   - server-side queryId computation (clients can't hijack queries by colliding ids)
+ */
+var installRealtimeSocketHandlers = function (socket, options) {
+    var _a, _b, _c;
+    if (options === void 0) { options = {}; }
+    var logInfo = (_a = options.logInfo) !== null && _a !== void 0 ? _a : (function () { });
+    var userId = (_b = socket.decodedToken) === null || _b === void 0 ? void 0 : _b.id;
+    var isAdmin = ((_c = socket.decodedToken) === null || _c === void 0 ? void 0 : _c.admin) === true;
+    var user = (0, socketUser_1.getSocketUser)(socket);
+    var counts = { document: 0, model: 0, query: 0 };
+    var joinUserRooms = function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!userId) return [3 /*break*/, 3];
+                    return [4 /*yield*/, socket.join("user:".concat(userId))];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, socket.join("authenticated")];
+                case 2:
+                    _a.sent();
+                    logInfo("[realtime] User ".concat(userId, " connected"));
+                    _a.label = 3;
+                case 3:
+                    if (!isAdmin) return [3 /*break*/, 5];
+                    return [4 /*yield*/, socket.join("admin")];
+                case 4:
+                    _a.sent();
+                    logInfo("[realtime] Admin user ".concat(userId, " joined admin room"));
+                    _a.label = 5;
+                case 5: return [2 /*return*/];
+            }
+        });
+    }); };
+    // Fire-and-forget — there is nothing useful for the caller to await.
+    void joinUserRooms();
+    socket.on("subscribe:model", function (modelName) { return __awaiter(void 0, void 0, void 0, function () {
+        var entry;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (typeof modelName !== "string" || modelName.length === 0) {
+                        return [2 /*return*/];
+                    }
+                    if (counts.model >= exports.MAX_MODEL_SUBSCRIPTIONS) {
+                        logInfo("[realtime] User ".concat(userId, " hit model subscription limit"));
+                        return [2 /*return*/];
+                    }
+                    entry = (0, registry_1.findRegistryEntryByRoutePath)(modelName);
+                    if (!entry) {
+                        logInfo("[realtime] User ".concat(userId, " denied model subscription: collection \"").concat(modelName, "\" not registered"));
+                        return [2 /*return*/];
+                    }
+                    // Owner-strategy models fan out via user:{ownerId} — there is no shared model room
+                    // that should be open to all users. Owners receive events through their user room
+                    // automatically; admins can use the admin room to see everything.
+                    if (entry.config.roomStrategy === "owner" && !isAdmin) {
+                        logInfo("[realtime] User ".concat(userId, " denied model subscription for ").concat(modelName, ": ") +
+                            "owner strategy restricts model room to admins");
+                        return [2 /*return*/];
+                    }
+                    return [4 /*yield*/, canSubscribe(entry, "list", user)];
+                case 1:
+                    if (!(_a.sent())) {
+                        logInfo("[realtime] User ".concat(userId, " denied model subscription for ").concat(modelName, ": list permission denied"));
+                        return [2 /*return*/];
+                    }
+                    counts.model += 1;
+                    return [4 /*yield*/, socket.join("model:".concat(modelName))];
+                case 2:
+                    _a.sent();
+                    logInfo("[realtime] User ".concat(userId, " subscribed to model:").concat(modelName));
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    socket.on("unsubscribe:model", function (modelName) { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!(typeof modelName === "string" && modelName.length > 0)) return [3 /*break*/, 2];
+                    return [4 /*yield*/, socket.leave("model:".concat(modelName))];
+                case 1:
+                    _a.sent();
+                    counts.model = Math.max(0, counts.model - 1);
+                    logInfo("[realtime] User ".concat(userId, " unsubscribed from model:").concat(modelName));
+                    _a.label = 2;
+                case 2: return [2 /*return*/];
+            }
+        });
+    }); });
+    socket.on("subscribe:document", function (payload) { return __awaiter(void 0, void 0, void 0, function () {
+        var entry, room;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!(payload === null || payload === void 0 ? void 0 : payload.collection) ||
+                        !(payload === null || payload === void 0 ? void 0 : payload.id) ||
+                        typeof payload.collection !== "string" ||
+                        typeof payload.id !== "string") {
+                        return [2 /*return*/];
+                    }
+                    if (counts.document >= exports.MAX_DOCUMENT_SUBSCRIPTIONS) {
+                        logInfo("[realtime] User ".concat(userId, " hit document subscription limit"));
+                        return [2 /*return*/];
+                    }
+                    entry = (0, registry_1.findRegistryEntryByRoutePath)(payload.collection);
+                    if (!entry) {
+                        logInfo("[realtime] User ".concat(userId, " denied document subscription: ") +
+                            "collection \"".concat(payload.collection, "\" not registered"));
+                        return [2 /*return*/];
+                    }
+                    return [4 /*yield*/, canSubscribe(entry, "read", user)];
+                case 1:
+                    if (!(_a.sent())) {
+                        logInfo("[realtime] User ".concat(userId, " denied document subscription for ") +
+                            "".concat(payload.collection, "/").concat(payload.id, ": read permission denied"));
+                        return [2 /*return*/];
+                    }
+                    if (entry.config.roomStrategy === "owner" && !isAdmin) {
+                        logInfo("[realtime] User ".concat(userId, " denied document subscription for ") +
+                            "".concat(payload.collection, "/").concat(payload.id, ": owner strategy requires admin"));
+                        return [2 /*return*/];
+                    }
+                    counts.document += 1;
+                    room = "document:".concat(payload.collection, ":").concat(payload.id);
+                    return [4 /*yield*/, socket.join(room)];
+                case 2:
+                    _a.sent();
+                    logInfo("[realtime] User ".concat(userId, " subscribed to ").concat(room));
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    socket.on("unsubscribe:document", function (payload) { return __awaiter(void 0, void 0, void 0, function () {
+        var room;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!((payload === null || payload === void 0 ? void 0 : payload.collection) && (payload === null || payload === void 0 ? void 0 : payload.id))) return [3 /*break*/, 2];
+                    room = "document:".concat(payload.collection, ":").concat(payload.id);
+                    return [4 /*yield*/, socket.leave(room)];
+                case 1:
+                    _a.sent();
+                    counts.document = Math.max(0, counts.document - 1);
+                    logInfo("[realtime] User ".concat(userId, " unsubscribed from ").concat(room));
+                    _a.label = 2;
+                case 2: return [2 /*return*/];
+            }
+        });
+    }); });
+    socket.on("subscribe:query", function (payload) { return __awaiter(void 0, void 0, void 0, function () {
+        var entry, query, queryId;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!(payload === null || payload === void 0 ? void 0 : payload.collection) ||
+                        !(payload === null || payload === void 0 ? void 0 : payload.query) ||
+                        typeof payload.collection !== "string" ||
+                        typeof payload.query !== "object" ||
+                        Array.isArray(payload.query)) {
+                        return [2 /*return*/];
+                    }
+                    if (counts.query >= exports.MAX_QUERY_SUBSCRIPTIONS) {
+                        logInfo("[realtime] User ".concat(userId, " hit query subscription limit"));
+                        return [2 /*return*/];
+                    }
+                    entry = (0, registry_1.findRegistryEntryByRoutePath)(payload.collection);
+                    if (!entry) {
+                        logInfo("[realtime] User ".concat(userId, " denied query subscription: ") +
+                            "collection \"".concat(payload.collection, "\" not registered"));
+                        return [2 /*return*/];
+                    }
+                    return [4 /*yield*/, getAuthorizedQuery(entry, __assign({}, payload.query), user)];
+                case 1:
+                    query = _a.sent();
+                    if (!query) {
+                        logInfo("[realtime] User ".concat(userId, " denied query subscription for ").concat(payload.collection, ": ") +
+                            "list permission or query filter denied");
+                        return [2 /*return*/];
+                    }
+                    if (entry.config.roomStrategy === "owner" && !isAdmin) {
+                        if (!userId) {
+                            return [2 /*return*/];
+                        }
+                        query = __assign(__assign({}, query), { ownerId: userId });
+                    }
+                    queryId = (0, queryStore_1.computeQueryId)(payload.collection, query);
+                    (0, queryStore_1.addQuerySubscription)(socket.id, payload.collection, query, queryId);
+                    counts.query += 1;
+                    return [4 /*yield*/, socket.join("query:".concat(queryId))];
+                case 2:
+                    _a.sent();
+                    socket.emit("query:subscribed", {
+                        clientQueryId: payload.queryId,
+                        collection: payload.collection,
+                        queryId: queryId,
+                    });
+                    logInfo("[realtime] User ".concat(userId, " subscribed to query:").concat(queryId, " on ").concat(payload.collection));
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    socket.on("unsubscribe:query", function (payload) { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!(payload === null || payload === void 0 ? void 0 : payload.queryId)) return [3 /*break*/, 2];
+                    (0, queryStore_1.removeQuerySubscription)(socket.id, payload.queryId);
+                    return [4 /*yield*/, socket.leave("query:".concat(payload.queryId))];
+                case 1:
+                    _a.sent();
+                    counts.query = Math.max(0, counts.query - 1);
+                    logInfo("[realtime] User ".concat(userId, " unsubscribed from query:").concat(payload.queryId));
+                    _a.label = 2;
+                case 2: return [2 /*return*/];
+            }
+        });
+    }); });
+    socket.on("disconnect", function () {
+        (0, queryStore_1.removeAllSocketQueries)(socket.id);
+        logInfo("[realtime] User ".concat(userId, " disconnected"));
+    });
+};
+exports.installRealtimeSocketHandlers = installRealtimeSocketHandlers;
+/**
+ * TerrenoPlugin that provides real-time sync via Socket.io and MongoDB change streams.
+ *
+ * Attaches a Socket.io server to the HTTP server created by TerrenoApp.start(),
+ * sets up JWT authentication for socket connections, manages room subscriptions
+ * (model, document, and query rooms), and starts a change stream watcher that
+ * emits events to connected clients.
+ *
+ * ## Subscription types
+ *
+ * - **Model rooms**: `subscribe:model` / `unsubscribe:model` — receive all events for a collection
+ * - **Document rooms**: `subscribe:document` / `unsubscribe:document` — receive events for a single document
+ * - **Query rooms**: `subscribe:query` / `unsubscribe:query` — receive events matching a MongoDB query
+ *
+ * @example
+ * ```typescript
+ * const app = new TerrenoApp({
+ *   userModel: User,
+ *   realtime: { debug: true },
+ * })
+ *   .register(todoRouter)   // todoRouter has realtime config
+ *   .start();
+ * ```
+ */
+var RealtimeApp = /** @class */ (function () {
+    function RealtimeApp(config) {
+        if (config === void 0) { config = {}; }
+        this.io = null;
+        this.config = config;
+    }
+    /**
+     * Register routes and middleware. Adds a /realtime/health endpoint.
+     */
+    RealtimeApp.prototype.register = function (app) {
+        var _this = this;
+        app.get("/realtime/health", function (_req, res) {
+            var _a, _b, _c, _d;
+            var connected = (_c = (_b = (_a = _this.io) === null || _a === void 0 ? void 0 : _a.engine) === null || _b === void 0 ? void 0 : _b.clientsCount) !== null && _c !== void 0 ? _c : 0;
+            res.json({
+                clients: connected,
+                debug: (_d = _this.config.debug) !== null && _d !== void 0 ? _d : false,
+                status: _this.io ? "running" : "not_started",
+            });
+        });
+    };
+    /**
+     * Called after the HTTP server is created. Sets up Socket.io, auth, rooms,
+     * and starts the change stream watcher.
+     */
+    RealtimeApp.prototype.onServerCreated = function (server) {
+        var _a, _b, _c;
+        var debug = (_a = this.config.debug) !== null && _a !== void 0 ? _a : false;
+        var logInfo = function (message) {
+            if (debug) {
+                logger_1.logger.info(message);
+            }
+        };
+        try {
+            logInfo("[realtime] Setting up Socket.io server...");
+            this.io = new socket_io_1.Server(server, {
+                cors: (_b = this.config.cors) !== null && _b !== void 0 ? _b : {
+                    methods: ["GET", "POST"],
+                    origin: "*",
+                },
+            });
+            // JWT authentication middleware
+            var tokenSecret = (_c = this.config.tokenSecret) !== null && _c !== void 0 ? _c : process.env.TOKEN_SECRET;
+            if (!tokenSecret) {
+                throw new Error("[realtime] TOKEN_SECRET is required for socket authentication. " +
+                    "Set process.env.TOKEN_SECRET or pass tokenSecret in RealtimeAppOptions.");
+            }
+            this.io.use((0, socketio_jwt_1.authorize)({
+                secret: tokenSecret,
+            }));
+            logInfo("[realtime] JWT authorization middleware added");
+            // Configure adapter for multi-instance deployments
+            this.setupAdapter(logInfo);
+            // Connection handling
+            this.io.on("connection", function (socket) {
+                try {
+                    // socketio-jwt's authorize middleware adds `decodedToken` at runtime; cast through
+                    // RealtimeSocketLike (a structural subset) to keep socket handler logic testable.
+                    (0, exports.installRealtimeSocketHandlers)(socket, { logInfo: logInfo });
+                }
+                catch (error) {
+                    logger_1.logger.error("[realtime] Error handling connection: ".concat(error));
+                    Sentry.captureException(error);
+                }
+            });
+            this.io.on("connect_error", function (error) {
+                logger_1.logger.error("[realtime] Connection error: ".concat(error.message));
+                Sentry.captureException(error);
+            });
+            // Start the change stream watcher
+            (0, changeStreamWatcher_1.startChangeStreamWatcher)(this.io, this.config.changeStream, debug);
+            logInfo("[realtime] Socket.io server setup complete");
+        }
+        catch (error) {
+            logger_1.logger.error("[realtime] Failed to set up Socket.io: ".concat(error));
+            Sentry.captureException(error);
+            throw error;
+        }
+    };
+    /**
+     * Get the Socket.io server instance.
+     */
+    RealtimeApp.prototype.getIo = function () {
+        return this.io;
+    };
+    /**
+     * Gracefully shut down the real-time server.
+     */
+    RealtimeApp.prototype.close = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var error_2;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        _a.trys.push([0, 4, , 5]);
+                        return [4 /*yield*/, (0, changeStreamWatcher_1.stopChangeStreamWatcher)()];
+                    case 1:
+                        _a.sent();
+                        if (!this.io) return [3 /*break*/, 3];
+                        return [4 /*yield*/, this.io.close()];
+                    case 2:
+                        _a.sent();
+                        this.io = null;
+                        _a.label = 3;
+                    case 3: return [3 /*break*/, 5];
+                    case 4:
+                        error_2 = _a.sent();
+                        logger_1.logger.error("[realtime] Error closing: ".concat(error_2));
+                        return [3 /*break*/, 5];
+                    case 5: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    RealtimeApp.prototype.setupAdapter = function (logInfo) {
+        var _a, _b, _c;
+        if (!this.io) {
+            return;
+        }
+        var adapter = (_a = this.config.adapter) !== null && _a !== void 0 ? _a : "none";
+        if (adapter === "redis") {
+            var redisUrl = (_c = (_b = this.config.redisUrl) !== null && _b !== void 0 ? _b : process.env.VALKEY_URL) !== null && _c !== void 0 ? _c : process.env.REDIS_URL;
+            if (redisUrl) {
+                logInfo("[realtime] Redis adapter configured with URL: ".concat((0, exports.redactCredentials)(redisUrl)));
+                // Redis adapter must be configured externally by the consuming app
+                // since @socket.io/redis-adapter and ioredis are optional peer dependencies.
+                // Use realtimeApp.getIo() to access the Socket.io instance and call
+                // io.adapter(createRedisAdapter(pubClient, subClient))
+                logger_1.logger.info("[realtime] To enable Redis adapter, configure it after server creation via getIo(). " +
+                    "See @socket.io/redis-adapter docs.");
+            }
+            else {
+                logger_1.logger.warn("[realtime] Redis adapter requested but no VALKEY_URL or REDIS_URL found");
+            }
+        }
+        // 'none' — no adapter, single instance mode
+    };
+    return RealtimeApp;
+}());
+exports.RealtimeApp = RealtimeApp;