redweb 0.12.0 → 0.13.0

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

@@ -0,0 +1,158 @@
+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

@@ -0,0 +1,50 @@
+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;
+}

package/recipes/site/README.md

@@ -0,0 +1,4 @@
+## Site starter
+
+`defineSite` supplies one layout and stylesheet for `/` and `/about`. Each page sets its own title.
+Pages use server-rendered TSX with no React dependency and no injected browser runtime.

package/recipes/site/app.test.cjs

@@ -0,0 +1,19 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { listen } = require('./network.cjs');
+
+test('pages share a layout, serve CSS, and require no browser runtime', { timeout: 10000 }, async t => {
+    const origin = await listen(t);
+    for (const route of ['/', '/about']) {
+        const response = await fetch(`${origin}${route}`);
+        assert.equal(response.status, 200);
+        const document = await response.text();
+        assert.match(document, /<nav>/);
+        assert.doesNotMatch(document, /<script/);
+        const css = document.match(/<link rel="stylesheet" href="([^"]+)"/)[1];
+        const stylesheet = await fetch(`${origin}${css}`);
+        assert.equal(stylesheet.status, 200);
+        assert.match(await stylesheet.text(), /\.home/);
+    }
+    assert.equal((await fetch(`${origin}/missing`)).status, 404);
+});

package/recipes/site/app.tsx

@@ -0,0 +1,25 @@
+import { defineSite, start, type LiveHtmlStartOptions } from 'redweb';
+import { runApp } from './run-app';
+
+const site = defineSite({
+    css: 'app.css',
+    layout: content => <body><nav><a href="/">Home</a> · <a href="/about">About</a></nav>{content}</body>,
+});
+
+@site.page('/', { head: { title: 'My Redweb site', description: 'A server-rendered TypeScript site.' } })
+export class HomePage {
+    render() {
+        return <main class="home"><h1>Your server-rendered app is ready.</h1><p>Edit src/app.tsx to make it yours.</p></main>;
+    }
+}
+
+@site.page('/about', { head: { title: 'About' } })
+export class AboutPage {
+    render() { return <main class="home"><h1>About</h1><p>Shared layout, separate pages, no browser JavaScript.</p></main>; }
+}
+
+export function createApp(options: LiveHtmlStartOptions = {}) {
+    return start([HomePage, AboutPage], { port: Number(process.env.PORT ?? 8181), templateRoot: __dirname, ...options });
+}
+
+if (require.main === module) runApp(createApp);

package/recipes/socket/README.md

@@ -0,0 +1,39 @@
+## Socket starter
+
+This is a WebSocket service, not an HTML page. Connect to `ws://localhost:8181/match?redwebVersion=1`.
+The URL selects the match route; `type` selects its individual `Join`, `Move`, or `Resume` handler.
+There are no socket decorators or secondary `message.action` dispatchers.
+
+Read `src/contract.ts`, `src/app.tsx`, and `src/handlers.ts` together: they define
+the wire contract, route/server configuration, and join/move/resume handlers.
+The displayed handlers depend on those other generated files; initialize the
+complete recipe first. Session ownership is separate from room fan-out.
+
+`src/contract.ts` declares the wire payloads once using Zod, a Standard Schema validator. Both the server and a bundled browser/Node client can import it for runtime validation and inferred TypeScript types:
+
+```ts
+import { match } from './contract';
+
+const socket = new WebSocket('ws://localhost:8181/match?redwebVersion=1');
+const client = match.client(socket);
+socket.addEventListener('open', () => {
+    client.send('join', { name: 'Ada' }).catch(console.error);
+});
+socket.addEventListener('message', async event => {
+    try { console.log(await client.parse(event)); }
+    catch (error) { console.error(error); }
+});
+```
+
+The initial `state` response contains `{ session, name, x, y }`. Send `move` with `{ x: 7, y: -3 }` to change your server-owned position; send `resume` with `{ session }` on a new connection to recover it. Messages are processed in order on each connection. The client wrapper validates messages; it does not open or reconnect the WebSocket for you. Use WSS outside local development.
+
+`npm test` opens real sockets and checks independent players, server-side moves, disconnect/resume, client validation, and server rejection of a malformed raw message. The starter also passes with the original source directory unavailable after building.
+
+### Boundaries
+
+- This demonstrates session-aware dispatch, not a complete authoritative game simulation. Coordinates are bounded integers; applications must enforce their own movement/rate/game rules.
+- The random session ID is a bearer credential. Anyone holding it can resume that player and replace its previous connection. Keep it private; do not broadcast the `state` response to other players. Add account authentication and bind sessions to authenticated identity for production.
+- Sessions are in memory, local to this server, capped at 100, and expire 30 seconds after disconnect. Server restart loses them. This is not persistent storage or a multi-instance session system.
+- Calling `join` or `resume` while already joined is rejected. Movement before joining and unknown/expired sessions are rejected. Application failures currently use the protocol's sanitized `HANDLER_FAILED` error.
+- Invalid contract payloads produce `INVALID_PAYLOAD` and close that connection with code 1008. The contract's `state` type is server output; it has no client-callable handler.
+- Transport and heartbeat bounds are illustrative; tune and load-test them for your deployment. Zod belongs to this starter, not Redweb's runtime dependencies.

