redweb 0.7.7 → 0.9.0

package/index.d.ts

@@ -1,9 +1,10 @@
 declare module 'redweb' {
     import { Application } from 'express';
     import { CorsOptions } from 'cors';
-    import { Server as NodeHttpServer } from 'http';
-    import { WebSocket, ServerOptions } from 'ws';
-    import { Buffer } from 'buffer';
+    import { Server as NodeHttpServer } from 'http';
+    import { WebSocket, ServerOptions } from 'ws';
+    import { Buffer } from 'buffer';
+    import { EventEmitter } from 'events';
 
     /** ─────────────────── HTTP / CORE ─────────────────── */
 
@@ -12,42 +13,217 @@ declare module 'redweb' {
     export interface RedWebOptions {
         port?: number;
         bind?: string;
-        publicPaths?: string[];
-        services?: Array<{ serviceName: string; method: string; function: Function }>;
-        listen?: boolean;
-        listenCallback?: () => void;
+        publicPaths?: string[];
+        services?: Array<{ serviceName: string; method: string; function: Function }>;
+        listen?: boolean;
+        listenCallback?: () => void;
         encoding?: RedWebEncoding;
         ssl?: { key: string; cert: string };
         server?: Application;
-        corsOptions?: CorsOptions;
+        corsOptions?: CorsOptions | false;
         enableHtmxRendering?: boolean;
+        exposeErrors?: boolean;
+        logger?: RedWebLogger | null;
+    }
+
+    export type RedWebSocket = WebSocket & {
+        clientKey: string;
+        __redwebClientKey: string;
+        remoteAddress: string;
+        isAssigned: boolean;
+        sendJson(data: unknown): boolean;
+        broadcast(data: unknown): number;
+        context?: RedWebConnectionContext;
+        joinRoom?(roomId: string): boolean;
+        leaveRoom?(roomId: string): boolean;
+        roomBroadcast?(roomId: string, data: unknown, options?: { except?: RedWebSocket }): number;
+        createSession?(sessionId: string, data: unknown): boolean;
+        resumeSession?(sessionId: string): unknown | null;
+        publishEvent?(type: string, payload: unknown): Promise<boolean>;
+        sendEvent?(type: string, payload: unknown, metadata?: ProtocolMetadata): boolean;
+        sendProtocolError?(code: string, message: string, metadata?: ProtocolMetadata): boolean;
+        sendBinaryEvent?(value: unknown): Promise<boolean>;
+    };
+
+    export interface RedWebConnectionContext {
+        connectionId: string;
+        principal: unknown;
+        session: unknown | null;
+        metadata: Record<string, unknown>;
+        signal?: AbortSignal;
+        protocol?: Readonly<{ version: string }>;
+    }
+
+    export interface AdmissionContext {
+        signal: AbortSignal;
+        networkIdentity: string;
+        route: SocketRoute;
+    }
+
+    export interface AdmissionOptions {
+        authenticate?: (
+            request: import('http').IncomingMessage,
+            context: AdmissionContext
+        ) => unknown | false | Promise<unknown | false>;
+        origins?: string[] | ((
+            origin: string | undefined,
+            request: import('http').IncomingMessage
+        ) => boolean | Promise<boolean>);
+        place?: (
+            principal: unknown,
+            request: import('http').IncomingMessage,
+            context: AdmissionContext
+        ) => string | false | null | undefined | Promise<string | false | null | undefined>;
+        allowedPlacementOrigins?: string[];
+        allowInsecurePlacement?: boolean;
+        timeoutMs?: number;
+    }
+
+    export interface MessageRateLimit {
+        capacity: number;
+        refillPerSecond: number;
+        action?: 'drop' | 'disconnect';
+    }
+
+    export interface TransportLimits {
+        maxConnections?: number;
+        maxBufferedBytes?: number;
+        maxPendingMessages?: number;
+        messageRate?: MessageRateLimit;
+        slowConsumerAction?: 'drop' | 'disconnect';
+    }
+
+    export interface HeartbeatOptions {
+        intervalMs: number;
+        timeoutMs: number;
+    }
+
+    export interface RoomOptions {
+        maxRooms?: number;
+        maxMembersPerRoom?: number;
+        maxRoomsPerConnection?: number;
+        maxRoomIdLength?: number;
+    }
+
+    export interface SessionOptions {
+        ttlMs?: number;
+        maxSessions?: number;
+        maxSessionIdLength?: number;
+        sweepIntervalMs?: number;
+    }
+
+    export interface MetricsSink {
+        increment?(name: string, value: number, attributes: Readonly<{ route: string }>): void | Promise<void>;
+        gauge?(name: string, value: number, attributes: Readonly<{ route: string }>): void | Promise<void>;
+        observe?(name: string, value: number, attributes: Readonly<{ route: string }>): void | Promise<void>;
+    }
+
+    export interface DistributionEvent<T = unknown> {
+        id: string;
+        source: string;
+        type: string;
+        payload: T;
+    }
+
+    export interface DistributionAdapter {
+        start?(signal?: AbortSignal): void | Promise<void>;
+        publish(channel: string, serializedEvent: string, signal?: AbortSignal): void | Promise<void>;
+        subscribe(
+            channel: string,
+            onEvent: (serializedEvent: string | DistributionEvent) => void,
+            signal?: AbortSignal
+        ): void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
+        unsubscribe?(channel: string, signal?: AbortSignal): void | Promise<void>;
+        close?(signal?: AbortSignal): void | Promise<void>;
+    }
+
+    export interface DistributionOptions {
+        adapter: DistributionAdapter;
+        channel: string;
+        nodeId?: string;
+        maxEventBytes?: number;
+        maxSeenEvents?: number;
+        seenTtlMs?: number;
+        lifecycleTimeoutMs?: number;
+        publishTimeoutMs?: number;
+        maxConcurrentPublishes?: number;
+        maxConcurrentEvents?: number;
+        required?: boolean;
+        onEvent(event: DistributionEvent, route: SocketRoute): void | Promise<void>;
+    }
+
+    export interface ProtocolMetadata {
+        requestId?: string;
+        sequence?: number;
+    }
+
+    export interface ProtocolBinaryCodec {
+        maxBytes?: number;
+        encode(value: unknown, context: RedWebConnectionContext): Buffer | Uint8Array | ArrayBuffer | Promise<Buffer | Uint8Array | ArrayBuffer>;
+        decode(buffer: Buffer, context: RedWebConnectionContext): unknown | Promise<unknown>;
+    }
+
+    export interface ProtocolOptions {
+        versions: string[];
+        required?: boolean;
+        queryParameter?: string;
+        header?: string;
+        binary?: false | ProtocolBinaryCodec;
     }
 
     /** ─────────────────── SOCKET SERVER ─────────────────── */
 
     export interface SocketServerOptions {
-        server?: NodeHttpServer;
-        port?: number;
-        listen?: boolean;
-        routes?: Array<new () => SocketRoute>;
+        server?: NodeHttpServer;
+        port?: number;
+        bind?: string;
+        listen?: boolean;
+        routes?: Array<new () => SocketRoute>;
         ssl?: { key: string; cert: string };
+        fallbackToRoot?: boolean;
+        closeServerOnShutdown?: boolean;
+        listenCallback?: () => void;
+        logger?: RedWebLogger | null;
+    }
+
+    export interface RedWebLogger {
+        log?(message?: any, ...optionalParams: any[]): void;
+        warn?(message?: any, ...optionalParams: any[]): void;
+        error?(message?: any, ...optionalParams: any[]): void;
     }
 
     /** ─────────────────── ROUTES & HANDLERS ─────────────────── */
 
     export interface SocketRouteConfig {
         path: string;
-        handlers: Array<new () => BaseHandler>;
-        services?: Array<new () => SocketService>;
-        allowDuplicateConnections?: boolean;
-        websocketOptions?: ServerOptions;
+        handlers: Array<new () => BaseHandler>;
+        services?: Array<new () => SocketService>;
+        allowDuplicateConnections?: boolean;
+        websocketOptions?: Omit<ServerOptions, 'noServer' | 'path' | 'server' | 'port'>;
+        trustProxy?: boolean;
+        getClientKey?: (request: import('http').IncomingMessage) => string;
+        exposeErrors?: boolean;
+        logger?: RedWebLogger | null;
+        shutdownTimeoutMs?: number;
+        admission?: AdmissionOptions | AdmissionOptions['authenticate'];
+        limits?: TransportLimits;
+        orderedMessages?: boolean;
+        heartbeat?: HeartbeatOptions;
+        rooms?: boolean | RoomOptions;
+        sessions?: boolean | SessionOptions;
+        metrics?: MetricsSink;
+        distribution?: false | DistributionOptions;
+        drainHandlers?: boolean;
+        protocol?: false | ProtocolOptions;
+        maxPendingUpgrades?: number;
     }
 
     /** Socket‑side autonomous service (game loops, timers, etc.) */
     export abstract class SocketService {
         name: string;
-        tickRateMs?: number;
-        protected _tickHandle?: NodeJS.Timeout;
+        tickRateMs: number | null;
+        route: SocketRoute;
+        protected _tickHandle: NodeJS.Timeout | null;
 
         constructor(name: string, tickRateMs?: number);
 
@@ -55,62 +231,116 @@ declare module 'redweb' {
         onInit(route: SocketRoute): void;
 
         /** Optional recurring tick (respecting tickRateMs) */
-        onTick?(): void;
+        onTick?(...args: any[]): unknown;
 
         /** Called on process shutdown / route removal */
         onShutdown(): void;
     }
 
+    export abstract class FixedStepService extends SocketService {
+        maxCatchUpTicks: number;
+        maxRetainedLagMs: number;
+        tick: number;
+        accumulatorMs: number;
+
+        constructor(name: string, tickRateMs: number, maxCatchUpTicks?: number, maxRetainedLagMs?: number);
+        onTick?(stepMs: number, tick: number): void | Promise<void>;
+        onLagDropped?(droppedLagMs: number): void;
+        pulse(): Promise<void>;
+        onShutdown(): Promise<void>;
+    }
+
     /** Message handler, triggered by client messages */
     export class BaseHandler {
         name: string;
         constructor(name: string);
 
         handleMessage(
-            socket: WebSocket & {
-                sendJson: (message: object) => void;
-                broadcast: (message: object) => void;
-            },
+            socket: RedWebSocket,
             message: any
-        ): void;
-
-        onMessage(socket: WebSocket, message: any): void;
-        acceptsBinary?(socket: WebSocket, buffer: Buffer): boolean;
-        handleBinaryMessage(socket: WebSocket, buffer: Buffer): void;
-        onBinaryMessage(socket: WebSocket, buffer: Buffer): void;
-        onInitialContact(socket: WebSocket): void;
-    }
+        ): Promise<unknown>;
+
+        validateMessage(message: any, socket: RedWebSocket): boolean | Promise<boolean>;
+        onMessage(socket: RedWebSocket, message: any): unknown;
+        acceptsBinary?(socket: RedWebSocket, buffer: Buffer): boolean;
+        handleBinaryMessage(socket: RedWebSocket, buffer: Buffer): Promise<unknown>;
+        onBinaryMessage(socket: RedWebSocket, buffer: Buffer): unknown;
+        onInitialContact(socket: RedWebSocket, request?: import('http').IncomingMessage): unknown;
+    }
 
     export class SocketRoute {
         path: string;
-        handlers: BaseHandler[];
-        clients: Map<string, WebSocket>;
-        allowDuplicateConnections?: boolean;
-        websocketOptions?: ServerOptions;
-
-        constructor(config: SocketRouteConfig);
-
-        addHandler(handler: new () => BaseHandler): void;
-        handleMessage(sock: WebSocket, data: any): void;
-        handleBinaryMessage(socket: WebSocket, buffer: Buffer): void;
-    }
+        handlers: BaseHandler[];
+        services: SocketService[];
+        clients: Map<string, RedWebSocket>;
+        rooms: RoomRegistry | null;
+        sessions: SessionRegistry | null;
+        distribution: unknown | null;
+        protocolPolicy: unknown | null;
+        draining: boolean;
+        allowDuplicateConnections?: boolean;
+        websocketOptions?: SocketRouteConfig['websocketOptions'];
+
+        constructor(config: SocketRouteConfig);
+
+        addHandler(handler: new () => BaseHandler): boolean;
+        resolveRemoteAddress(request: import('http').IncomingMessage): string;
+        connectionOpenCallback(socket: RedWebSocket, request?: import('http').IncomingMessage): unknown;
+        connectionCloseCallback?(socket: RedWebSocket): unknown;
+        handleMessage(sock: RedWebSocket, data: any): Promise<boolean>;
+        handleBinaryMessage(socket: RedWebSocket, buffer: Buffer): Promise<boolean>;
+        beginDrain(): boolean;
+        isReady(): boolean;
+        publish(type: string, payload: unknown): Promise<boolean>;
+        shutdown(): Promise<void>;
+    }
 
     /** ─────────────────── SERVER BASE ─────────────────── */
 
     export class BaseSocketServer {
-        clients: Map<string, WebSocket>;
-        server: NodeHttpServer;
+        server: NodeHttpServer;
         routes: SocketRoute[];
+        ownsServer: boolean;
 
-        constructor(server: NodeHttpServer, options?: SocketServerOptions);
+        constructor(server: NodeHttpServer, options?: SocketServerOptions);
 
-        addRoute(route: new () => SocketRoute): void;
+        addRoute(route: new () => SocketRoute): SocketRoute;
+        isReady(): boolean;
+        beginDrain(): boolean;
+        shutdown(): Promise<void>;
     }
 
     /** ─────────────────── REGISTRY & UTIL TYPES ─────────────────── */
 
