redweb 0.13.5 → 0.15.0

package/src/htmx/metadata.js

@@ -178,7 +178,10 @@ function page(routePath, options = {}) {
     if (!['connection', 'shared'].includes(scope)) {
         throw new TypeError('Page scope must be "connection" or "shared".');
     }
-    if (typeof live !== 'boolean') throw new TypeError('Page live must be a boolean.');
+    if (typeof live !== 'boolean') throw new TypeError('Page live must be a boolean.');
+    if (options.socket !== undefined && (typeof options.socket !== 'function' || !live || scope !== 'connection')) {
+        throw new TypeError('Page socket requires a route class and a live connection-scoped page.');
+    }
     if (layout !== undefined && typeof layout !== 'function') throw new TypeError('Page layout must be a function.');
     const head = pageHead(options.head);
     const cache = pageCache(options.cache, live);
@@ -189,7 +192,8 @@ function page(routePath, options = {}) {
         PAGE_METADATA.set(PageClass, Object.freeze({
             path: routePath,
             template,
-            scope,
+            scope,
+            ...(options.socket && { socket: options.socket }),
             ...(live === false && { live: false }),
             ...(head && { head }),
             ...(cache && { cache }),

package/src/ws/BaseHandler.js

@@ -20,10 +20,12 @@ class BaseHandler {
      */
     async handleMessage(socket, message) {
         const validationResult = await this.validateMessage(message, socket);
-        if (validationResult === false) {
-            throw new Error('Invalid message');
-        }
-        return this.onMessage(socket, message);
+        if (validationResult === false) {
+            throw new Error('Invalid message');
+        }
+        const guard = require('./HandlerGuard').guards.get(socket);
+        if (guard) await guard();
+        return this.onMessage(socket, message);
     }
 
     validateMessage() {

package/src/ws/BaseSocketServer.js

@@ -12,6 +12,7 @@ const { PLACEMENT_REDIRECT, ADMISSION_SETTLEMENT } = require('./AdmissionPolicy'
 const { PROTOCOL_REJECTION } = require('./ProtocolPolicy');
 const { RequestFailure, UPGRADE_REJECTION } = require('../access/RequestFailure');
 const OwnedServerLifecycle = require('../OwnedServerLifecycle');
+const { scheduleStartupCleanup } = require('../StartupCleanup');
 const {
   listenServer,
   closeServer,
@@ -62,15 +63,14 @@ class BaseSocketServer {
       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]);
+          this.routes.push(route);
           throw new Error('WebSocket route paths must be unique.');
         }
         this.routes.push(route);
       }
     } catch (error) {
       this._ownedServer?.dispose();
-      this.disposeRoutes(this.routes);
-      throw error;
+      throw scheduleStartupCleanup(error, () => this.disposeRoutes(this.routes));
     }
 
     this._upgradeHandler = this.handleUpgrade.bind(this);
@@ -90,17 +90,18 @@ class BaseSocketServer {
     } catch (error) {
       this.server.off('upgrade', this._upgradeHandler);
       this._ownedServer?.dispose();
-      this.disposeRoutes(this.routes);
-      throw error;
+      throw scheduleStartupCleanup(error, () => this.disposeRoutes(this.routes));
     }
   }
 
-  disposeRoutes(routes) {
-    routes.forEach(route => {
-      Promise.resolve()
-        .then(() => route.shutdown?.())
-        .catch(error => this.logger?.error?.('Error shutting down route:', error));
-    });
+  async disposeRoutes(routes) {
+    const errors = await settleTasks(routes.map(route => () => route.shutdown?.()));
+    if (errors.length) {
+      for (const error of errors) {
+        try { this.logger?.error?.('Error shutting down route:', error); } catch { /* Preserve the cleanup failure even if logging fails. */ }
+      }
+      throw new AggregateError(errors, 'Route construction rollback failed.');
+    }
   }
 
   handleUpgrade(req, sock, head) {
@@ -208,8 +209,7 @@ class BaseSocketServer {
   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}.`);
+      throw scheduleStartupCleanup(new Error(`A WebSocket route already exists at ${route.path}.`), () => this.disposeRoutes([route]));
     }
     this.routes.push(route);
     return route;

package/src/ws/HandlerGuard.js

@@ -0,0 +1,4 @@
+'use strict';
+// A private hook, never a field supplied by an incoming message.
+const guards = new WeakMap();
+module.exports = { guards };

package/src/ws/SocketAction.js

@@ -0,0 +1,16 @@
+'use strict';
+
+// Browser-safe metadata keeps the standalone contract entry free of Node rendering dependencies.
+const bindings = new WeakMap();
+function register(Handler, type) {
+    bindings.set(Handler, { Handler, type });
+    Object.defineProperty(Handler, 'with', { value(payload) {
+        const serialized = JSON.stringify(payload);
+        if (serialized === undefined || serialized.length > 65536) throw new TypeError('Socket action payload must be bounded JSON.');
+        const binding = Object.freeze({});
+        bindings.set(binding, { Handler, type, payload: JSON.parse(serialized) });
+        return binding;
+    } });
+    return Handler;
+}
+module.exports = { register, bindings };

package/src/ws/SocketContract.js

@@ -83,7 +83,7 @@ class SocketContract {
         if (!this.#validators.has(type)) throw new TypeError('Handler message type is not defined in the contract.');
         if (typeof callback !== 'function') throw new TypeError('A contract handler requires a callback.');
         const contract = this;
-        return class ContractHandler extends BaseHandler {
+        class ContractHandler extends BaseHandler {
             constructor() { super(type); }
             async handleMessage(socket, message) {
                 if (socket.context?.protocol?.version !== contract.version) throw new TypeError('The route must negotiate this contract version before handling messages.');
@@ -93,7 +93,8 @@ class SocketContract {
                 return super.handleMessage(socket, { ...message, payload });
             }
             onMessage(socket, message) { return callback(socket, message.payload, message); }
-        };
+        }
+        return require('./SocketAction').register(ContractHandler, type);
     }
 
     client(socket) { return new ContractClient(this, socket); }

package/src/ws/SocketRoute.js

@@ -117,6 +117,10 @@ class SocketRoute {
         const reservedOption = ['noServer', 'path', 'server', 'port']
             .find(option => Object.prototype.hasOwnProperty.call(websocketOptions, option));
         if (reservedOption) throw new TypeError(`Redweb controls websocketOptions.${reservedOption}.`);
+        const { closeTimeout = 5000 } = websocketOptions;
+        if (!Number.isInteger(closeTimeout) || closeTimeout < 1 || closeTimeout > 2147483647) {
+            throw new TypeError('`websocketOptions.closeTimeout` must be an integer between 1 and 2147483647 milliseconds.');
+        }
         if (!Number.isInteger(shutdownTimeoutMs) || shutdownTimeoutMs < 0) {
             throw new TypeError('`shutdownTimeoutMs` must be a non-negative integer.');
         }
@@ -135,7 +139,7 @@ class SocketRoute {
          * @type {string}
          */
         this.path = path;
-        this.websocketOptions = { ...websocketOptions };
+        this.websocketOptions = { ...websocketOptions, closeTimeout };
         this.logger = logger || { log() {}, warn() {}, error() {} };
         this.trustProxy = trustProxy;
         this.getClientKey = getClientKey;
@@ -165,7 +169,7 @@ class SocketRoute {
             throw new Error('Handler names must be unique within a route.');
         }
         this.clients = new Map();
-        this.server = new WebSocketServer({ ...websocketOptions, noServer: true });
+        this.server = new WebSocketServer({ ...this.websocketOptions, noServer: true });
         this.server.on('connection', this.handleConnection.bind(this));
         this.allowDuplicateConnections = Boolean(allowDuplicateConnections);
 
@@ -448,8 +452,9 @@ class SocketRoute {
             return false;
         } else {
             try {
-                await handler.handleMessage(sock, data);
-                return true;
+                // A handler may send a recoverable protocol error and explicitly decline
+                // success. Undefined remains successful for existing command handlers.
+                return await handler.handleMessage(sock, data) !== false;
             } catch (error) {
                 if (this.sendAccessFailure(sock, error, { requestId: data.requestId })) return false;
                 if (error instanceof InboundContractValidationError) {

package/recipes/shared/run-app.test.cjs

@@ -1,158 +0,0 @@
-const assert = require('node:assert/strict');
-const { test } = require('node:test');
-const { spawn } = require('node:child_process');
-
-// Each case uses its own Node process, real HTTP/TCP/WS resources and real timers.
-// Windows cannot deliver POSIX signals through child.kill, so only that platform
-// explicitly emits the signal event inside the child. Linux uses real OS signals.
-const fixture = String.raw`
-const assert = require('node:assert/strict');
-const http = require('node:http');
-const net = require('node:net');
-const { once } = require('node:events');
-const WebSocket = require('ws');
-const mode = process.argv[1];
-const signals = ['SIGINT', 'SIGTERM'];
-const initial = signals.map(signal => process.listenerCount(signal));
-const { runApp } = require('./dist/run-app.js');
-assert.deepEqual(signals.map(signal => process.listenerCount(signal)), initial);
-require('./dist/app.js');
-assert.deepEqual(signals.map(signal => process.listenerCount(signal)), initial);
-let cleanups = 0;
-process.once('beforeExit', () => console.log(JSON.stringify({ cleanups, signals: signals.map(signal => process.listenerCount(signal)), initial })));
-const signal = name => process.platform === 'win32' ? process.emit(name) : process.kill(process.pid, name);
-if (mode === 'invalid') {
-    for (const value of [0, -1, NaN, Infinity, 1.5, 2147483648]) assert.throws(() => runApp(() => { throw Error('must not execute'); }, value), RangeError);
-} else if (mode === 'factory') {
-    assert.equal(runApp(() => { throw Error('private startup detail'); }), undefined);
-} else {
-    if (mode === 'preserve') process.exitCode = '7';
-    const server = http.createServer((_request, response) => response.end('ready'));
-    const wss = new WebSocket.Server({ server });
-    wss.on('error', () => {}); // The HTTP listener error is owned by runApp.
-    const peers = new Set();
-    server.on('connection', peer => { peers.add(peer); peer.on('close', () => peers.delete(peer)); });
-    const close = async () => {
-        for (const peer of peers) peer.destroy();
-        for (const peer of wss.clients) peer.terminate();
-        await new Promise(resolve => wss.close(resolve));
-        await new Promise(resolve => server.close(resolve));
-    };
-    const app = runApp(() => ({ server, shutdown() {
-        cleanups++;
-        console.log('cleanup-started');
-        if (mode === 'throw') { void close(); throw Error('private cleanup detail'); }
-        if (mode === 'reject-open') return Promise.reject(Error('private cleanup detail'));
-        return close().then(async () => {
-            if (mode === 'hung') return new Promise(() => {});
-            if (mode === 'reject') throw Error('private cleanup detail');
-            if (mode === 'repeat') {
-                signal('SIGINT'); signal('SIGTERM');
-                server.emit('error', Error('private listener detail'));
-            }
-            await new Promise(resolve => setTimeout(resolve, 20));
-        });
-    } }), 200);
-    assert.equal(app.server, server);
-    (async () => {
-        if (mode === 'occupied') {
-            const other = http.createServer();
-            await new Promise(resolve => other.listen(0, '127.0.0.1', resolve));
-            server.once('error', () => other.close());
-            server.listen(other.address().port, '127.0.0.1');
-            return;
-        }
-        await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
-        const port = server.address().port;
-        const response = await fetch('http://127.0.0.1:' + port);
-        assert.equal(await response.text(), 'ready');
-        const peer = net.connect(port, '127.0.0.1');
-        peer.on('error', () => {});
-        await once(peer, 'connect');
-        peer.write('GET / HTTP/1.1\r\nHost: localhost\r\n');
-        const socket = new WebSocket('ws://127.0.0.1:' + port);
-        socket.on('error', () => {});
-        await once(socket, 'open');
-        if (mode === 'native-close') {
-            for (const connection of peers) connection.destroy();
-            server.close();
-            return;
-        }
-        // A partial HTTP peer otherwise prevents native close; application cleanup
-        // begins via the signal and the later native close must not end its timer.
-        signal(mode === 'interrupt' ? 'SIGINT' : 'SIGTERM');
-    })().catch(error => { console.error(error); process.exit(99); });
-}
-`;
-
-function execute(mode, t, args = ['-e', fixture, mode], env = process.env) {
-    return new Promise((resolve, reject) => {
-        const child = spawn(process.execPath, args, { cwd: process.cwd(), env, windowsHide: true });
-        let stdout = '', stderr = '';
-        let timedOut = false, finished = false;
-        const closed = new Promise(resolve => child.once('close', () => { finished = true; resolve(); }));
-        const deadline = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, 5000);
-        t.after(async () => {
-            clearTimeout(deadline);
-            if (!finished) { child.kill('SIGKILL'); await closed; }
-        });
-        child.stdout.on('data', data => { stdout += data; });
-        child.stderr.on('data', data => { stderr += data; });
-        child.once('error', reject);
-        child.once('close', (code, signal) => {
-            clearTimeout(deadline);
-            if (timedOut) reject(new Error(`Lifecycle child timed out: ${mode}\n${stdout}\n${stderr}`));
-            else resolve({ code, signal, stdout, stderr });
-        });
-    });
-}
-
-test('the actual application entrypoint exits cleanly when its port is occupied', { timeout: 7000 }, async t => {
-    const net = require('node:net');
-    const { once } = require('node:events');
-    const fs = require('node:fs');
-    const path = require('node:path');
-    const directory = fs.mkdtempSync(path.join(require('node:os').tmpdir(), 'redweb-entrypoint-'));
-    const occupied = net.createServer(socket => socket.destroy());
-    const loopback = net.createServer(socket => socket.destroy());
-    let failure;
-    try {
-        occupied.listen(0, '0.0.0.0');
-        await once(occupied, 'listening');
-        // Windows permits distinct wildcard/loopback binds on the same port.
-        // Hold both addresses; Unix may already reject the second bind.
-        loopback.listen(occupied.address().port, '127.0.0.1');
-        try { await once(loopback, 'listening'); }
-        catch (error) { assert.equal(error.code, 'EADDRINUSE'); }
-        const env = { ...process.env, PORT: String(occupied.address().port), NODE_ENV: 'test', DASHBOARD_DATABASE: path.join(directory, 'test.sqlite') };
-        delete env.DASHBOARD_ORIGIN;
-        const result = await execute('actual-entrypoint', t, ['dist/app.js'], env);
-        assert.equal(result.code, 1, `${result.stdout}\n${result.stderr}`);
-        assert.equal(result.signal, null);
-        assert.match(result.stderr, /Application listener failed/);
-    } catch (error) { failure = error; }
-    const cleanup = await Promise.allSettled([
-        ...[occupied, loopback].map(server => new Promise((resolve, reject) => server.close(error =>
-            error && error.code !== 'ERR_SERVER_NOT_RUNNING' ? reject(error) : resolve()))),
-        fs.promises.rm(directory, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }),
-    ]);
-    const failures = [...(failure ? [failure] : []), ...cleanup.filter(result => result.status === 'rejected').map(result => result.reason)];
-    if (failures.length) throw new AggregateError(failures, 'Entrypoint verification or cleanup failed');
-});
-
-for (const mode of ['normal', 'interrupt', 'native-close', 'invalid', 'factory', 'throw', 'reject', 'reject-open', 'hung', 'occupied', 'repeat', 'preserve']) {
-    test(`entrypoint cleanup: ${mode}`, { timeout: 7000 }, async t => {
-        const result = await execute(mode, t);
-        const expected = ['normal', 'interrupt', 'native-close', 'invalid'].includes(mode) ? 0 : mode === 'preserve' ? 7 : 1;
-        assert.equal(result.code, expected, `${result.stdout}\n${result.stderr}`);
-        assert.equal(result.signal, null);
-        assert.doesNotMatch(result.stderr, /private .* detail/);
-        const noApp = ['invalid', 'factory'].includes(mode);
-        assert.equal((result.stdout.match(/cleanup-started/g) || []).length, noApp ? 0 : 1);
-        if (['hung', 'reject-open'].includes(mode)) assert.match(result.stderr, /exceeded its deadline/);
-        if (['normal', 'interrupt', 'native-close', 'invalid', 'factory', 'preserve'].includes(mode)) {
-            const snapshot = JSON.parse(result.stdout.trim().split(/\r?\n/).at(-1));
-            assert.deepEqual(snapshot.signals, snapshot.initial);
-        }
-    });
-}

package/recipes/shared/run-app.ts

@@ -1,50 +0,0 @@
-import type { Server } from 'node:http';
-
-interface Application { server: Server; shutdown(): Promise<void>; }
-
-/** Entry-point policy only: importing a recipe never installs process handlers. */
-export function runApp<T extends Application>(createApp: () => T, shutdownTimeoutMs = 5000): T | undefined {
-    if (!Number.isInteger(shutdownTimeoutMs) || shutdownTimeoutMs < 1 || shutdownTimeoutMs > 2147483647) {
-        throw new RangeError('Application shutdown timeout must be a positive timer-safe integer.');
-    }
-    const fail = (message: string) => {
-        console.error(message);
-        if (Number(process.exitCode ?? 0) === 0) process.exitCode = 1;
-    };
-    let app: T;
-    try { app = createApp(); }
-    catch { fail('Application startup failed.'); return undefined; }
-
-    let closing: Promise<void> | undefined;
-    const stop = () => {
-        if (!closing) {
-            let failed = false;
-            const deadline = setTimeout(() => {
-                fail('Application cleanup exceeded its deadline; terminating the process.');
-                process.exit();
-            }, shutdownTimeoutMs);
-            closing = Promise.resolve().then(() => app.shutdown()).catch(() => {
-                failed = true;
-                fail('Application cleanup failed.');
-            }).finally(() => {
-                // Failed cleanup may leave live handles. Permit natural exit if none
-                // remain, but still force a bounded exit when resources were leaked.
-                if (failed) { deadline.unref(); return; }
-                clearTimeout(deadline);
-                process.off('SIGINT', stop);
-                process.off('SIGTERM', stop);
-                app.server.off('error', onError);
-                app.server.off('close', stop);
-            });
-        }
-        return closing;
-    };
-    const onError = () => { fail('Application listener failed.'); void stop(); };
-    // Persistent handlers keep repeated signals from bypassing active cleanup.
-    process.on('SIGINT', stop);
-    process.on('SIGTERM', stop);
-    app.server.on('error', onError);
-    // Native close can precede database/worker cleanup: it starts, never ends, shutdown.
-    app.server.once('close', stop);
-    return app;
-}