redweb 0.13.3 → 0.14.0

package/recipes/dashboard/README.md

@@ -14,11 +14,11 @@ npm test
 npm run dev
 ```
 
-The provisioning command displays a randomly generated password once. Save it securely; there are no default accounts or passwords. Open **http://127.0.0.1:8181/login**, sign in, and add a card. A second signed-in tab updates immediately. Restart the app: your cards and unexpired credentials remain valid. Sign out all sessions to close every connected tab for that account and invalidate all its cookies.
+The provisioning command displays a randomly generated password once. Save it securely; there are no default accounts or passwords. Open **http://127.0.0.1:8181/login** or **http://localhost:8181/login**, sign in, and add a card. A second signed-in tab updates immediately. Restart the app: your cards and unexpired credentials remain valid. Sign out all sessions to close every connected tab for that account and invalidate all its cookies.
 
-`npm test` provisions temporary test accounts and a real temporary database, then exercises HTTP, WebSockets, isolation, restart, and session expiry. It never modifies your application database. Integration tests use no mocks. A separately labelled unit test injects a cleanup error after closing a real SQLite database to verify rejection handling; it does not simulate a real operating-system failure.
+`npm test` provisions temporary test accounts and a real temporary database, then exercises HTTP, WebSockets, isolation, restart, and session expiry. It never modifies your application database. Integration tests use no mocks, including hostile cross-loopback form and socket origins. Redweb's release gate also signs in with both valid and invalid credentials through a visible Chromium window, using `localhost` so synthetic request headers cannot hide browser-origin bugs. CI supplies a virtual display for that same headed test. A separately labelled unit test injects a cleanup error after closing a real SQLite database to verify rejection handling; it does not simulate a real operating-system failure.
 
-`npm run test:coverage` measures the TypeScript application through source maps, separately from Redweb's own instrumented-library coverage. It also waits through the actual one-minute login admission window without mocking the clock. The report includes TypeScript-generated decorator accessor functions; inspect that distinction rather than assuming a library coverage figure applies to this recipe. The generated npm configuration enforces this recipe's Node engine requirement before installation.
+`npm run test:coverage` measures the TypeScript application through source maps, separately from Redweb's own instrumented-library coverage. Login-window expiry uses the same real limiter with an explicitly short test configuration; it never waits through the production one-minute default. The report includes TypeScript-generated decorator accessor functions; inspect that distinction rather than assuming a library coverage figure applies to this recipe. The generated npm configuration enforces this recipe's Node engine requirement before installation.
 
 ## Where the behavior lives
 

package/recipes/dashboard/app.test.cjs

@@ -8,7 +8,7 @@ const { DatabaseSync } = require('node:sqlite');
 const { spawn, spawnSync } = require('node:child_process');
 const net = require('node:net');
 const { WebSocketServer, WebSocket } = require('ws');
-const { createApp, databasePath } = require('../dist/app');
+const { allowsDashboardOrigin, createApp, databasePath } = require('../dist/app');
 const { DashboardStore } = require('../dist/store');
 const { DashboardAuth, credentials, sessionToken } = require('../dist/auth');
 const { PrivateCards } = require('../dist/cards');
@@ -29,8 +29,8 @@ async function fixture(t, options = {}) {
     t.after(async () => { await app?.shutdown(); rmSync(directory, { recursive: true, force: true }); });
     async function restart() {
         await app?.shutdown();
-        app = createApp({ port: 0, database, ...options });
-        if (!app.server.listening) await once(app.server, 'listening');
+        app = createApp({ port: 0, database, signals: false, ...options });
+        await app.run();
         return `http://127.0.0.1:${app.server.address().port}`;
     }
     return { database, restart, origin: await restart(), get app() { return app; } };