package/recipes/socket/app.test.cjs

@@ -0,0 +1,85 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { once } = require('node:events');
+const { listen, connect } = require('./network.cjs');
+const { match } = require('../dist/contract.js');
+
+async function rejected(client, type, payload) {
+    const closed = once(client.socket, 'close');
+    await match.client(client.socket).send(type, payload);
+    assert.equal((await client.receive(message => message.type === 'error')).error.code, 'HANDLER_FAILED');
+    assert.equal((await closed)[0], 1011);
+}
+
+test('join, move and resume use separate validated handlers with isolated server sessions', { timeout: 10000 }, async t => {
+    const origin = await listen(t);
+    const url = `${origin.replace('http:', 'ws:')}/match?redwebVersion=${match.version}`;
+    const first = await connect(t, url, origin);
+    const second = await connect(t, url, origin);
+    const client = match.client(first.socket);
+    await client.send('join', { name: ' Ada ' }, { requestId: 'join-1' });
+    const joined = await first.receive(message => message.type === 'state');
+    assert.equal(joined.requestId, 'join-1');
+    assert.equal(joined.payload.name, 'Ada');
+    assert.deepEqual([joined.payload.x, joined.payload.y], [0, 0]);
+
+    const unjoined = await connect(t, url, origin);
+    await rejected(unjoined, 'move', { x: 2, y: 3 });
+    await match.client(second.socket).send('join', { name: 'Grace' });
+    const other = await second.receive(message => message.type === 'state');
+    assert.notEqual(other.payload.session, joined.payload.session);
+
+    await client.send('move', { x: 7, y: -3 }, { requestId: 'move-1' });
+    assert.deepEqual((await first.receive(message => message.type === 'state')).payload,
+        { ...joined.payload, x: 7, y: -3 });
+    await assert.rejects(client.send('move', { x: 101, y: 0 }), { code: 'INVALID_PAYLOAD' });
+    const closed = once(first.socket, 'close');
+    first.socket.close();
+    await closed;
+    const resumed = await connect(t, url, origin);
+    await match.client(resumed.socket).send('resume', { session: joined.payload.session });
+    assert.deepEqual((await resumed.receive(message => message.type === 'state')).payload,
+        { ...joined.payload, x: 7, y: -3 });
+
+    // Bypass client validation to prove the server independently rejects malformed input.
+    const rejectedClosed = once(resumed.socket, 'close');
+    resumed.send({ v: match.version, type: 'move', payload: { x: 'wrong', y: 0 } });
+    assert.equal((await resumed.receive(message => message.type === 'error')).error.code, 'INVALID_PAYLOAD');
+    assert.equal((await rejectedClosed)[0], 1008);
+});
+
+test('joined identities cannot join/resume again and unknown sessions fail closed', { timeout: 10000 }, async t => {
+    const origin = await listen(t);
+    const url = `${origin.replace('http:', 'ws:')}/match?redwebVersion=${match.version}`;
+    for (const type of ['join', 'resume']) {
+        const client = await connect(t, url, origin);
+        await match.client(client.socket).send('join', { name: 'Ada' });
+        const joined = await client.receive(message => message.type === 'state');
+        await rejected(client, type, type === 'join' ? { name: 'Replacement' } : { session: joined.payload.session });
+    }
+    const visitor = await connect(t, url, origin);
+    await rejected(visitor, 'resume', { session: require('node:crypto').randomUUID() });
+});
+
+test('retained disconnected sessions count toward the bounded session capacity', { timeout: 20000 }, async t => {
+    const origin = await listen(t);
+    const url = `${origin.replace('http:', 'ws:')}/match?redwebVersion=${match.version}`;
+    const sessions = new Set();
+    for (let index = 0; index < 100; index++) {
+        const client = await connect(t, url, origin);
+        await match.client(client.socket).send('join', { name: `player-${index}` });
+        const joined = await client.receive(message => message.type === 'state');
+        sessions.add(joined.payload.session);
+        const closed = once(client.socket, 'close');
+        client.socket.close();
+        await closed;
+    }
+    assert.equal(sessions.size, 100);
+    const overflow = await connect(t, url, origin);
+    await rejected(overflow, 'join', { name: 'overflow' });
+    // Capacity rejection does not invalidate a previously issued bearer session.
+    const resumed = await connect(t, url, origin);
+    const session = sessions.values().next().value;
+    await match.client(resumed.socket).send('resume', { session });
+    assert.equal((await resumed.receive(message => message.type === 'state')).payload.session, session);
+});

