@zero-server/realtime 0.9.1 → 0.9.3

package/lib/ws/room.js

@@ -0,0 +1,223 @@
+/**
+ * @module ws/room
+ * @description WebSocket room/channel manager.
+ *              Provides broadcast, room-based messaging, and connection
+ *              registry for WebSocket connections.
+ */
+
+/**
+ * Manages a pool of WebSocket connections with room-based grouping.
+ *
+ * @example
+ *   const pool = new WebSocketPool();
+ *   app.ws('/chat', (ws, req) => {
+ *       pool.add(ws);
+ *       pool.join(ws, 'general');
+ *       ws.on('message', msg => pool.toRoom('general', msg));
+ *       ws.on('close', () => pool.remove(ws));
+ *   });
+ */
+class WebSocketPool
+{
+    /** @constructor */
+    constructor()
+    {
+        /** @type {Set<import('./connection')>} All active connections. */
+        this._connections = new Set();
+        /** @type {Map<string, Set<import('./connection')>>} Room → connection sets. */
+        this._rooms = new Map();
+    }
+
+    /**
+     * Add a connection to the pool.
+     * @param {import('./connection')} ws - WebSocket connection.
+     * @returns {WebSocketPool} this
+     */
+    add(ws)
+    {
+        this._connections.add(ws);
+
+        // Auto-remove on close
+        ws.once('close', () => this.remove(ws));
+
+        return this;
+    }
+
+    /**
+     * Remove a connection from the pool and all rooms.
+     * @param {import('./connection')} ws - WebSocket connection.
+     * @returns {WebSocketPool} this
+     */
+    remove(ws)
+    {
+        this._connections.delete(ws);
+        for (const [room, members] of this._rooms)
+        {
+            members.delete(ws);
+            if (members.size === 0) this._rooms.delete(room);
+        }
+        return this;
+    }
+
+    /**
+     * Join a connection to a room.
+     * @param {import('./connection')} ws - WebSocket connection.
+     * @param {string} room - Room name.
+     * @returns {WebSocketPool} this
+     */
+    join(ws, room)
+    {
+        if (!this._rooms.has(room)) this._rooms.set(room, new Set());
+        this._rooms.get(room).add(ws);
+        return this;
+    }
+
+    /**
+     * Remove a connection from a room.
+     * @param {import('./connection')} ws - WebSocket connection.
+     * @param {string} room - Room name.
+     * @returns {WebSocketPool} this
+     */
+    leave(ws, room)
+    {
+        const members = this._rooms.get(room);
+        if (members)
+        {
+            members.delete(ws);
+            if (members.size === 0) this._rooms.delete(room);
+        }
+        return this;
+    }
+
+    /**
+     * Get all rooms a connection belongs to.
+     * @param {import('./connection')} ws - WebSocket connection.
+     * @returns {string[]} Room names the connection belongs to.
+     */
+    roomsOf(ws)
+    {
+        const result = [];
+        for (const [room, members] of this._rooms)
+        {
+            if (members.has(ws)) result.push(room);
+        }
+        return result;
+    }
+
+    /**
+     * Broadcast a message to ALL connected clients.
+     * @param {string|Buffer} data   - Payload.
+     * @param {import('./connection')} [exclude] - Optional connection to exclude (e.g. the sender).
+     */
+    broadcast(data, exclude)
+    {
+        for (const ws of this._connections)
+        {
+            if (ws !== exclude && ws.readyState === 1) ws.send(data);
+        }
+    }
+
+    /**
+     * Broadcast a JSON message to ALL connected clients.
+     * @param {*} obj - Value to serialise.
+     * @param {import('./connection')} [exclude] - Connection(s) to exclude.
+     */
+    broadcastJSON(obj, exclude)
+    {
+        const msg = JSON.stringify(obj);
+        this.broadcast(msg, exclude);
+    }
+
+    /**
+     * Send a message to all connections in a specific room.
+     * @param {string} room          - Room name.
+     * @param {string|Buffer} data   - Payload.
+     * @param {import('./connection')} [exclude] - Connection(s) to exclude.
+     */
+    toRoom(room, data, exclude)
+    {
+        const members = this._rooms.get(room);
+        if (!members) return;
+        for (const ws of members)
+        {
+            if (ws !== exclude && ws.readyState === 1) ws.send(data);
+        }
+    }
+
+    /**
+     * Send a JSON message to all connections in a specific room.
+     * @param {string} room - Room name.
+     * @param {*}      obj - Data object to send.
+     * @param {import('./connection')} [exclude] - Connection(s) to exclude.
+     */
+    toRoomJSON(room, obj, exclude)
+    {
+        this.toRoom(room, JSON.stringify(obj), exclude);
+    }
+
+    /**
+     * Get all connections in a room.
+     * @param {string} room - Room name.
+     * @returns {import('./connection')[]} Connections in the room (empty array if the room does not exist).
+     */
+    in(room)
+    {
+        const members = this._rooms.get(room);
+        return members ? Array.from(members) : [];
+    }
+
+    /**
+     * Total number of active connections.
+     * @type {number}
+     */
+    get size()
+    {
+        return this._connections.size;
+    }
+
+    /**
+     * Number of connections in a specific room.
+     * @param {string} room - Room name.
+     * @returns {number} Number of connections in the room.
+     */
+    roomSize(room)
+    {
+        const members = this._rooms.get(room);
+        return members ? members.size : 0;
+    }
+
+    /**
+     * List all active room names.
+     * @returns {string[]} Array of room names.
+     */
+    get rooms()
+    {
+        return Array.from(this._rooms.keys());
+    }
+
+    /**
+     * Get all active connections.
+     * @returns {import('./connection')[]} Array of connections in the pool.
+     */
+    get clients()
+    {
+        return Array.from(this._connections);
+    }
+
+    /**
+     * Close all connections gracefully.
+     * @param {number} [code=1001] - Close code.
+     * @param {string} [reason]    - Close reason.
+     */
+    closeAll(code = 1001, reason = 'Server shutdown')
+    {
+        for (const ws of this._connections)
+        {
+            ws.close(code, reason);
+        }
+        this._connections.clear();
+        this._rooms.clear();
+    }
+}
+
+module.exports = WebSocketPool;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zero-server/realtime",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "WebSocket connection + room manager and SSE stream controller.",
   "keywords": [
     "zero-server",
@@ -20,6 +20,8 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "lib",
+    "types",
     "index.js",
     "index.d.ts",
     "README.md",
@@ -42,7 +44,12 @@
     "access": "public"
   },
   "sideEffects": false,