+    export function sendJson(socket: WebSocket, data: unknown): boolean;
+
+    export class RoomRegistry {
+        constructor(options?: RoomOptions);
+        join(roomId: string, socket: RedWebSocket): boolean;
+        leave(roomId: string, socket: RedWebSocket): boolean;
+        leaveAll(socket: RedWebSocket): number;
+        members(roomId: string): RedWebSocket[];
+        has(roomId: string, socket: RedWebSocket): boolean;
+        broadcast(roomId: string, data: unknown, options?: { except?: RedWebSocket }): number;
+        clear(): void;
+        close(): boolean;
+        readonly size: number;
+    }
+
+    export class SessionRegistry<T = unknown> {
+        constructor(options?: SessionOptions, logger?: RedWebLogger | null);
+        create(sessionId: string, data: T, socket?: RedWebSocket): boolean;
+        resume(sessionId: string, socket: RedWebSocket): T | null;
+        release(socket: RedWebSocket): boolean;
+        remove(sessionId: string): boolean;
+        get(sessionId: string): T | undefined;
+        sweep(): void;
+        stop(): void;
+        readonly size: number;
+    }
+
     export interface SocketWrapper {
-        socket: WebSocket;
+        socket: RedWebSocket;
         id: string;
         send: (type: string, payload: Record<string, any>) => void;
         getSanitized?(): Record<string, any>;
@@ -155,19 +385,22 @@ declare module 'redweb' {
         constructor(options?: SocketServerOptions);
     }
 
-    export class BaseHttpServer {
-        app: Application;
-        server?: NodeHttpServer;
-        constructor(options?: RedWebOptions);
-    }
-
-    export class HttpServer extends BaseHttpServer {
-        constructor(options?: RedWebOptions);
-    }
-
-    export class HttpsServer extends BaseHttpServer {
-        constructor(options?: RedWebOptions);
-    }
+    export class BaseHttpServer {
+        app: Application;
+        server?: NodeHttpServer;
+        constructor(options?: RedWebOptions);
+        shutdown?(): Promise<void>;
+    }
+
+    export class HttpServer extends BaseHttpServer {
+        constructor(options?: RedWebOptions);
+        shutdown(): Promise<void>;
+    }
+
+    export class HttpsServer extends BaseHttpServer {
+        constructor(options?: RedWebOptions);
+        shutdown(): Promise<void>;
+    }
 
     /** ─────────────────── CONSTANTS ─────────────────── */
 
@@ -175,7 +408,11 @@ declare module 'redweb' {
         GET: 'get';
         POST: 'post';
         PUT: 'put';
+        PATCH: 'patch';
         DELETE: 'delete';
+        OPTIONS: 'options';
+        HEAD: 'head';
+        ALL: 'all';
     };
 
     export const ENCODINGS: {
@@ -185,4 +422,15 @@ declare module 'redweb' {
 
     export const HTTP_OPTIONS: RedWebOptions;
     export const SOCKET_OPTIONS: SocketServerOptions;
+
+    export const ERROR_CODES: Readonly<{
+        INVALID_MESSAGE: 'INVALID_MESSAGE';
+        UNKNOWN_HANDLER: 'UNKNOWN_HANDLER';
+        HANDLER_FAILED: 'HANDLER_FAILED';
+        BINARY_UNSUPPORTED: 'BINARY_UNSUPPORTED';
+        RATE_LIMITED: 'RATE_LIMITED';
+        QUEUE_FULL: 'QUEUE_FULL';
+        CAPACITY_REACHED: 'CAPACITY_REACHED';
+        INITIALIZATION_FAILED: 'INITIALIZATION_FAILED';
+    }>;
 }

package/index.js

@@ -1,20 +1,38 @@
-const { BaseHttpServer, METHODS } = require('./src/http');
+const { BaseHttpServer, METHODS } = require('./src/http');
+const { ENCODINGS, HTTP_OPTIONS } = require('./src/http/BaseHttpServer');
 const { sendJson } = require('./src/ws/util');
-const { SocketServer, SecureSocketServer, SOCKET_OPTIONS, SocketRoute, SocketService, SocketRegistry } = require('./src/ws');
+const {
+    SocketServer,
+    SecureSocketServer,
+    SOCKET_OPTIONS,
+    SocketRoute,
+    SocketService,
+    FixedStepService,
+    SocketRegistry,
+    RoomRegistry,
+    SessionRegistry,
+    ERROR_CODES,
+} = require('./src/ws');
 const { BaseHandler } = require('./src/ws/BaseHandler');
 const HttpServer = require('./src/http/HttpServer');
 const HttpsServer = require('./src/http/HttpsServer');
 module.exports = {
-    HttpServer,
-    HttpsServer,
-    BaseHttpServer,
-    SocketServer,
+    HttpServer,
+    HttpsServer,
+    BaseHttpServer,
+    SocketServer,
     SecureSocketServer,
     BaseHandler,
     SocketRoute,
     SocketService,
+    FixedStepService,
     SocketRegistry,
+    RoomRegistry,
+    SessionRegistry,
+    ERROR_CODES,
     sendJson,
     SOCKET_OPTIONS,
+    HTTP_OPTIONS,
+    ENCODINGS,
     METHODS
 };

package/package.json

@@ -1,27 +1,46 @@
 {
   "name": "redweb",
-  "version": "0.7.7",
+  "version": "0.9.0",
   "description": "A way to quickly set up an express server",
   "main": "index.js",
+  "types": "index.d.ts",
   "scripts": {
+    "pretest": "node scripts/generate-protocol-types.js --check && tsc -p tests/types/tsconfig.json",
+    "generate:protocol-types": "node scripts/generate-protocol-types.js",
+    "verify:overhead": "node scripts/verify-disabled-overhead.js",
+    "verify:soak": "node --expose-gc scripts/verify-soak.js",
+    "verify:memory": "node scripts/verify-memory-overhead.js",
+    "verify:load": "node scripts/verify-load.js",
+    "verify:recovery": "node --expose-gc scripts/verify-recovery.js",
     "test": "npx jest"
   },
   "files": [
     "src/*",
-    "index.d.ts"
+    "client.js",
+    "client.d.ts",
+    "CHANGELOG.md",
+    "index.d.ts",
+    "docs"
   ],
   "keywords": [],
   "author": "",
   "license": "ISC",
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
+    "@types/cors": "2.8.19",
+    "@types/express": "^4.17.21",
+    "@types/node": "20.19.24",
+    "@types/ws": "^8.18.1",
     "cors": "^2.8.5",
-    "express": "^4.19.2",
-    "ws": "^8.17.0"
+    "express": "^4.22.2",
+    "ws": "^8.21.3"
   },
   "devDependencies": {
-    "@types/express": "^4.17.21",
     "@types/jest": "^29.5.12",
     "jest": "^29.7.0",
-    "supertest": "^7.0.0"
+    "supertest": "^7.0.0",
+    "typescript": "^5.9.3"
   }
 }

package/src/htmx/HtmxRenderer.js

@@ -8,7 +8,7 @@ class HtmxRenderer {
      * @param {string} filePath - Path to the .htmx file.
      * @returns {string} Rendered HTML string with normalized whitespace.
      */
-    static render(filePath) {
+    static render(filePath, { rootDir = path.dirname(path.resolve(filePath)), timeoutMs = 1000 } = {}) {
         if (!fs.existsSync(filePath)) {
             throw new Error(`Template file not found: ${filePath}`);
         }
@@ -32,8 +32,16 @@ class HtmxRenderer {
         `;
 
         // Create a custom require function that resolves paths relative to the template
+        const resolvedRoot = path.resolve(rootDir);
         const customRequire = (modulePath) => {
+            if (typeof modulePath !== 'string' || !modulePath.startsWith('.')) {
+                throw new Error('Templates may only require relative modules');
+            }
             const absolutePath = path.resolve(path.dirname(filePath), modulePath);
+            const relative = path.relative(resolvedRoot, absolutePath);
+            if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+                throw new Error('Template module is outside the allowed root');
+            }
             return require(absolutePath);
         };
 
@@ -48,7 +56,7 @@ class HtmxRenderer {
         vm.createContext(sandbox);
 
         // Get the rendered output
-        let result = script.runInContext(sandbox);
+        let result = script.runInContext(sandbox, { timeout: timeoutMs });
 
         // Normalize spaces but preserve those in content
         result = result