redweb 0.7.7 → 0.9.0

package/src/ws/BaseSocketServer.js

@@ -1,19 +1,33 @@
 /**
  * @typedef {Object} SocketServerOptions
- * @property {import('http').Server} [server]                    HTTP server to bind to
- * @property {number}              [port=3000]                  Port to listen on
- * @property {boolean}             [listen=true]                Whether owned servers should automatically start listening
- * @property {Array<new () => import('./SocketRoute').SocketRoute>} [routes]
- */
+ * @property {import('http').Server} [server]                    HTTP server to bind to
+ * @property {number}              [port=3000]                  Port to listen on
+ * @property {boolean}             [listen=true]                Whether owned servers should automatically start listening
+ * @property {Array<new () => import('./SocketRoute').SocketRoute>} [routes]
+ */
 
 const DefaultRoute = require('./DefaultRoute');
+const { PLACEMENT_REDIRECT, ADMISSION_SETTLEMENT } = require('./AdmissionPolicy');
+const { PROTOCOL_REJECTION } = require('./ProtocolPolicy');
+const {
+  listenServer,
+  closeServer,
+  settleTasks,
+  throwCleanupErrors,
+  validateListenerOptions,
+} = require('../serverLifecycle');
 
 const SOCKET_OPTIONS = {
-  port: 3000,
-  ssl:  null,
-  listen: true,
-  routes: []
-};
+  port: 3000,
+  bind: '0.0.0.0',
+  ssl:  null,
+  listen: true,
+  routes: [],
+  fallbackToRoot: false,
+  closeServerOnShutdown: undefined,
+  logger: console,
+  listenCallback: undefined,
+};
 
 /**
  * Base WebSocket server
@@ -23,16 +37,61 @@ class BaseSocketServer {
    * @param {import('http').Server} server
    * @param {SocketServerOptions}  [options]
    */