@@ -70,9 +70,12 @@ async function cardClient(t, origin, cookie) {
 test('private live cards: real HTTP, sockets, isolation, reconnect, sign-out and durable restart', async t => {
     const fixtureApp = await fixture(t);
     let { origin } = fixtureApp;
+    const localhost = origin.replace('127.0.0.1', 'localhost');
     assert.equal((await fetch(`${origin}/login`)).status, 200);
     assert.equal((await fetch(origin)).status, 401);
     assert.equal((await post(origin, '/login', { account: 'alice', password }, '', 'https://foreign.example')).status, 403);
+    assert.equal((await post(origin, '/login', { account: 'alice', password }, '', localhost)).status, 403);
+    assert.equal((await post(localhost, '/login', { account: 'alice', password: 'wrong-password-at-least-16' })).status, 401);
     assert.equal((await post(origin, '/login', { account: 'alice', password: 'wrong-password-at-least-16' })).status, 401);
     const alice = await login(origin);
     const alice2 = await login(origin);
@@ -80,6 +83,14 @@ test('private live cards: real HTTP, sockets, isolation, reconnect, sign-out and
     const page = await fetch(origin, { headers: { Cookie: alice } });
     assert.match(page.headers.get('cache-control'), /private.*no-store/);
     assert.equal(page.headers.get('etag'), null);
+    const document = await page.text();
+    const pageConfig = JSON.parse(document.match(/id="__redweb_page">([^<]+)/)[1]);
+    const hostile = new WebSocket(`${origin.replace('http:', 'ws:')}${pageConfig.socketPath}?pageId=${pageConfig.pageId}&redwebVersion=${encodeURIComponent(pageConfig.version)}`,
+        { headers: { Cookie: alice, Origin: localhost } });
+    hostile.on('error', () => {});
+    const [, rejection] = await once(hostile, 'unexpected-response');
+    assert.equal(rejection.statusCode, 403);
+    rejection.resume();
     const first = await cardClient(t, origin, alice);
     const second = await cardClient(t, origin, alice2);
     const other = await cardClient(t, origin, bob);
@@ -124,6 +135,23 @@ test('private live cards: real HTTP, sockets, isolation, reconnect, sign-out and
     await client.items(value => value.length === 1);
 });
 
+test('unit: development accepts only equivalent loopback browser origins on the listening port', () => {
+    const expected = 'http://127.0.0.1:8181';
+    assert.equal(allowsDashboardOrigin('http://localhost:8181', expected, false, 'localhost:8181'), true);
+    assert.equal(allowsDashboardOrigin('http://127.0.0.1:8181', expected, false, '127.0.0.1:8181'), true);
+    assert.equal(allowsDashboardOrigin('http://[::1]:8181', expected, false, '[::1]:8181'), true);
+    assert.equal(allowsDashboardOrigin('http://localhost:8181', expected, false, '127.0.0.1:8181'), false);
+    assert.equal(allowsDashboardOrigin('https://localhost:8181', expected, false, 'localhost:8181'), false);
+    assert.equal(allowsDashboardOrigin('http://localhost:8182', expected, false, 'localhost:8182'), false);
+    assert.equal(allowsDashboardOrigin('http://localhost:8181/path', expected, false, 'localhost:8181'), false);
+    assert.equal(allowsDashboardOrigin('not an origin', expected, false, 'localhost:8181'), false);
+    assert.equal(allowsDashboardOrigin(undefined, expected, false, 'localhost:8181'), false);
+    assert.equal(allowsDashboardOrigin('http://localhost:8181', expected, false), false);
+    assert.equal(allowsDashboardOrigin('http://localhost:8181', expected, false, 'localhost:8181/path'), false);
+    assert.equal(allowsDashboardOrigin('https://dashboard.example', 'https://dashboard.example', true), true);
+    assert.equal(allowsDashboardOrigin('http://localhost:8181', 'https://dashboard.example', true), false);
+});
+
 test('session expiry closes idle sockets and rejects later HTTP access', async t => {
     const { origin } = await fixture(t, { sessionLifetimeMs: 1200 });
     const cookie = await login(origin);
@@ -200,6 +228,8 @@ test('logout fences password checks in flight; close and admission bounds stop n
     assert.equal(await closing, undefined);
     assert.equal(await auth.login('peer', 'alice', password), undefined);
     assert.throws(() => new DashboardAuth(store, 0));
+    assert.throws(() => new DashboardAuth(store, 3600000, 19));
+    assert.throws(() => new DashboardAuth(store, 3600000, 60001));
     const limited = new DashboardAuth(store);
     const concurrent = Array.from({ length: 5 }, (_, index) => limited.login(`peer-${index}`, 'alice', password));
     assert.equal(await concurrent[4], undefined);
@@ -266,11 +296,11 @@ test('incomplete HTTP uploads cannot keep shutdown or the database alive indefin
     const database = join(directory, 'drain.sqlite');
     let app;
     t.after(async () => { await app?.shutdown(); rmSync(directory, { recursive: true, force: true }); });
-    assert.throws(() => createApp({ port: 0, database, sessionLifetimeMs: 0 }), /lifetime/);
+    await assert.rejects(createApp({ port: 0, database, sessionLifetimeMs: 0 }).run(), /lifetime/);
     assert.throws(() => createApp({ port: 0, database, origin: 'https://example.com/path' }), /exact/);
     assert.throws(() => createApp({ port: 0, database, origin: 'ftp://example.com' }), /exact/);
-    app = createApp({ port: 0, database });
-    await once(app.server, 'listening');
+    app = createApp({ port: 0, database, shutdownTimeoutMs: 30 });
+    await app.run();
     const socket = net.connect(app.server.address().port, '127.0.0.1');
     t.after(() => socket.destroy());
     socket.on('error', () => {});
@@ -320,14 +350,14 @@ test('production origin/cookies and malformed forms use real HTTP', async t => {
 test('unit: listener-error cleanup observes rejection without hiding it from the application owner', async t => {
     const directory = mkdtempSync(join(tmpdir(), 'redweb-dashboard-cleanup-'));
     const database = join(directory, 'cards.sqlite');
-    const app = createApp({ port: 0, database });
+    const app = createApp({ port: 0, database, signals: false });
     t.after(async () => {
         // This test deliberately makes the returned cleanup promise reject.
         // Await settlement before removing files, including on assertion failure.
         await Promise.allSettled([app.shutdown()]);
         rmSync(directory, { recursive: true, force: true });
     });
-    await once(app.server, 'listening');
+    await app.run();
     const failure = new Error('Injected database cleanup failure');
     const close = DashboardStore.prototype.close;
     // Unit-only fault injection, not a claim of a naturally occurring SQLite
@@ -339,7 +369,7 @@ test('unit: listener-error cleanup observes rejection without hiding it from the
     app.server.emit('error', new Error('Injected listener failure'));
     const closing = app.shutdown();
     assert.equal(app.shutdown(), closing);
-    await assert.rejects(closing, error => error === failure);
+    await assert.rejects(closing, error => error.errors.length === 1 && error.errors[0] === failure);
     assert.equal(injected.mock.callCount(), 1);
     assert.equal(app.server.listening, false);
     injected.mock.restore();
@@ -421,10 +451,10 @@ test('real administrator and standalone startup commands expose errors and persi
     try { assert.ok(store.credentials('carol')); }
     finally { store.close(); }
     app = createApp({ database, port: 0 });
-    await once(app.server, 'listening');
+    await app.run();
     const unavailable = run('dist/app.js', [], { PORT: String(app.server.address().port) });
     assert.equal(unavailable.status, 1);
-    assert.match(unavailable.stderr, /Application listener failed/);
+    assert.match(unavailable.stderr, /EADDRINUSE/);
     // Windows kill('SIGTERM') terminates immediately without invoking Node handlers.
     // An actual IPC message delivers the signal event there; Unix uses its OS signal.
     const signalControl = join(directory, 'signal.cjs');

package/recipes/dashboard/app.tsx

@@ -1,15 +1,34 @@
 import express, { type ErrorRequestHandler } from 'express';
 import { mkdirSync } from 'node:fs';
+import type { IncomingMessage } from 'node:http';
 import { dirname, resolve } from 'node:path';
-import { page, start, type LivePageRequestContext } from 'redweb';
+import { defineApp, page, type LivePageRequestContext } from 'redweb';
 import { DashboardAuth, sessionToken } from './auth';
 import { Cards, PrivateCards } from './cards';
 import { DashboardStore } from './store';
-import { runApp } from './run-app';
 
-export interface DashboardOptions { port?: number; database?: string; origin?: string; sessionLifetimeMs?: number; }
+export interface DashboardOptions { port?: number; database?: string; origin?: string; sessionLifetimeMs?: number; signals?: boolean; shutdownTimeoutMs?: number; }
 
-export function databasePath() { return resolve(process.env.DASHBOARD_DATABASE ?? 'data/dashboard.sqlite'); }
+export function databasePath() {
+    return process.env.DASHBOARD_DATABASE === ':memory:' ? ':memory:' : resolve(process.env.DASHBOARD_DATABASE ?? 'data/dashboard.sqlite');
+}
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
+
+/** Development is loopback-only, so its equivalent browser hostnames share one trust boundary. */
+export function allowsDashboardOrigin(candidate: string | undefined, expected: string, configured: boolean, host?: string) {
+    if (!candidate) return false;
+    if (configured) return candidate === expected;
+    if (!host || /[\/@?#\\]/.test(host)) return false;
+    try {
+        const actual = new URL(candidate);
+        const local = new URL(expected);
+        const target = new URL(`http://${host}`);
+        return actual.origin === candidate && actual.protocol === 'http:'
+            && actual.origin === target.origin && actual.port === local.port
+            && LOOPBACK_HOSTS.has(actual.hostname);
+    } catch { return false; }
+}
 
 export function createApp(options: DashboardOptions = {}) {
     const port = options.port ?? Number(process.env.PORT ?? 8181);
@@ -19,11 +38,9 @@ export function createApp(options: DashboardOptions = {}) {
     }
     if (process.env.NODE_ENV === 'production' && !configuredOrigin?.startsWith('https://')) throw new Error('Production requires an explicit HTTPS DASHBOARD_ORIGIN.');
     const filename = options.database ?? databasePath();
-    mkdirSync(dirname(filename), { recursive: true });
-    const store = new DashboardStore(filename);
-    try {
-    const cards = new PrivateCards(store);
-    const auth = new DashboardAuth(store, options.sessionLifetimeMs);
+    let store: DashboardStore | undefined;
+    let cards: PrivateCards;
+    let auth: DashboardAuth | undefined;
     const app = express();
     app.disable('x-powered-by');
     app.use(express.urlencoded({ extended: false, limit: '4kb', parameterLimit: 4 }));
@@ -31,7 +48,9 @@ export function createApp(options: DashboardOptions = {}) {
         if (!response.destroyed) response.status(400).send('Invalid form submission.');
     };
     app.use(invalidBody);
-    const origin = () => configuredOrigin ?? `http://127.0.0.1:${(server.server.address() as { port: number }).port}`;
+    const origin = () => configuredOrigin ?? `http://127.0.0.1:${(server.server!.address() as { port: number }).port}`;
+    const allowsOrigin = (candidate: string | undefined, request: IncomingMessage) =>
+        allowsDashboardOrigin(candidate, origin(), Boolean(configuredOrigin), request.headers.host);
 
     @page('/login', { live: false, css: 'app.css', head: { title: 'Sign in · Your cards' } })
     class Login {
@@ -57,30 +76,31 @@ export function createApp(options: DashboardOptions = {}) {
         }
     }
 
-    auth.mount(app, origin, account => server.revoke(account));
-    const server = start([Login, Dashboard], {
+    class Workspace {
+        onInit() {
+            mkdirSync(dirname(filename), { recursive: true });
+            store = new DashboardStore(filename);
+            cards = new PrivateCards(store);
+            auth = new DashboardAuth(store, options.sessionLifetimeMs);
+            auth.mount(app, origin, allowsOrigin, account => server.revoke(account));
+        }
+        onShutdown() {
+            try { auth?.close(); }
+            finally { store?.close(); }
+        }
+    }
+    const server = defineApp({
+        pages: [Login, Dashboard], services: [Workspace], signals: options.signals, shutdownTimeoutMs: options.shutdownTimeoutMs,
         server: app, port, bind: configuredOrigin ? '0.0.0.0' : '127.0.0.1', logger: null, templateRoot: __dirname,
-        origins: value => value === origin(),
+        origins: allowsOrigin,
         authenticate: request => request.method === 'GET' && request.url?.split('?')[0] === '/login'
-            ? true : store.session(sessionToken(request.headers.cookie))?.account,
+            ? true : store!.session(sessionToken(request.headers.cookie))?.account,
     });
-    let closing: Promise<void> | undefined;
-    const shutdown = () => {
-        auth.close();
-        if (!closing) {
-            closing = server.shutdown().finally(() => store.close());
-        }
-        return closing;
-    };
-    server.server.once('error', () => { void shutdown().catch(() => {}); });
-    return {
-        server: server.server,
-        shutdown,
-    };
-    } catch (error) { store.close(); throw error; }
+    return server;
 }
 
 if (require.main === module) {
-    const app = runApp(createApp);
-    app?.server.once('listening', () => console.log(`Dashboard: ${process.env.DASHBOARD_ORIGIN ?? `http://127.0.0.1:${(app.server.address() as { port: number }).port}`}/login`));
+    const app = createApp();
+    void app.run().then(running => console.log(`Dashboard: ${process.env.DASHBOARD_ORIGIN ?? `http://127.0.0.1:${(running.server.address() as { port: number }).port}`}/login`))
+        .catch(error => { console.error(error); process.exitCode = 1; });
 }

package/recipes/dashboard/auth.ts

@@ -26,8 +26,10 @@ export class DashboardAuth {
     private closed = false;
     private readonly attempts = new Map<string, { count: number; expires: number }>();
 
-    constructor(private readonly store: DashboardStore, private readonly ttlMs = 3600000) {
+    constructor(private readonly store: DashboardStore, private readonly ttlMs = 3600000,
+        private readonly attemptWindowMs = 60000) {
         if (!Number.isInteger(ttlMs) || ttlMs < 100 || ttlMs > 86400000) throw new RangeError('Invalid session lifetime.');
+        if (!Number.isInteger(attemptWindowMs) || attemptWindowMs < 20 || attemptWindowMs > 60000) throw new RangeError('Invalid login attempt window.');
     }
 
     async login(ip: string, account: unknown, password: unknown): Promise<string | undefined> {
@@ -37,7 +39,7 @@ export class DashboardAuth {
         let attempt = this.attempts.get(ip);
         if (!attempt) {
             if (this.attempts.size >= 1024) return undefined;
-            attempt = { count: 0, expires: now + 60000 };
+            attempt = { count: 0, expires: now + this.attemptWindowMs };
             this.attempts.set(ip, attempt);
         }
         if (++attempt.count > 10 || this.active >= 4) return undefined;
@@ -55,12 +57,12 @@ export class DashboardAuth {
 
     close() { this.closed = true; this.attempts.clear(); }
 
-    mount(app: Application, origin: () => string, revoke: (account: string) => Promise<unknown>) {
+    mount(app: Application, origin: () => string, allowsOrigin: (candidate: string | undefined, request: Request) => boolean, revoke: (account: string) => Promise<unknown>) {
         const cookie = (token: string) => `${COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${token ? Math.ceil(this.ttlMs / 1000) : 0}${origin().startsWith('https:') ? '; Secure' : ''}`;
         const post = (route: string, handler: (request: Request, response: Response) => Promise<void>) => {
             app.post(route, (request, response) => {
                 response.set('Cache-Control', 'private, no-store');
-                if (request.get('origin') !== origin()) { response.status(403).send('This form must be submitted from this site.'); return; }
+                if (!allowsOrigin(request.get('origin'), request)) { response.status(403).send('This form must be submitted from this site.'); return; }
                 void handler(request, response).catch(() => response.status(503).send('Unable to complete the request. Try again later.'));
             });
         };

package/recipes/dashboard/rate-window.test.cjs

@@ -3,15 +3,15 @@ const { test } = require('node:test');
 const { DashboardStore } = require('../dist/store');
 const { DashboardAuth, credentials } = require('../dist/auth');
 
-test('login admission reopens after the real one-minute window, without clock mocks', { timeout: 65000 }, async t => {
+test('login admission reopens after its configured short real window', async t => {
     const store = new DashboardStore(':memory:');
-    const auth = new DashboardAuth(store);
+    const auth = new DashboardAuth(store, 3600000, 250);
     t.after(() => { auth.close(); store.close(); });
     const password = 'test-only-login-window-password';
     store.provision('alice', await credentials(password));
-    for (let attempt = 0; attempt < 10; attempt++) assert.equal(await auth.login('same-peer', 'invalid', password), undefined);
+    for (let attempt = 0; attempt < 10; attempt++) assert.equal(await auth.login('same-peer', 'invalid', 'short'), undefined);
     assert.equal(await auth.login('same-peer', 'alice', password), undefined);
-    await new Promise(resolve => setTimeout(resolve, 60010));
+    await new Promise(resolve => setTimeout(resolve, 275));
     const token = await auth.login('same-peer', 'alice', password);
     assert.equal(store.session(token).account, 'alice');
 });

package/recipes/http-ws/README.md

@@ -4,7 +4,7 @@ One Node server answers ordinary HTTP requests and upgrades `/chat` connections
 
 After starting the application, request `http://127.0.0.1:8181/health` to receive `{"ok":true}`. Connect a WebSocket to `ws://127.0.0.1:8181/chat` and send `{"type":"hello"}` to receive `{"type":"hello","message":"Hello from the server!"}`. This is a raw JSON socket example, not a chatroom UI or the versioned socket-contract protocol. Use the chat or socket starter for those applications.
 
-The HTTP builder does not bind a port. The socket service explicitly takes responsibility for listening and closing the supplied server with `listen: true` and `closeServerOnShutdown: true`. Call the returned application's `shutdown()`; it processes route failures and still closes its HTTP/TCP peers. Do not separately close the HTTP builder. Importing this module creates no listener; the standalone entrypoint uses the same bounded `runApp` helper as the other starters.
+`defineApp` registers the socket route and the HTTP endpoint on one owned listener. `app.run()` opens it; `app.shutdown()` closes it even when route cleanup fails. You do not need separate server variables, listener flags, or a startup helper. Importing the definition creates no listener.
 
 `/health` reports liveness, not readiness or completed application work. Loopback binding is intentional. Before exposing the service, choose your deployment bind address, configure HTTPS/WSS, trusted origins, authentication, authorization, payload/connection limits, and any persistence you need. Shared listeners do not automatically provide these policies. Shutdown may force connections closed; it does not guarantee message delivery or durable work.
 

package/recipes/http-ws/app.test.cjs

@@ -4,8 +4,8 @@ const net = require('node:net');
 const { once } = require('node:events');
 const WebSocket = require('ws');
 const { SocketRoute } = require('redweb');
-const { createApp, Hello } = require('../dist/app.js');
-const { listen, connect } = require('./network.cjs');
+const { Hello } = require('../dist/app.js');
+const { createApp, listen, connect } = require('./network.cjs');
 
 test('an absent PORT binds the documented default or reports that exact port occupied', { timeout: 10000 }, async () => {
     const { spawnSync } = require('node:child_process');
@@ -15,12 +15,11 @@ test('an absent PORT binds the documented default or reports that exact port occ
         const assert = require('node:assert/strict');
         const { once } = require('node:events');
         const WebSocket = require('ws');
-        const { createApp } = require('./dist/app.js');
+        const { app } = require('./dist/app.js');
         (async () => {
-            const app = createApp();
             let socket;
             try {
-                try { if (!app.server.listening) await once(app.server, 'listening'); }
+                try { await app.run(); }
                 catch (error) {
                     assert.equal(error.code, 'EADDRINUSE');
                     assert.equal(error.port, 8181);
@@ -60,17 +59,16 @@ test('HTTP and separate message handlers share one port, with strict socket path
 
 for (const failingRoute of [false, true]) {
     test(`shutdown closes incomplete HTTP peers${failingRoute ? ' despite a route failure' : ' idempotently'}`, { timeout: 10000 }, async t => {
-        const app = createApp({ port: 0, logger: null });
+        const app = createApp({ port: 0, logger: null, shutdownTimeoutMs: 30 });
         t.after(() => app.shutdown().catch(() => {}));
-        if (!app.server.listening) await once(app.server, 'listening');
-        assert.equal(app.closeServerOnShutdown, true);
+        await app.run();
         const failure = new Error('Application cleanup failed');
         if (failingRoute) {
             class FailingRoute extends SocketRoute {
                 constructor() { super({ path: '/fails', handlers: [Hello] }); }
                 async shutdown() { await super.shutdown(); throw failure; }
             }
-            app.addRoute(FailingRoute);
+            app.sockets.addRoute(FailingRoute);
         }
         const accepted = once(app.server, 'connection');
         const peer = net.connect(app.server.address().port, '127.0.0.1');
@@ -82,7 +80,7 @@ for (const failingRoute of [false, true]) {
         const closed = once(serverPeer, 'close');
         const shutdown = app.shutdown();
         assert.equal(app.shutdown(), shutdown);
-        if (failingRoute) await assert.rejects(shutdown, error => error.errors.length === 1 && error.errors[0] === failure);
+        if (failingRoute) await assert.rejects(shutdown, error => error.errors.length === 1 && error.errors[0].errors[0] === failure);
         else await shutdown;
         await closed;
         assert.equal(serverPeer.destroyed, true);

package/recipes/http-ws/app.tsx

@@ -1,5 +1,4 @@
-import { BaseHandler, HttpServer, METHODS, SocketRoute, SocketServer, type RedWebSocket, type SocketServerOptions } from 'redweb';
-import { runApp } from './run-app';
+import { BaseHandler, defineApp, METHODS, SocketRoute, type RedWebSocket } from 'redweb';
 
 export class Hello extends BaseHandler {
     constructor() { super('hello'); }
@@ -15,22 +14,12 @@ export class ChatRoute extends SocketRoute {
     }
 }
 
-export function createApp(options: Pick<SocketServerOptions, 'port' | 'bind' | 'logger'> = {}) {
-    const http = new HttpServer({
-        listen: false,
-        publicPaths: [],
-        services: [{ serviceName: '/health', method: METHODS.GET, function: (_req, res) => res.json({ ok: true }) }],
-    });
+export const app = defineApp({
+    sockets: [ChatRoute],
+    port: Number(process.env.PORT ?? 8181),
+    bind: '127.0.0.1',
+    publicPaths: [],
+    httpServices: [{ serviceName: '/health', method: METHODS.GET, function: (_req, res) => res.json({ ok: true }) }],
+});
 
-    return new SocketServer({
-        port: options.port ?? Number(process.env.PORT ?? 8181),
-        bind: options.bind ?? '127.0.0.1',
-        logger: options.logger,
-        server: http.server,
-        routes: [ChatRoute],
-        listen: true,
-        closeServerOnShutdown: true, // One owner closes routes and the shared HTTP listener.
-    });
-}
-
-if (require.main === module) runApp(createApp);
+if (require.main === module) void app.run().catch(error => { console.error(error); process.exitCode = 1; });

package/recipes/realtime/app.tsx

@@ -1,5 +1,4 @@
-import { action, page, start, state, type LiveHtmlStartOptions } from 'redweb';
-import { runApp } from './run-app';
+import { action, defineApp, page, state } from 'redweb';
 
 @page('/', { css: 'app.css', shared: true })
 export class CounterPage {
@@ -21,8 +20,6 @@ export class CounterPage {
     }
 }
 
-export function createApp(options: LiveHtmlStartOptions = {}) {
-    return start(CounterPage, { port: Number(process.env.PORT ?? 8181), templateRoot: __dirname, ...options });
-}
+export const app = defineApp({ pages: [CounterPage], port: Number(process.env.PORT ?? 8181), templateRoot: __dirname });
 
-if (require.main === module) runApp(createApp);
+if (require.main === module) void app.run().catch(error => { console.error(error); process.exitCode = 1; });

package/recipes/shared/README.md

@@ -29,7 +29,9 @@ custom hostnames, tunnels and proxy-forwarded origins are not supported by this
 Run `npm start` to serve the compiled app. For deployment, build first, ship `dist/`, `package.json`, and the lockfile,
 then install runtime dependencies with `npm ci --omit=dev`. The application does not require TypeScript or `src/` at runtime.
 
-The standalone entrypoint calls the shared `runApp(createApp)` helper. Importing either module starts no listener and installs no process handlers. On SIGINT/SIGTERM, a listener error, or native listener closure, the helper calls application shutdown once. Repeated signals do not bypass cleanup. The five-second outer deadline covers the whole application, including database/worker cleanup after HTTP closes; customize it with the helper's second argument if necessary. Cleanup must resolve only after resources are released. A failed cleanup sets a failure exit status and retains a deadline for any surviving handles; the helper never resets an existing failure status. If cleanup does not finish in time, the entrypoint terminates the process with a failure status. This cannot preempt synchronous code blocking Node's event loop and does not make in-memory state durable. Factory functions remain responsible for releasing partially constructed resources before throwing.
+The standalone entrypoint calls `app.run()` on a `defineApp` definition. Importing it opens no listener and installs no process handlers. Redweb owns HTTP and WebSocket startup together, including signal handling and bounded shutdown; no generated `run-app.ts` helper is needed. Configure `startupTimeoutMs` and `shutdownTimeoutMs` on the definition (both default to five seconds). App-wide service classes acquire resources in `onInit(app, signal)` and release them in `onShutdown()`; the dashboard uses this for its auth/database resources. The dashboard's factory configures an independent private workspace but does not start it.
+
+Repeated signals do not bypass cleanup. Failed process-owned cleanup sets a failure exit status and retains a deadline for surviving handles. Explicit `shutdown()` rejects on cleanup failures without terminating its caller. Deadlines cannot preempt synchronous code blocking Node's event loop or arbitrary operations that ignore cancellation. Tests can define an independent application from `{ ...app.options, port: 0, signals: false }` and await `run()`; app-owned state is isolated, but objects deliberately captured by page class closures remain shared unless a new class/room is created.
 
 The shipped lifecycle tests exercise actual processes, HTTP/TCP/WebSocket peers and timers. Linux uses actual OS signals; Windows tests explicitly emit signal events inside the process because killing a Windows child does not exercise graceful POSIX signal delivery. This is not a claim that Windows console/service managers forward the same signals. Deploy with a supervisor that forwards the supported termination signal and allows longer than the configured cleanup deadline.
 

package/recipes/shared/lifecycle.test.cjs

@@ -0,0 +1,81 @@
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { spawn } = require('node:child_process');
+const { once } = require('node:events');
+
+function execute(t, args, env = process.env) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, args, { env, windowsHide: true });
+        let stdout = '', stderr = '', finished = false;
+        const closed = new Promise(resolve => child.once('close', () => { finished = true; resolve(); }));
+        const deadline = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('Entrypoint did not exit')); }, 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); resolve({ code, signal, stdout, stderr }); });
+    });
+}
+
+// Each generated app is tested in a real process. Framework deadline/failure
+// coverage lives with Application itself, not in six copied startup helpers.
+for (const mode of ['SIGINT', 'SIGTERM', 'native-close']) {
+    test(`import is inert; application owns ${mode} cleanup`, { timeout: 7000 }, async t => {
+        const result = await execute(t, ['-e', String.raw`
+            const assert = require('node:assert/strict');
+            const { once } = require('node:events');
+            const { defineApp } = require('redweb');
+            const initial = ['SIGINT', 'SIGTERM'].map(signal => process.listenerCount(signal));
+            const source = require('./dist/app');
+            assert.deepEqual(['SIGINT', 'SIGTERM'].map(signal => process.listenerCount(signal)), initial);
+            const app = source.app
+                ? defineApp({ ...source.app.options, port: 0, bind: '127.0.0.1', logger: null })
+                : source.createApp({ port: 0, database: ':memory:' });
+            assert.equal(app.server, null);
+            (async () => {
+                const running = await app.run();
+                const response = await fetch('http://127.0.0.1:' + running.server.address().port, { headers: { Connection: 'close' } });
+                assert.ok(response.status < 500);
+                await response.arrayBuffer();
+                const closed = once(running.server, 'close');
+                if (process.argv[1] === 'native-close') {
+                    running.server.close();
+                } else {
+                    // Windows kill does not deliver a graceful POSIX signal.
+                    if (process.platform === 'win32') process.emit(process.argv[1]);
+                    else process.kill(process.pid, process.argv[1]);
+                }
+                await closed;
+                await app.shutdown();
+                assert.equal(running.server.listening, false);
+                assert.deepEqual(['SIGINT', 'SIGTERM'].map(signal => process.listenerCount(signal)), initial);
+            })().catch(error => { console.error(error); process.exitCode = 1; });
+        `, mode]);
+        assert.equal(result.code, 0, result.stdout + result.stderr);
+        assert.equal(result.signal, null);
+    });
+}
+
+test('the actual application entrypoint reports an occupied port', { timeout: 7000 }, async t => {
+    const net = require('node:net');
+    const occupied = net.createServer(socket => socket.destroy());
+    const loopback = net.createServer(socket => socket.destroy());
+    t.after(async () => {
+        for (const server of [occupied, loopback]) await new Promise(resolve => server.close(resolve));
+    });
+    occupied.listen(0, '0.0.0.0');
+    await once(occupied, 'listening');
+    // Windows may allow separate wildcard and loopback binds to the same port.
+    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: ':memory:' };
+    delete env.DASHBOARD_ORIGIN;
+    const result = await execute(t, ['dist/app.js'], env);
+    assert.equal(result.code, 1, result.stdout + result.stderr);
+    assert.equal(result.signal, null);
+    assert.match(result.stderr, /EADDRINUSE/);
+});

package/recipes/shared/network.cjs

@@ -1,12 +1,17 @@
 const assert = require('node:assert/strict');
 const { once } = require('node:events');
 const WebSocket = require('ws');
-const { createApp } = require('../dist/app.js');
+const { defineApp } = require('redweb');
+const { app: definition } = require('../dist/app.js');
 
-async function listen(t) {
-    const app = createApp({ port: 0, bind: '127.0.0.1', logger: null });
+function createApp(options = {}) {
+    return defineApp({ ...definition.options, port: 0, bind: '127.0.0.1', logger: null, signals: false, ...options });
+}
+
+async function listen(t, options) {
+    const app = createApp(options);
     t.after(() => app.shutdown());
-    if (!app.server.listening) await once(app.server, 'listening');
+    await app.run();
     return `http://127.0.0.1:${app.server.address().port}`;
 }
 
@@ -56,4 +61,4 @@ async function live(t, origin, headers = {}) {
     };
 }
 
-module.exports = { listen, connect, live };
+module.exports = { createApp, listen, connect, live };

package/recipes/site/app.tsx

@@ -1,5 +1,4 @@
-import { defineSite, start, type LiveHtmlStartOptions } from 'redweb';
-import { runApp } from './run-app';
+import { defineApp, defineSite } from 'redweb';
 
 const site = defineSite({
     css: 'app.css',
@@ -18,8 +17,6 @@ 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 });
-}
+export const app = defineApp({ pages: [HomePage, AboutPage], port: Number(process.env.PORT ?? 8181), templateRoot: __dirname });
 
-if (require.main === module) runApp(createApp);
+if (require.main === module) void app.run().catch(error => { console.error(error); process.exitCode = 1; });

package/recipes/socket/app.tsx

@@ -1,7 +1,6 @@
-import { SocketRoute, SocketServer, type SocketServerOptions } from 'redweb';
+import { defineApp, SocketRoute } from 'redweb';
 import { match } from './contract';
 import { Join, Move, Resume } from './handlers';
-import { runApp } from './run-app';
 
 export class MatchRoute extends SocketRoute {
     constructor() {
@@ -19,12 +18,6 @@ export class MatchRoute extends SocketRoute {
     }
 }
 
-export function createApp(options: SocketServerOptions = {}) {
-    return new SocketServer({
-        port: Number(process.env.PORT ?? 8181),
-        routes: [MatchRoute],
-        ...options,
-    });
-}
+export const app = defineApp({ sockets: [MatchRoute], port: Number(process.env.PORT ?? 8181) });
 
-if (require.main === module) runApp(createApp);
+if (require.main === module) void app.run().catch(error => { console.error(error); process.exitCode = 1; });