@terreno/api 0.13.2 → 0.14.0

package/src/realtime/realtimeApp.ts

@@ -0,0 +1,478 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: Socket.io handler signatures require dynamic args
+import type http from "node:http";
+import * as Sentry from "@sentry/bun";
+import {authorize} from "@thream/socketio-jwt";
+import type express from "express";
+import {Server, type Socket} from "socket.io";
+
+import type {User} from "../auth";
+import {logger} from "../logger";
+import {checkPermissions} from "../permissions";
+import type {TerrenoPlugin} from "../terrenoPlugin";
+import {startChangeStreamWatcher, stopChangeStreamWatcher} from "./changeStreamWatcher";
+import {
+  addQuerySubscription,
+  computeQueryId,
+  removeAllSocketQueries,
+  removeQuerySubscription,
+} from "./queryStore";
+import {findRegistryEntryByRoutePath, type RealtimeRegistryEntry} from "./registry";
+import {getSocketUser, type SocketWithDecodedToken} from "./socketUser";
+import type {DocumentSubscription, QuerySubscription, RealtimeAppOptions} from "./types";
+
+/**
+ * Caps on per-socket subscriptions. Prevents a malicious or buggy client from
+ * exhausting server memory by opening unbounded subscriptions.
+ */
+export const MAX_MODEL_SUBSCRIPTIONS = 50;
+export const MAX_DOCUMENT_SUBSCRIPTIONS = 500;
+export 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 const redactCredentials = (url: string): string => {
+  try {
+    const 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(`${parsed.protocol}//`, `${parsed.protocol}//***@`);
+    }
+    return parsed.toString();
+  } catch {
+    return url.replace(/^(\w+):\/\/[^@/]*@/, "$1://***@");
+  }
+};
+
+/**
+ * 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;
+  // biome-ignore lint/suspicious/noExplicitAny: Socket.io event handlers accept arbitrary argument shapes per event name
+  on: (event: string, handler: (...args: any[]) => any) => void;
+}
+
+const canSubscribe = async (
+  entry: RealtimeRegistryEntry,
+  method: "list" | "read",
+  user?: User
+): Promise<boolean> => {
+  const permissions = entry.options.permissions[method];
+  return checkPermissions(method, permissions, user);
+};
+
+const getAuthorizedQuery = async (
+  entry: RealtimeRegistryEntry,
+  query: Record<string, any>,
+  user?: User
+): Promise<Record<string, any> | null> => {
+  if (!(await canSubscribe(entry, "list", user))) {
+    return null;
+  }
+
+  if (!entry.options.queryFilter) {
+    return query;
+  }
+
+  let filteredQuery: Record<string, any> | null;
+  try {
+    filteredQuery = await entry.options.queryFilter(user, query);
+  } catch (error) {
+    logger.error(
+      `[realtime] queryFilter threw for ${entry.modelName}/list: ${error}. Denying query subscription.`
+    );
+    Sentry.captureException(error);
+    return null;
+  }
+
+  if (filteredQuery === null) {
+    return null;
+  }
+
+  return {...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)
+ */
+export const installRealtimeSocketHandlers = (
+  socket: RealtimeSocketLike,
+  options: {logInfo?: (msg: string) => void} = {}
+): void => {
+  const logInfo = options.logInfo ?? ((): void => {});
+  const userId = socket.decodedToken?.id;
+  const isAdmin = socket.decodedToken?.admin === true;
+  const user = getSocketUser(socket);
+
+  const counts = {document: 0, model: 0, query: 0};
+
+  const joinUserRooms = async (): Promise<void> => {
+    if (userId) {
+      await socket.join(`user:${userId}`);
+      await socket.join("authenticated");
+      logInfo(`[realtime] User ${userId} connected`);
+    }
+    if (isAdmin) {
+      await socket.join("admin");
+      logInfo(`[realtime] Admin user ${userId} joined admin room`);
+    }
+  };
+
+  // Fire-and-forget — there is nothing useful for the caller to await.
+  void joinUserRooms();
+
+  socket.on("subscribe:model", async (modelName: string): Promise<void> => {
+    if (typeof modelName !== "string" || modelName.length === 0) {
+      return;
+    }
+    if (counts.model >= MAX_MODEL_SUBSCRIPTIONS) {
+      logInfo(`[realtime] User ${userId} hit model subscription limit`);
+      return;
+    }
+
+    const entry = findRegistryEntryByRoutePath(modelName);
+    if (!entry) {
+      logInfo(
+        `[realtime] User ${userId} denied model subscription: collection "${modelName}" not registered`
+      );
+      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 ${userId} denied model subscription for ${modelName}: ` +
+          "owner strategy restricts model room to admins"
+      );
+      return;
+    }
+
+    if (!(await canSubscribe(entry, "list", user))) {
+      logInfo(
+        `[realtime] User ${userId} denied model subscription for ${modelName}: list permission denied`
+      );
+      return;
+    }
+
+    counts.model += 1;
+    await socket.join(`model:${modelName}`);
+    logInfo(`[realtime] User ${userId} subscribed to model:${modelName}`);
+  });
+
+  socket.on("unsubscribe:model", async (modelName: string): Promise<void> => {
+    if (typeof modelName === "string" && modelName.length > 0) {
+      await socket.leave(`model:${modelName}`);
+      counts.model = Math.max(0, counts.model - 1);
+      logInfo(`[realtime] User ${userId} unsubscribed from model:${modelName}`);
+    }
+  });
+
+  socket.on("subscribe:document", async (payload: DocumentSubscription): Promise<void> => {
+    if (
+      !payload?.collection ||
+      !payload?.id ||
+      typeof payload.collection !== "string" ||
+      typeof payload.id !== "string"
+    ) {
+      return;
+    }
+    if (counts.document >= MAX_DOCUMENT_SUBSCRIPTIONS) {
+      logInfo(`[realtime] User ${userId} hit document subscription limit`);
+      return;
+    }
+
+    const entry = findRegistryEntryByRoutePath(payload.collection);
+    if (!entry) {
+      logInfo(
+        `[realtime] User ${userId} denied document subscription: ` +
+          `collection "${payload.collection}" not registered`
+      );
+      return;
+    }
+
+    if (!(await canSubscribe(entry, "read", user))) {
+      logInfo(
+        `[realtime] User ${userId} denied document subscription for ` +
+          `${payload.collection}/${payload.id}: read permission denied`
+      );
+      return;
+    }
+
+    if (entry.config.roomStrategy === "owner" && !isAdmin) {
+      logInfo(
+        `[realtime] User ${userId} denied document subscription for ` +
+          `${payload.collection}/${payload.id}: owner strategy requires admin`
+      );
+      return;
+    }
+
+    counts.document += 1;
+    const room = `document:${payload.collection}:${payload.id}`;
+    await socket.join(room);
+    logInfo(`[realtime] User ${userId} subscribed to ${room}`);
+  });
+
+  socket.on("unsubscribe:document", async (payload: DocumentSubscription): Promise<void> => {
+    if (payload?.collection && payload?.id) {
+      const room = `document:${payload.collection}:${payload.id}`;
+      await socket.leave(room);
+      counts.document = Math.max(0, counts.document - 1);
+      logInfo(`[realtime] User ${userId} unsubscribed from ${room}`);
+    }
+  });
+
+  socket.on("subscribe:query", async (payload: QuerySubscription): Promise<void> => {
+    if (
+      !payload?.collection ||
+      !payload?.query ||
+      typeof payload.collection !== "string" ||
+      typeof payload.query !== "object" ||
+      Array.isArray(payload.query)
+    ) {
+      return;
+    }
+    if (counts.query >= MAX_QUERY_SUBSCRIPTIONS) {
+      logInfo(`[realtime] User ${userId} hit query subscription limit`);
+      return;
+    }
+
+    const entry = findRegistryEntryByRoutePath(payload.collection);
+    if (!entry) {
+      logInfo(
+        `[realtime] User ${userId} denied query subscription: ` +
+          `collection "${payload.collection}" not registered`
+      );
+      return;
+    }
+
+    let query = await getAuthorizedQuery(entry, {...payload.query}, user);
+    if (!query) {
+      logInfo(
+        `[realtime] User ${userId} denied query subscription for ${payload.collection}: ` +
+          "list permission or query filter denied"
+      );
+      return;
+    }
+
+    if (entry.config.roomStrategy === "owner" && !isAdmin) {
+      if (!userId) {
+        return;
+      }
+      query = {...query, ownerId: userId};
+    }
+
+    const queryId = computeQueryId(payload.collection, query);
+
+    addQuerySubscription(socket.id, payload.collection, query, queryId);
+    counts.query += 1;
+    await socket.join(`query:${queryId}`);
+    socket.emit("query:subscribed", {
+      clientQueryId: payload.queryId,
+      collection: payload.collection,
+      queryId,
+    });
+    logInfo(`[realtime] User ${userId} subscribed to query:${queryId} on ${payload.collection}`);
+  });
+
+  socket.on("unsubscribe:query", async (payload: {queryId: string}): Promise<void> => {
+    if (payload?.queryId) {
+      removeQuerySubscription(socket.id, payload.queryId);
+      await socket.leave(`query:${payload.queryId}`);
+      counts.query = Math.max(0, counts.query - 1);
+      logInfo(`[realtime] User ${userId} unsubscribed from query:${payload.queryId}`);
+    }
+  });
+
+  socket.on("disconnect", () => {
+    removeAllSocketQueries(socket.id);
+    logInfo(`[realtime] User ${userId} disconnected`);
+  });
+};
+
+/**
+ * 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 class RealtimeApp implements TerrenoPlugin {
+  private io: Server | null = null;
+  private config: RealtimeAppOptions;
+
+  constructor(config: RealtimeAppOptions = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Register routes and middleware. Adds a /realtime/health endpoint.
+   */
+  register(app: express.Application): void {
+    app.get("/realtime/health", (_req, res) => {
+      const connected = this.io?.engine?.clientsCount ?? 0;
+      res.json({
+        clients: connected,
+        debug: this.config.debug ?? 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.
+   */
+  onServerCreated(server: http.Server): void {
+    const debug = this.config.debug ?? false;
+
+    const logInfo = (message: string): void => {
+      if (debug) {
+        logger.info(message);
+      }
+    };
+
+    try {
+      logInfo("[realtime] Setting up Socket.io server...");
+
+      this.io = new Server(server, {
+        cors: this.config.cors ?? {
+          methods: ["GET", "POST"],
+          origin: "*",
+        },
+      });
+
+      // JWT authentication middleware
+      const tokenSecret = this.config.tokenSecret ?? 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(
+        authorize({
+          secret: tokenSecret,
+        })
+      );
+
+      logInfo("[realtime] JWT authorization middleware added");
+
+      // Configure adapter for multi-instance deployments
+      this.setupAdapter(logInfo);
+
+      // Connection handling
+      this.io.on("connection", (socket: Socket): void => {
+        try {
+          // socketio-jwt's authorize middleware adds `decodedToken` at runtime; cast through
+          // RealtimeSocketLike (a structural subset) to keep socket handler logic testable.
+          installRealtimeSocketHandlers(socket as unknown as RealtimeSocketLike, {logInfo});
+        } catch (error) {
+          logger.error(`[realtime] Error handling connection: ${error}`);
+          Sentry.captureException(error);
+        }
+      });
+
+      this.io.on("connect_error", (error: Error) => {
+        logger.error(`[realtime] Connection error: ${error.message}`);
+        Sentry.captureException(error);
+      });
+
+      // Start the change stream watcher
+      startChangeStreamWatcher(this.io, this.config.changeStream, debug);
+
+      logInfo("[realtime] Socket.io server setup complete");
+    } catch (error) {
+      logger.error(`[realtime] Failed to set up Socket.io: ${error}`);
+      Sentry.captureException(error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get the Socket.io server instance.
+   */
+  getIo(): Server | null {
+    return this.io;
+  }
+
+  /**
+   * Gracefully shut down the real-time server.
+   */
+  async close(): Promise<void> {
+    try {
+      await stopChangeStreamWatcher();
+      if (this.io) {
+        await this.io.close();
+        this.io = null;
+      }
+    } catch (error) {
+      logger.error(`[realtime] Error closing: ${error}`);
+    }
+  }
+
+  private setupAdapter(logInfo: (msg: string) => void): void {
+    if (!this.io) {
+      return;
+    }
+
+    const adapter = this.config.adapter ?? "none";
+
+    if (adapter === "redis") {
+      const redisUrl = this.config.redisUrl ?? process.env.VALKEY_URL ?? process.env.REDIS_URL;
+      if (redisUrl) {
+        logInfo(`[realtime] Redis adapter configured with URL: ${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.info(
+          "[realtime] To enable Redis adapter, configure it after server creation via getIo(). " +
+            "See @socket.io/redis-adapter docs."
+        );
+      } else {
+        logger.warn("[realtime] Redis adapter requested but no VALKEY_URL or REDIS_URL found");
+      }
+    }
+    // 'none' — no adapter, single instance mode
+  }
+}

package/src/realtime/registry.ts

@@ -0,0 +1,64 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: model router options are generic across all models
+import type {ModelRouterOptions} from "../api";
+import type {RealtimeConfig} from "./types";
+
+/**
+ * A registered model with real-time sync configuration.
+ */
+export interface RealtimeRegistryEntry {
+  /** Mongoose model name (e.g. "Todo") */
+  modelName: string;
+  /** Route path (e.g. "/todos") */
+  routePath: string;
+  /** Collection name in MongoDB (e.g. "todos") */
+  collectionName: string;
+  /** Real-time configuration from modelRouter options */
+  config: RealtimeConfig;
+  /**
+   * Full modelRouter options (for responseHandler, permissions, etc.).
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: registry stores heterogeneous models — narrowing the generic is not useful at the registry level
+  options: ModelRouterOptions<any>;
+}
+
+const realtimeRegistry: RealtimeRegistryEntry[] = [];
+
+/**
+ * Register a model for real-time sync. Called automatically by modelRouter
+ * when the `realtime` option is provided.
+ */
+export const registerRealtime = (entry: RealtimeRegistryEntry): void => {
+  realtimeRegistry.push(entry);
+};
+
+/**
+ * Get all registered real-time models.
+ */
+export const getRealtimeRegistry = (): RealtimeRegistryEntry[] => realtimeRegistry;
+
+/**
+ * Find a registry entry by MongoDB collection name.
+ */
+export const findRegistryEntryByCollection = (
+  collectionName: string
+): RealtimeRegistryEntry | undefined => {
+  return realtimeRegistry.find((entry) => entry.collectionName === collectionName);
+};
+
+/**
+ * Find a registry entry by route path / collection tag (e.g. "todos").
+ */
+export const findRegistryEntryByRoutePath = (
+  collection: string
+): RealtimeRegistryEntry | undefined => {
+  return realtimeRegistry.find(
+    (entry) => entry.routePath === `/${collection}` || entry.routePath === collection
+  );
+};
+
+/**
+ * Clear the registry (for testing).
+ */
+export const clearRealtimeRegistry = (): void => {
+  realtimeRegistry.length = 0;
+};

package/src/realtime/socketUser.ts

@@ -0,0 +1,25 @@
+import type {User} from "../auth";
+
+export interface DecodedRealtimeToken {
+  admin?: boolean;
+  id?: string;
+  isAnonymous?: boolean;
+}
+
+export interface SocketWithDecodedToken {
+  decodedToken?: DecodedRealtimeToken;
+}
+
+export const getSocketUser = (socket: SocketWithDecodedToken): User | undefined => {
+  const userId = socket.decodedToken?.id;
+  if (!userId) {
+    return undefined;
+  }
+
+  return {
+    _id: userId,
+    admin: socket.decodedToken?.admin === true,
+    id: userId,
+    isAnonymous: socket.decodedToken?.isAnonymous,
+  };
+};

package/src/realtime/types.ts

@@ -0,0 +1,112 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: realtime config callbacks receive dynamic document shapes
+import type express from "express";
+
+/**
+ * Configuration for real-time sync on a modelRouter.
+ * Determines which CRUD methods emit WebSocket events and how they are routed.
+ */
+export interface RealtimeConfig {
+  /** Which CRUD methods should emit real-time sync events */
+  methods: Array<"create" | "update" | "delete">;
+  /**
+   * Strategy for determining which Socket.io rooms receive events.
+   * - 'owner': emit to `user:{doc.ownerId}` room
+   * - 'model': emit to `model:{modelName}` room (clients must subscribe)
+   * - 'broadcast': emit to all authenticated sockets
+   * - function: custom room resolver returning room name(s)
+   */
+  roomStrategy:
+    | "owner"
+    | "model"
+    | "broadcast"
+    // biome-ignore lint/suspicious/noExplicitAny: doc is an arbitrary Mongoose document; consumers cast to their model type
+    | ((doc: any, method: string, req: express.Request) => string[]);
+  /** Custom serializer for real-time events. Falls back to the modelRouter responseHandler. */
+  // biome-ignore lint/suspicious/noExplicitAny: doc shape and return value are consumer-defined per model
+  realtimeResponseHandler?: (doc: any, method: string) => any;
+}
+
+/**
+ * A real-time sync event emitted to clients via WebSocket.
+ */
+export interface RealtimeEvent {
+  /** Mongoose model name (e.g. "Todo") */
+  model: string;
+  /** Route path used as tag type (e.g. "todos") */
+  collection: string;
+  /** The CRUD method that triggered this event */
+  method: "create" | "update" | "delete";
+  /** Document ID */
+  id: string;
+  /** Serialized document data (omitted for hard deletes) */
+  // biome-ignore lint/suspicious/noExplicitAny: emitted document shape varies by model and serializer
+  data?: any;
+  /** Fields that were updated (for update events from change streams) */
+  updatedFields?: string[];
+  /** Epoch milliseconds when the event was generated */
+  timestamp: number;
+}
+
+/**
+ * Configuration for the MongoDB change stream watcher.
+ */
+export interface ChangeStreamConfig {
+  /** Collections to never watch (e.g. "socketio", "sessions") */
+  ignoredCollections?: string[];
+  /** Operation types to ignore */
+  ignoredOperations?: string[];
+  /** Non-modelRouter collections to watch (emits raw events) */
+  additionalCollections?: string[];
+  /** Change stream batch size (default: 50) */
+  batchSize?: number;
+  /** Full document mode (default: "updateLookup") */
+  fullDocument?: "updateLookup" | "whenAvailable";
+}
+
+/**
+ * Options for the RealtimeApp plugin.
+ */
+export interface RealtimeAppOptions {
+  /** Change stream watcher configuration */
+  changeStream?: ChangeStreamConfig;
+  /** CORS configuration for Socket.io */
+  cors?: {origin: string | string[]; methods?: string[]};
+  /**
+   * Socket.io adapter for multi-instance deployments.
+   * - 'none': single-instance mode, no adapter (default)
+   * - 'redis': use Redis adapter (requires redisUrl or VALKEY_URL env var)
+   *
+   * For MongoDB adapter or custom adapters, configure the Socket.io instance
+   * directly via getIo() after server creation.
+   */
+  adapter?: "redis" | "none";
+  /** Redis URL for the Redis adapter */
+  redisUrl?: string;
+  /** JWT secret for socket authentication (default: process.env.TOKEN_SECRET) */
+  tokenSecret?: string;
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * Payload sent by the client to subscribe to a single document's changes.
+ */
+export interface DocumentSubscription {
+  /** Collection tag (e.g. "todos") */
+  collection: string;
+  /** Document ID */
+  id: string;
+}
+
+/**
+ * Payload sent by the client to subscribe to a query-filtered list.
+ */
+export interface QuerySubscription {
+  /** Collection tag (e.g. "todos") */
+  collection: string;
+  /** MongoDB-style query filter (e.g. {completed: false}) */
+  // biome-ignore lint/suspicious/noExplicitAny: MongoDB query filter values are arbitrary user-supplied JSON
+  query: Record<string, any>;
+  /** Client-provided queryId (ignored — server computes a canonical ID) */
+  queryId?: string;
+}