redweb 0.8.0 → 0.10.0

package/src/ws/BaseSocketServer.js

@@ -1,31 +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]
- */
-
-const DefaultRoute = require('./DefaultRoute');
-const {
-  listenServer,
-  closeServer,
-  settleTasks,
-  throwCleanupErrors,
-  validateListenerOptions,
-} = require('../serverLifecycle');
-
-const SOCKET_OPTIONS = {
-  port: 3000,
-  bind: '0.0.0.0',
-  ssl:  null,
-  listen: true,
-  routes: [],
-  fallbackToRoot: false,
-  closeServerOnShutdown: undefined,
-  logger: console,
-  listenCallback: undefined,
-};
+ * @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,
+  bind: '0.0.0.0',
+  ssl:  null,
+  listen: true,
+  routes: [],
+  fallbackToRoot: false,
+  closeServerOnShutdown: undefined,
+  logger: console,
+  listenCallback: undefined,
+};
 
 /**
  * Base WebSocket server
@@ -35,56 +37,68 @@ class BaseSocketServer {
    * @param {import('http').Server} server
    * @param {SocketServerOptions}  [options]
    */
-  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;
+  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 ─────────────────────────── */
-    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);
-
-    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));
-    });
-  }
+    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);
+
+    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) {
+    // Upgrade sockets are detached from Node's HTTP request lifecycle. A peer
+    // may reset one while admission is pending or after a rejection response;
+    // consume that transport-level event so it cannot crash the process.
+    if (typeof sock.on === 'function') sock.on('error', Function.prototype);
     // Some websocket clients (e.g., certain UE plugins) are finicky about the
     // HTTP upgrade path they send. Normalise the path and fall back to a default
     // route so we can still complete the upgrade instead of tearing the socket down.
@@ -97,50 +111,135 @@ class BaseSocketServer {
     })();
 
     const route =
-      this.routes.find(r => r.path === path) ||
-      (this.fallbackToRoot ? this.routes.find(r => r.path === '/') : undefined);
+      this.routes.find(r => r.path === 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) {
-    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;
+  addRoute(RouteClass) {
+    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() {
-    if (!this._shutdownPromise) this._shutdownPromise = this.performShutdown();
-    return this._shutdownPromise;
-  }
-
-  async performShutdown() {
-    this.server.off?.('upgrade', this._upgradeHandler);
-    const errors = await settleTasks(this.routes.map(route => () => route.shutdown?.()));
-    if (this.closeServerOnShutdown && this.server.listening) {
-      try {
-        await closeServer(this.server);
-      } catch (error) {
-        errors.push(error);
-      }
-    }
-    throwCleanupErrors(errors, 'One or more WebSocket server cleanup operations failed.');
-  }
-}
+  shutdown() {
+    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));
+  }
+}
 
 module.exports = { BaseSocketServer, SOCKET_OPTIONS };

package/src/ws/DefaultHandler.js

@@ -5,9 +5,9 @@ class DefaultHandler extends BaseHandler {
         super("DefaultHandler");
     }
 
-    onMessage(socket, message) {
-        socket.sendJson({ message: `I got your message of ${JSON.stringify(message)}` });
-    }
-}
+    onMessage(socket, message) {
+        socket.sendJson({ message: `I got your message of ${JSON.stringify(message)}` });
+    }
+}
 
-module.exports = DefaultHandler;
+module.exports = DefaultHandler;

package/src/ws/DefaultRoute.js

@@ -2,14 +2,14 @@ const SocketRoute  = require("./SocketRoute");
 const DefaultHandler = require('./DefaultHandler');
 
 class DefaultRoute extends SocketRoute {
-    constructor(server, options = {}) {
-        super({
-            server,
-            path: "/",
-            handlers: [DefaultHandler],
-            logger: options.logger,
-        })
+    constructor(server, options = {}) {
+        super({
+            server,
+            path: "/",
+            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;