package/recipes/socket/app.tsx

@@ -0,0 +1,30 @@
+import { SocketRoute, SocketServer, type SocketServerOptions } from 'redweb';
+import { match } from './contract';
+import { Join, Move, Resume } from './handlers';
+import { runApp } from './run-app';
+
+export class MatchRoute extends SocketRoute {
+    constructor() {
+        super({
+            path: '/match',
+            handlers: [Join, Move, Resume],
+            protocol: match.protocol,
+            orderedMessages: true,
+            sessions: { ttlMs: 30000, maxSessions: 100 },
+            heartbeat: { intervalMs: 15000, timeoutMs: 10000 },
+            allowDuplicateConnections: true,
+            websocketOptions: { maxPayload: 4096 },
+            limits: { maxConnections: 100, maxPendingMessages: 32, maxBufferedBytes: 65536 },
+        });
+    }
+}
+
+export function createApp(options: SocketServerOptions = {}) {
+    return new SocketServer({
+        port: Number(process.env.PORT ?? 8181),
+        routes: [MatchRoute],
+        ...options,
+    });
+}
+
+if (require.main === module) runApp(createApp);

package/recipes/socket/contract.ts

@@ -0,0 +1,12 @@
+import { defineSocketContract } from 'redweb/contract';
+import { z } from 'zod';
+
+const position = { x: z.number().int().min(-100).max(100), y: z.number().int().min(-100).max(100) };
+
+// Share this module with a browser or Node client. It imports no server application code.
+export const match = defineSocketContract('1', {
+    join: z.object({ name: z.string().trim().min(1).max(40) }).strict(),
+    move: z.object(position).strict(),
+    resume: z.object({ session: z.string().uuid() }).strict(),
+    state: z.object({ session: z.string().uuid(), name: z.string(), ...position }).strict(),
+});

package/recipes/socket/handlers.ts

@@ -0,0 +1,40 @@
+import { randomUUID } from 'node:crypto';
+import type { RedWebSocket } from 'redweb';
+import { match } from './contract';
+
+class Player {
+    readonly session = randomUUID();
+    x = 0;
+    y = 0;
+    constructor(readonly name: string) {}
+}
+
+function requireUnjoined(socket: RedWebSocket) {
+    if (socket.context?.session) throw new Error('Already joined.');
+}
+
+function currentPlayer(socket: RedWebSocket) {
+    const session = socket.context?.session as { data?: unknown } | null | undefined;
+    if (!(session?.data instanceof Player)) throw new Error('Join or resume first.');
+    return session.data;
+}
+
+export const Join = match.handler('join', (socket, { name }, message) => {
+    requireUnjoined(socket);
+    const player = new Player(name);
+    if (!socket.createSession?.(player.session, player)) throw new Error('Session capacity reached.');
+    return match.send(socket, 'state', player, { requestId: message.requestId });
+});
+
+export const Move = match.handler('move', (socket, { x, y }, message) => {
+    const player = currentPlayer(socket);
+    player.x = x;
+    player.y = y;
+    return match.send(socket, 'state', player, { requestId: message.requestId });
+});
+
+export const Resume = match.handler('resume', (socket, { session }, message) => {
+    requireUnjoined(socket);
+    if (!(socket.resumeSession?.(session) instanceof Player)) throw new Error('Session expired or unknown.');
+    return match.send(socket, 'state', currentPlayer(socket), { requestId: message.requestId });
+});