-  "dependencies": {
-    "@zero-server/sdk": "0.9.1"
+  "peerDependencies": {
+    "@zero-server/sdk": ">=0.9.3"
+  },
+  "peerDependenciesMeta": {
+    "@zero-server/sdk": {
+      "optional": true
+    }
   }
 }

package/types/app.d.ts

@@ -0,0 +1,223 @@
+/// <reference types="node" />
+
+import { Server as HttpServer } from 'http';
+import { Server as HttpsServer, ServerOptions as TlsOptions } from 'https';
+import { Http2Server, Http2SecureServer } from 'http2';
+import { Request } from './request';
+import { Response } from './response';
+import { RouterInstance, RouteChain, RouteInfo, RouteOptions, RouteHandler } from './router';
+import { MiddlewareFunction, ErrorHandlerFunction, NextFunction } from './middleware';
+import { WebSocketHandler, WebSocketOptions, WebSocketPool } from './websocket';
+import { SSEStream } from './sse';
+import { LifecycleState } from './lifecycle';
+import { MetricsRegistry, HealthCheckResult } from './observe';
+import { ProtoSchema, GrpcServiceOptions, GrpcInterceptor, GrpcHandler } from './grpc';
+
+export interface ListenOptions {
+    /** Create an HTTP/2 server. Combined with TLS options for h2 over TLS, or h2c (cleartext) otherwise. */
+    http2?: boolean;
+    /** Allow HTTP/1.1 fallback on HTTP/2 TLS servers (ALPN negotiation). Default: true. */
+    allowHTTP1?: boolean;
+}
+
+export interface App {
+    /** Internal router instance. */
+    router: RouterInstance;
+    /** Middleware stack. */
+    middlewares: MiddlewareFunction[];
+    /** Application-level locals, merged into every request/response locals. */
+    locals: Record<string, any>;
+
+    /**
+     * Register middleware or mount a sub-router.
+     */
+    use(fn: MiddlewareFunction): App;
+    use(path: string, fn: MiddlewareFunction): App;
+    use(path: string, router: RouterInstance): App;
+
+    /**
+     * Register a global error handler.
+     */
+    onError(fn: ErrorHandlerFunction): void;
+
+    /**
+     * Core request handler for use with `http.createServer()`.
+     */
+    handler(req: import('http').IncomingMessage, res: import('http').ServerResponse): void;
+
+    /**
+     * Start listening for connections.
+     * Pass `{ http2: true }` to create an HTTP/2 server (h2c cleartext or TLS with ALPN).
+     */
+    listen(port?: number, cb?: () => void): HttpServer;
+    listen(port: number, opts: TlsOptions, cb?: () => void): HttpsServer;
+    listen(port: number, opts: ListenOptions & { http2: true } & TlsOptions, cb?: () => void): Http2SecureServer;
+    listen(port: number, opts: ListenOptions & { http2: true }, cb?: () => void): Http2Server;
+    listen(port: number, opts: ListenOptions, cb?: () => void): HttpServer | HttpsServer | Http2Server | Http2SecureServer;
+
+    /**
+     * Gracefully close the server.
+     */
+    close(cb?: (err?: Error) => void): void;
+
+    /**
+     * Perform a full graceful shutdown.
+     */
+    shutdown(opts?: { timeout?: number }): Promise<void>;
+
+    /**
+     * Register a lifecycle event listener.
+     */
+    on(event: 'beforeShutdown' | 'shutdown', fn: () => void | Promise<void>): App;
+
+    /**
+     * Remove a lifecycle event listener.
+     */
+    off(event: 'beforeShutdown' | 'shutdown', fn: () => void | Promise<void>): App;
+
+    /**
+     * Register a WebSocket pool for graceful shutdown.
+     */
+    registerPool(pool: WebSocketPool): App;
+
+    /**
+     * Unregister a WebSocket pool from lifecycle management.
+     */
+    unregisterPool(pool: WebSocketPool): App;
+
+    /**
+     * Track an SSE stream for graceful shutdown.
+     */
+    trackSSE(stream: SSEStream): App;
+
+    /**
+     * Register an ORM Database for graceful shutdown.
+     */
+    registerDatabase(db: { close(): Promise<void> }): App;
+
+    /**
+     * Unregister an ORM Database from lifecycle management.
+     */
+    unregisterDatabase(db: { close(): Promise<void> }): App;
+
+    /**
+     * Configure the shutdown timeout in milliseconds.
+     */
+    shutdownTimeout(ms: number): App;
+
+    /**
+     * Current lifecycle state.
+     */
+    readonly lifecycleState: LifecycleState;
+
+    /**
+     * Register a liveness health check endpoint.
+     */
+    health(path?: string, checks?: Record<string, () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>>): App;
+    health(checks?: Record<string, () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>>): App;
+
+    /**
+     * Register a readiness health check endpoint.
+     */
+    ready(path?: string, checks?: Record<string, () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>>): App;
+    ready(checks?: Record<string, () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>>): App;
+
+    /**
+     * Register a custom health check.
+     */
+    addHealthCheck(name: string, fn: () => HealthCheckResult | boolean | Promise<HealthCheckResult | boolean>): App;
+
+    /**
+     * Get the application metrics registry.
+     */
+    metrics(): MetricsRegistry;
+
+    /**
+     * Mount a Prometheus metrics endpoint.
+     */
+    metricsEndpoint(path?: string, opts?: { registry?: MetricsRegistry }): App;
+
+    /**
+     * Register a WebSocket upgrade handler.
+     */
+    ws(path: string, handler: WebSocketHandler): void;
+    ws(path: string, opts: WebSocketOptions, handler: WebSocketHandler): void;
+
+    /**
+     * Register a gRPC service with handlers.
+     */
+    grpc(schema: ProtoSchema, serviceName: string, handlers: Record<string, GrpcHandler>, opts?: GrpcServiceOptions): App;
+
+    /**
+     * Add a global gRPC interceptor.
+     */
+    grpcInterceptor(fn: GrpcInterceptor): App;
+
+    /**
+     * Return a flat list of all registered routes.
+     */
+    routes(): RouteInfo[];
+
+    /**
+     * Register a route with a specific HTTP method.
+     */
+    route(method: string, path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+
+    /**
+     * Get a setting value (1 arg) or set a setting value (2 args).
+     */
+    set(key: string): any;
+    set(key: string, val: any): App;
+
+    /**
+     * Get a setting value, or register a GET route.
+     * With 1 string arg: returns the setting value.
+     * With path + handlers: registers a GET route.
+     */
+    get(key: string): any;
+    get(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+
+    /**
+     * Enable a boolean setting (set to `true`).
+     */
+    enable(key: string): App;
+
+    /**
+     * Disable a boolean setting (set to `false`).
+     */
+    disable(key: string): App;
+
+    /**
+     * Check if a setting is truthy.
+     */
+    enabled(key: string): boolean;
+
+    /**
+     * Check if a setting is falsy.
+     */
+    disabled(key: string): boolean;
+
+    /**
+     * Register a parameter pre-processing handler.
+     */
+    param(name: string, fn: (req: Request, res: Response, next: NextFunction, value: string) => void): App;
+
+    /**
+     * Create a route group under a prefix with shared middleware.
+     */
+    group(prefix: string, ...args: [...MiddlewareFunction[], (router: RouterInstance) => void]): App;
+
+    /**
+     * Create a chainable route builder for the given path.
+     */
+    chain(path: string): RouteChain;
+
+    // HTTP method shortcuts
+    post(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    put(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    delete(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    patch(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    options(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    head(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    all(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+}