-  constructor(server, options = {}) {
-    this.clients = new Map();
+  constructor(server, options = {}, ownsServer = false, name = 'SocketServer') {
+    if (!server || typeof server.on !== 'function') throw new TypeError('A Node HTTP(S) server is required.');
     Object.assign(this, { ...SOCKET_OPTIONS, ...options });
+    validateListenerOptions(this);
+    if (!Array.isArray(this.routes)) throw new TypeError('`routes` must be an array.');
     this.server = server;
+    this.ownsServer = ownsServer;
+    this.closeServerOnShutdown = options.closeServerOnShutdown ?? ownsServer;
+    this.draining = false;
+    this.pendingUpgrades = new Map();
+    this.rawConnections = this.closeServerOnShutdown ? new Set() : null;
+    this._connectionHandler = this.rawConnections ? socket => {
+      this.rawConnections.add(socket);
+      socket.once('close', () => this.rawConnections.delete(socket));
+    } : null;
+    if (this._connectionHandler) this.server.on('connection', this._connectionHandler);
 
     /* ─── ROUTE INITIALISATION ─────────────────────────── */
-    if (!options.routes?.length) options.routes = [DefaultRoute];
-    this.routes = options.routes.map(RouteClass => new RouteClass(server));
+    const RouteClasses = options.routes?.length ? [...options.routes] : [DefaultRoute];
+    this.routes = [];
+    try {
+      for (const RouteClass of RouteClasses) {
+        const route = new RouteClass(server, { logger: this.logger });
+        if (this.routes.some(existing => existing.path === route.path)) {
+          this.disposeRoutes([route]);
+          throw new Error('WebSocket route paths must be unique.');
+        }
+        this.routes.push(route);
+      }
+    } catch (error) {
+      this.disposeRoutes(this.routes);
+      throw error;
+    }
+
+    this._upgradeHandler = this.handleUpgrade.bind(this);
+    this.server.on('upgrade', this._upgradeHandler);
 
-    this.server.on('upgrade', this.handleUpgrade.bind(this));
+    const shouldListen = (ownsServer && this.listen !== false) || (!ownsServer && options.listen === true);
+    if (shouldListen) {
+      listenServer(this.server, {
+        port: this.port,
+        bind: this.bind,
+        callback: this.listenCallback,
+        logger: this.logger,
+        name,
+      });
+    }
+  }
+
+  disposeRoutes(routes) {
+    routes.forEach(route => {
+      Promise.resolve()
+        .then(() => route.shutdown?.())
+        .catch(error => this.logger?.error?.('Error shutting down route:', error));
+    });
   }
 
   handleUpgrade(req, sock, head) {
@@ -49,29 +108,133 @@ class BaseSocketServer {
 
     const route =
       this.routes.find(r => r.path === path) ||
-      this.routes.find(r => r.path === '/');
+      (this.fallbackToRoot ? this.routes.find(r => r.path === '/') : undefined);
 
     if (!route) return sock.destroy();
+    if (this.draining) return this.rejectUpgrade(sock, 503, 'Service Unavailable');
+    if (route.isReady?.() === false) return this.rejectUpgrade(sock, 503, 'Service Unavailable');
 
+    if (route.admissionPolicy || route.protocolPolicy || route.transportPolicy && route.transportPolicy.maxConnections !== Infinity) {
+      let reservation;
+      try {
+        reservation = route.reserveUpgrade(req);
+      } catch (error) {
+        this.logger?.error?.('WebSocket admission reservation failed:', error);
+      }
+      if (!reservation) return this.rejectUpgrade(sock, 503, 'Service Unavailable');
+      const controller = new AbortController();
+      this.pendingUpgrades.set(sock, { controller, route, reservation });
+      void Promise.resolve()
+        .then(() => route.authorizeUpgrade(req, sock, controller.signal))
+        .then(accepted => {
+          if (sock.destroyed) return;
+          if (this.draining) return this.rejectUpgrade(sock, 503, 'Service Unavailable');
+          if (!accepted) {
+            const redirect = req[PLACEMENT_REDIRECT];
+            if (redirect) return this.rejectUpgrade(sock, 307, 'Temporary Redirect', { Location: redirect });
+            const rejection = req[PROTOCOL_REJECTION];
+            return rejection
+              ? this.rejectUpgrade(sock, rejection.statusCode, rejection.statusText, rejection.headers)
+              : this.rejectUpgrade(sock, 401, 'Unauthorized');
+          }
+          this.completeUpgrade(route, req, sock, head);
+        })
+        .catch(error => {
+          this.logger?.error?.('WebSocket admission failed:', error);
+          if (!sock.destroyed) this.rejectUpgrade(sock, 401, 'Unauthorized');
+        })
+        .finally(async () => {
+          await req[ADMISSION_SETTLEMENT];
+          this.pendingUpgrades.delete(sock);
+          route.releaseUpgrade(reservation);
+        });
+      return;
+    }
+
+    this.completeUpgrade(route, req, sock, head);
+  }
+
+  completeUpgrade(route, req, sock, head) {
     route.server.handleUpgrade(req, sock, head, (s, r) =>
       route.server.emit('connection', s, r)
     );
   }
 
+  rejectUpgrade(socket, statusCode, statusText, headers = {}) {
+    try {
+      const extraHeaders = Object.entries(headers).map(([name, value]) => `${name}: ${value}\r\n`).join('');
+      socket.end?.(
+        `HTTP/1.1 ${statusCode} ${statusText}\r\n` +
+        extraHeaders +
+        'Connection: close\r\n' +
+        'Content-Length: 0\r\n\r\n'
+      );
+    } catch {
+      socket.destroy?.();
+    }
+  }
+
   /**
    * Dynamically attach a new route at runtime
    * @param {new () => import('./SocketRoute').SocketRoute} RouteClass
    */
   addRoute(RouteClass) {
-    this.routes.push(new RouteClass(this.server));
+    const route = new RouteClass(this.server, { logger: this.logger });
+    if (this.routes.some(existing => existing.path === route.path)) {
+      this.disposeRoutes([route]);
+      throw new Error(`A WebSocket route already exists at ${route.path}.`);
+    }
+    this.routes.push(route);
+    return route;
   }
 
   /**
    * Gracefully tear down all routes (and their services)
    */
   shutdown() {
-    this.routes.forEach(route => route.shutdown?.());
-    this.server.close();
+    if (!this._shutdownPromise) this._shutdownPromise = this.performShutdown();
+    return this._shutdownPromise;
+  }
+
+  isReady() {
+    return !this.draining && this.routes.every(route => route.isReady?.() !== false);
+  }
+
+  beginDrain() {
+    if (this.draining) return false;
+    this.draining = true;
+    this.pendingUpgrades.forEach(({ controller }) => controller.abort());
+    this.routes.forEach(route => route.beginDrain?.());
+    return true;
+  }
+
+  async performShutdown() {
+    this.beginDrain();
+    this.server.off?.('upgrade', this._upgradeHandler);
+    const deadline = Date.now() + Math.max(0, ...this.routes.map(route => route.shutdownTimeoutMs));
+    const errors = await settleTasks(this.routes.map(route => () => route.shutdown?.()));
+    if (this.closeServerOnShutdown && this.server.listening) {
+      try {
+        await this.closeOwnedServer(Math.max(0, deadline - Date.now()));
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (this._connectionHandler) this.server.off?.('connection', this._connectionHandler);
+    throwCleanupErrors(errors, 'One or more WebSocket server cleanup operations failed.');
+  }
+
+  closeOwnedServer(timeoutMs) {
+    let timer;
+    const closing = closeServer(this.server);
+    const timeout = new Promise(resolve => {
+      timer = setTimeout(() => {
+        this.rawConnections?.forEach(socket => socket.destroy?.());
+        resolve();
+      }, timeoutMs);
+      timer.unref?.();
+    });
+    return Promise.race([closing, timeout]).finally(() => clearTimeout(timer));
   }
 }
 

package/src/ws/DefaultHandler.js

@@ -1,5 +1,4 @@
 const { BaseHandler } = require("./BaseHandler");
-const { sendJson } = require("./util");
 
 class DefaultHandler extends BaseHandler {
     constructor() {
@@ -7,8 +6,8 @@ class DefaultHandler extends BaseHandler {
     }
 
     onMessage(socket, message) {
-        socket.send(sendJson(`I got your message of ${JSON.stringify(message)}`));
+        socket.sendJson({ message: `I got your message of ${JSON.stringify(message)}` });
     }
 }
 
-module.exports = DefaultHandler;
+module.exports = DefaultHandler;

package/src/ws/DefaultRoute.js

@@ -2,13 +2,14 @@ const SocketRoute  = require("./SocketRoute");
 const DefaultHandler = require('./DefaultHandler');
 
 class DefaultRoute extends SocketRoute {
-    constructor(server) {
+    constructor(server, options = {}) {
         super({
             server,
             path: "/",
-            handlers: [DefaultHandler]
+            handlers: [DefaultHandler],
+            logger: options.logger,
         })
     }
 }
 
-module.exports = DefaultRoute;
+module.exports = DefaultRoute;

package/src/ws/DistributionBridge.js

@@ -0,0 +1,271 @@
+const { randomUUID } = require('crypto');
+const { performance } = require('perf_hooks');
+const { throwCleanupErrors } = require('../serverLifecycle');
+
+class DistributionBridge {
+    constructor(options, onEvent, logger = console, clock = () => performance.now()) {
+        if (!options || typeof options !== 'object' || Array.isArray(options)) {
+            throw new TypeError('`distribution` must be an object.');
+        }
+        const {
+            adapter,
+            channel,
+            nodeId = randomUUID(),
+            maxEventBytes = 64 * 1024,
+            maxSeenEvents = 10_000,
+            seenTtlMs = 60_000,
+            lifecycleTimeoutMs = 5000,
+            publishTimeoutMs = lifecycleTimeoutMs,
+            maxConcurrentPublishes = 64,
+            maxConcurrentEvents = 64,
+            required = false,
+        } = options;
+        if (!adapter || typeof adapter !== 'object') throw new TypeError('`distribution.adapter` is required.');
+        ['publish', 'subscribe'].forEach(method => {
+            if (typeof adapter[method] !== 'function') throw new TypeError(`\`distribution.adapter.${method}\` must be a function.`);
+        });
+        ['start', 'unsubscribe', 'close'].forEach(method => {
+            if (adapter[method] !== undefined && typeof adapter[method] !== 'function') {
+                throw new TypeError(`\`distribution.adapter.${method}\` must be a function.`);
+            }
+        });
+        if (typeof channel !== 'string' || !channel) throw new TypeError('`distribution.channel` must be a non-empty string.');
+        if (typeof nodeId !== 'string' || !nodeId || nodeId.length > 256) {
+            throw new TypeError('`distribution.nodeId` must be a non-empty string of at most 256 characters.');
+        }
+        const integers = {
+            maxEventBytes,
+            maxSeenEvents,
+            seenTtlMs,
+            lifecycleTimeoutMs,
+            publishTimeoutMs,
+            maxConcurrentPublishes,
+            maxConcurrentEvents,
+        };
+        for (const [name, value] of Object.entries(integers)) {
+            if (!Number.isInteger(value) || value < 1) throw new TypeError(`\`distribution.${name}\` must be a positive integer.`);
+        }
+        if (typeof required !== 'boolean') throw new TypeError('`distribution.required` must be a boolean.');
+        if (typeof onEvent !== 'function') throw new TypeError('`distribution.onEvent` must be a function.');
+        if (typeof clock !== 'function') throw new TypeError('`clock` must be a function.');
+        Object.assign(this, {
+            adapter,
+            channel,
+            nodeId,
+            maxEventBytes,
+            maxSeenEvents,
+            seenTtlMs,
+            lifecycleTimeoutMs,
+            publishTimeoutMs,
+            maxConcurrentPublishes,
+            maxConcurrentEvents,
+            required,
+            onEvent,
+            logger,
+            clock,
+        });
+        this.seen = new Map();
+        this.publishes = new Set();
+        this.events = new Set();
+        this.closed = false;
+        this.healthy = false;
+        this.subscribed = false;
+        this.ready = this.start();
+    }
+
+    async start() {
+        try {
+            await this.withTimeout(
+                signal => this.adapter.start?.(signal),
+                this.lifecycleTimeoutMs,
+                'start',
+                () => this.adapter.close?.()
+            );
+            if (this.closed) return false;
+            const unsubscribe = await this.withTimeout(
+                signal => this.adapter.subscribe(this.channel, event => this.receive(event), signal),
+                this.lifecycleTimeoutMs,
+                'subscribe',
+                lateUnsubscribe => typeof lateUnsubscribe === 'function'
+                    ? lateUnsubscribe()
+                    : this.adapter.unsubscribe?.(this.channel)
+            );
+            if (typeof unsubscribe === 'function') this.unsubscribe = unsubscribe;
+            this.subscribed = true;
+            this.healthy = true;
+            return true;
+        } catch (error) {
+            this.logger?.error?.('Distribution adapter failed to start:', error);
+            return false;
+        }
+    }
+
+    withTimeout(operation, timeoutMs, name, compensateLate) {
+        let timer;
+        let timedOut = false;
+        const controller = new AbortController();
+        const task = Promise.resolve().then(() => operation(controller.signal));
+        void task.then(value => {
+            if (!timedOut || !compensateLate) return;
+            Promise.resolve()
+                .then(() => compensateLate(value))
+                .catch(error => this.logger?.error?.(`Late distribution ${name} cleanup failed:`, error));
+        }, error => {
+            if (timedOut) this.logger?.error?.(`Distribution adapter ${name} failed after timeout:`, error);
+        });
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                timedOut = true;
+                controller.abort();
+                reject(new Error(`Distribution adapter ${name} timed out.`));
+            }, timeoutMs);
+            timer.unref();
+        });
+        return Promise.race([task, timeout]).finally(() => clearTimeout(timer));
+    }
+
+    isReady() {
+        return this.healthy && !this.closed;
+    }
+
+    publish(type, payload) {
+        if (this.closed || typeof type !== 'string' || !type || this.publishes.size >= this.maxConcurrentPublishes) {
+            return Promise.resolve(false);
+        }
+        const event = { id: randomUUID(), source: this.nodeId, type, payload };
+        const serialized = this.serialize(event);
+        if (!serialized) return Promise.resolve(false);
+        const task = this.performPublish(serialized);
+        this.track(this.publishes, task);
+        return task;
+    }
+
+    async performPublish(serialized) {
+        if (!await this.ready || this.closed) return false;
+        try {
+            await this.withTimeout(
+                signal => this.adapter.publish(this.channel, serialized, signal),
+                this.publishTimeoutMs,
+                'publish'
+            );
+            this.healthy = true;
+            return true;
+        } catch (error) {
+            this.healthy = false;
+            this.logger?.error?.('Distribution publish failed:', error);
+            return false;
+        }
+    }
+
+    track(collection, task) {
+        collection.add(task);
+        const cleanup = () => collection.delete(task);
+        void task.then(cleanup, cleanup);
+    }
+
+    receive(input) {
+        if (this.closed || this.events.size >= this.maxConcurrentEvents) return false;
+        let event;
+        try {
+            const serialized = typeof input === 'string' ? input : JSON.stringify(input);
+            if (Buffer.byteLength(serialized) > this.maxEventBytes) return false;
+            event = typeof input === 'string' ? JSON.parse(input) : input;
+        } catch {
+            return false;
+        }
+        if (!this.isValid(event) || event.source === this.nodeId || this.hasSeen(event.id)) return false;
+        this.remember(event.id);
+        const task = Promise.resolve()
+            .then(() => this.onEvent(event))
+            .catch(error => this.logger?.error?.('Distribution event handler failed:', error));
+        this.track(this.events, task);
+        return true;
+    }
+
+    isValid(event) {
+        return Boolean(
+            event &&
+            typeof event === 'object' &&
+            typeof event.id === 'string' && event.id && event.id.length <= 256 &&
+            typeof event.source === 'string' && event.source && event.source.length <= 256 &&
+            typeof event.type === 'string' && event.type && event.type.length <= 256
+        );
+    }
+
+    serialize(event) {
+        try {
+            const serialized = JSON.stringify(event);
+            return Buffer.byteLength(serialized) <= this.maxEventBytes ? serialized : null;
+        } catch {
+            return null;
+        }
+    }
+
+    hasSeen(id) {
+        const expiry = this.seen.get(id);
+        if (expiry === undefined) return false;
+        if (expiry <= this.clock()) {
+            this.seen.delete(id);
+            return false;
+        }
+        return true;
+    }
+
+    evictExpired(now) {
+        while (this.seen.size) {
+            const [eventId, expiry] = this.seen.entries().next().value;
+            if (expiry > now) return;
+            this.seen.delete(eventId);
+        }
+    }
+
+    remember(id) {
+        const now = this.clock();
+        this.evictExpired(now);
+        while (this.seen.size >= this.maxSeenEvents) this.seen.delete(this.seen.keys().next().value);
+        this.seen.set(id, now + this.seenTtlMs);
+    }
+
+    async stopSubscription() {
+        if (!this.subscribed) return;
+        this.subscribed = false;
+        await this.withTimeout(
+            signal => this.unsubscribe ? this.unsubscribe() : this.adapter.unsubscribe?.(this.channel, signal),
+            this.lifecycleTimeoutMs,
+            'unsubscribe'
+        );
+    }
+
+    async drainActivity() {
+        await this.withTimeout(
+            () => Promise.allSettled([...this.publishes, ...this.events]),
+            this.lifecycleTimeoutMs,
+            'drain'
+        );
+    }
+
+    async close() {
+        if (this.closed) return;
+        this.closed = true;
+        this.healthy = false;
+        await this.ready;
+        const errors = [];
+        for (const operation of [
+            () => this.stopSubscription(),
+            () => this.drainActivity(),
+            () => this.withTimeout(signal => this.adapter.close?.(signal), this.lifecycleTimeoutMs, 'close'),
+        ]) {
+            try {
+                await operation();
+            } catch (error) {
+                errors.push(error);
+            }
+        }
+        this.seen.clear();
+        this.publishes.clear();
+        this.events.clear();
+        throwCleanupErrors(errors, 'One or more distribution adapter cleanup operations failed.');
+    }
+}
+
+module.exports = DistributionBridge;

package/src/ws/FixedStepService.js

@@ -0,0 +1,74 @@
+const { performance } = require('perf_hooks');
+const SocketService = require('./SocketService');
+
+class FixedStepService extends SocketService {
+    constructor(name, tickRateMs, maxCatchUpTicks = 5, maxRetainedLagMs = tickRateMs * maxCatchUpTicks) {
+        super(name, tickRateMs);
+        if (!Number.isInteger(tickRateMs) || tickRateMs < 1) {
+            throw new TypeError('`tickRateMs` must be a positive integer.');
+        }
+        if (!Number.isInteger(maxCatchUpTicks) || maxCatchUpTicks < 1) {
+            throw new TypeError('`maxCatchUpTicks` must be a positive integer.');
+        }
+        if (!Number.isInteger(maxRetainedLagMs) || maxRetainedLagMs < tickRateMs) {
+            throw new TypeError('`maxRetainedLagMs` must be an integer greater than or equal to `tickRateMs`.');
+        }
+        this.maxCatchUpTicks = maxCatchUpTicks;
+        this.maxRetainedLagMs = maxRetainedLagMs;
+        this.tick = 0;
+        this.accumulatorMs = 0;
+        this._runningPromise = null;
+    }
+
+    now() {
+        return performance.now();
+    }
+
+    onInit(route) {
+        this.route = route;
+        this.lastTime = this.now();
+        this._tickHandle = setInterval(() => this.pulse(), this.tickRateMs);
+        this._tickHandle.unref?.();
+    }
+
+    pulse() {
+        if (this._runningPromise) return this._runningPromise;
+        const now = this.now();
+        const accumulated = this.accumulatorMs + Math.max(0, now - this.lastTime);
+        const droppedLagMs = Math.max(0, accumulated - this.maxRetainedLagMs);
+        this.accumulatorMs = Math.min(accumulated, this.maxRetainedLagMs);
+        this.lastTime = now;
+        if (droppedLagMs) {
+            this.route?.metrics?.observe('redweb.fixed_step.lag_dropped', droppedLagMs);
+            try {
+                this.onLagDropped?.(droppedLagMs);
+            } catch (error) {
+                this.route?.logger?.error?.('Fixed-step lag hook failed:', error);
+            }
+        }
+        const due = Math.min(this.maxCatchUpTicks, Math.floor(this.accumulatorMs / this.tickRateMs));
+        if (!due) return Promise.resolve();
+        this.accumulatorMs -= due * this.tickRateMs;
+        this._runningPromise = this.runTicks(due).finally(() => { this._runningPromise = null; });
+        return this._runningPromise;
+    }
+
+    async runTicks(count) {
+        for (let index = 0; index < count; index += 1) {
+            this.tick += 1;
+            try {
+                await this.onTick?.(this.tickRateMs, this.tick);
+            } catch (error) {
+                this.route?.logger?.error?.('Fixed-step service tick failed:', error);
+            }
+        }
+    }
+
+    async onShutdown() {
+        if (this._tickHandle) clearInterval(this._tickHandle);
+        this._tickHandle = null;
+        await this._runningPromise;
+    }
+}
+
+module.exports = FixedStepService;