package/src/OwnedServerLifecycle.js

@@ -0,0 +1,66 @@
+'use strict';
+
+/** Tracks only a caller-owned listener, including pre-HTTP/pre-TLS TCP peers. */
+class OwnedServerLifecycle {
+    constructor(server) {
+        this.server = server;
+        this.connections = new Set();
+        this.forced = false;
+        this.onEmpty = null;
+        this.onConnection = socket => {
+            this.connections.add(socket);
+            socket.once('close', () => {
+                this.connections.delete(socket);
+                this.onEmpty?.();
+            });
+            if (this.forced) socket.destroy();
+        };
+        this.dispose = () => {
+            server.off('connection', this.onConnection);
+            server.off('close', this.dispose);
+        };
+        server.on('connection', this.onConnection);
+        server.once('close', this.dispose);
+    }
+
+    forceClose() {
+        this.forced = true;
+        const errors = [];
+        // A failed/non-cooperating close callback must not leave admission open.
+        if (this.server.listening) {
+            try { this.server.close(); } catch (error) { errors.push(error); }
+        }
+        for (const socket of this.connections) {
+            try { socket.destroy(); } catch (error) { errors.push(error); }
+        }
+        return errors;
+    }
+
+    close(timeoutMs, closeCallback) {
+        let timer;
+        const empty = new Promise(resolve => {
+            this.onEmpty = () => { if (this.connections.size === 0) resolve(); };
+        });
+        const closing = Promise.resolve().then(closeCallback).catch(error => {
+            const cleanup = this.forceClose();
+            if (cleanup.length) throw new AggregateError([error, ...cleanup], error.message, { cause: error });
+            throw error;
+        });
+        const timeout = new Promise((resolve, reject) => {
+            timer = setTimeout(() => {
+                const errors = this.forceClose();
+                if (errors.length) reject(new AggregateError(errors, 'Owned listener force-close failed.'));
+                else resolve();
+            }, timeoutMs);
+        });
+        this.onEmpty();
+        return Promise.race([Promise.all([closing, empty]), timeout]).then(() => undefined).finally(() => {
+            clearTimeout(timer);
+            this.onEmpty = null;
+            // Retain the forced-peer guard until native close when peers remain.
+            if (!this.server.listening && this.connections.size === 0) this.dispose();
+        });
+    }
+}
+
+module.exports = OwnedServerLifecycle;

package/src/access/AccessPolicy.js

@@ -0,0 +1,37 @@
+const { BoundedOperation, OperationInterrupted } = require('../async/BoundedOperation');
+const codes = require('./failure-codes.json');
+
+class AccessDenied extends Error {
+    constructor(code = 'ACCESS_DENIED') {
+        const safeCode = typeof code === 'string' && code.startsWith('ACCESS_') && Object.hasOwn(codes, code) ? code : 'ACCESS_DENIED';
+        super(codes[safeCode].message);
+        this.code = safeCode;
+        this.status = codes[safeCode].status;
+    }
+}
+
+/** Explicit permission, not identity lookup. Only a literal true permits work. */
+class AccessPolicy {
+    constructor(authorize, timeoutMs) {
+        if (authorize !== undefined && typeof authorize !== 'function') throw new TypeError('authorize must be a function.');
+        if (authorize === undefined && timeoutMs !== undefined) throw new TypeError('authorizationTimeoutMs requires authorize.');
+        this.authorize = authorize;
+        this.boundary = new BoundedOperation(timeoutMs);
+        Object.freeze(this);
+    }
+
+    async check(context, input) {
+        if (!this.authorize) return;
+        try {
+            const allowed = await this.boundary.run(signal => this.authorize(Object.freeze({ ...context, signal }), input), context?.signal);
+            if (allowed !== true) throw new AccessDenied();
+        } catch (error) {
+            if (error instanceof AccessDenied) throw new AccessDenied(error.code);
+            if (error instanceof OperationInterrupted) throw new AccessDenied(error.reason === 'timeout' ? 'ACCESS_TIMEOUT' : 'ACCESS_CANCELLED');
+            // Do not turn a broken policy into a permission denial or expose its details.
+            throw new Error('Authorization policy failed.');
+        }
+    }
+}
+
+module.exports = { AccessPolicy, AccessDenied };

package/src/access/AuthenticationFailure.js

@@ -0,0 +1,13 @@
+'use strict';
+const codes = require('./failure-codes.json');
+
+/** Safe authentication diagnostics shared by page and socket boundaries. */
+class AuthenticationFailure extends Error {
+    constructor(code = 'AUTHENTICATION_REQUIRED') {
+        super(codes.AUTHENTICATION_REQUIRED.message);
+        this.code = typeof code === 'string' && code.startsWith('AUTHENTICATION_') && Object.hasOwn(codes, code) ? code : 'AUTHENTICATION_FAILED';
+        this.status = codes[this.code].status;
+    }
+}
+
+module.exports = AuthenticationFailure;

package/src/access/RequestFailure.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const { STATUS_CODES } = require('http');
+const AuthenticationFailure = require('./AuthenticationFailure');
+const { AccessDenied } = require('./AccessPolicy');
+const ActionInputError = require('../validation/ActionInputError');
+const codes = require('./failure-codes.json');
+
+const UPGRADE_REJECTION = Symbol('redweb.upgradeRejection');
+
+/** Only allowlisted codes cross the HTTP upgrade boundary; never callback text. */
+class RequestFailure extends Error {
+    constructor(code) {
+        const safeCode = typeof code === 'string' && Object.hasOwn(codes, code) ? code : 'ADMISSION_FAILED';
+        const statusCode = codes[safeCode].status;
+        super(safeCode.startsWith('AUTHENTICATION_') ? codes.AUTHENTICATION_REQUIRED.message : codes[safeCode].message || STATUS_CODES[statusCode]);
+        this.code = safeCode;
+        this.status = statusCode;
+        this.rejection = Object.freeze({
+            statusCode, statusText: STATUS_CODES[statusCode],
+            headers: Object.freeze({ 'Redweb-Error': safeCode, 'Cache-Control': 'no-store' }),
+        });
+    }
+
+    static from(error, fallback = 'ADMISSION_FAILED') {
+        try {
+            return new RequestFailure(error instanceof RequestFailure || error instanceof AuthenticationFailure || error instanceof AccessDenied || error instanceof ActionInputError
+                ? error.code : fallback);
+        } catch { return new RequestFailure(fallback); }
+    }
+}
+
+module.exports = { RequestFailure, UPGRADE_REJECTION };

package/src/access/failure-codes.json

@@ -0,0 +1,25 @@
+{
+  "REQUEST_INVALID": { "status": 400 },
+  "AUTHENTICATION_REQUIRED": { "status": 401, "message": "Page authentication did not complete successfully." },
+  "AUTHENTICATION_FAILED": { "status": 500 },
+  "AUTHENTICATION_TIMEOUT": { "status": 503 },
+  "AUTHENTICATION_CANCELLED": { "status": 503 },
+  "ORIGIN_DENIED": { "status": 403 },
+  "PLACEMENT_DENIED": { "status": 403 },
+  "PLACEMENT_INVALID": { "status": 500 },
+  "ADMISSION_FAILED": { "status": 500 },
+  "ADMISSION_TIMEOUT": { "status": 503 },
+  "ADMISSION_CANCELLED": { "status": 503 },
+  "ADMISSION_CAPACITY": { "status": 503 },
+  "SERVER_DRAINING": { "status": 503 },
+  "ROUTE_UNAVAILABLE": { "status": 503 },
+  "ACCESS_DENIED": { "status": 403, "message": "This operation is not permitted." },
+  "ACCESS_TIMEOUT": { "status": 503, "message": "Authorization timed out. The operation was not run." },
+  "ACCESS_CANCELLED": { "status": 503, "message": "Authorization was cancelled. The operation was not run." },
+  "ACCESS_CAPACITY": { "status": 503, "message": "Authorization capacity reached. The operation was not run." },
+  "PAGE_FAILED": { "status": 500, "message": "Page request failed." },
+  "PAGE_CAPACITY": { "status": 503, "message": "Page session capacity reached." },
+  "ACTION_INVALID_INPUT": { "status": 400, "message": "Action input is invalid. Check the form values and try again." },
+  "ACTION_VALIDATION_TIMEOUT": { "status": 503, "message": "Action input validation timed out. The action was not run." },
+  "ACTION_CANCELLED": { "status": 503, "message": "The connection closed before input validation completed. The action was not run." }
+}