redweb 0.13.5 → 0.14.0

package/src/Application.js

@@ -0,0 +1,239 @@
+'use strict';
+
+const LiveHtmlServer = require('./htmx/LiveHtmlServer');
+const HttpServer = require('./http/HttpServer');
+const HttpsServer = require('./http/HttpsServer');
+const SocketServer = require('./ws/SocketServer');
+const SocketService = require('./ws/SocketService');
+const OwnedServerLifecycle = require('./OwnedServerLifecycle');
+const { validateListenerOptions } = require('./serverLifecycle');
+const { awaitStartupCleanup } = require('./StartupCleanup');
+const { performance } = require('node:perf_hooks');
+
+function classes(value, name) {
+    if (!Array.isArray(value) || value.some(Type => typeof Type !== 'function')) {
+        throw new TypeError(`\`${name}\` must be an array of classes.`);
+    }
+    return [...value];
+}
+
+function bounded(operation, milliseconds, label, signal) {
+    let timer, abort;
+    return Promise.race([
+        Promise.resolve().then(() => {
+            if (signal?.aborted) throw new Error('Application startup was cancelled.');
+            return operation();
+        }),
+        new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`${label} exceeded its deadline.`)), milliseconds); }),
+        new Promise((_, reject) => {
+            abort = () => reject(new Error('Application startup was cancelled.'));
+            signal?.addEventListener('abort', abort, { once: true });
+            if (signal?.aborted) abort();
+        }),
+    ]).finally(() => { clearTimeout(timer); signal?.removeEventListener('abort', abort); });
+}
+
+/** One deferred application definition, one listener and one cleanup owner. */
+class Application {
+    constructor(options = {}) {
+        if (!options || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('Application options must be an object.');
+        const { pages = [], sockets = [], services = [], port = 8181, bind = '0.0.0.0',
+            startupTimeoutMs = 5000, shutdownTimeoutMs = 5000, signals = true, ...rest } = options;
+        if ('static' in rest) throw new TypeError('Use exportStatic() for static output; defineApp() owns a live HTTP listener.');
+        for (const name of ['listen', 'routes', 'socketRoutes', 'closeServerOnShutdown']) {
+            if (name in rest) throw new TypeError(`defineApp owns \`${name}\`; use pages/sockets and run().`);
+        }
+        validateListenerOptions({ port, bind, listen: false, listenCallback: rest.listenCallback });
+        for (const value of [startupTimeoutMs, shutdownTimeoutMs]) {
+            if (!Number.isInteger(value) || value < 1 || value > 2147483647) throw new RangeError('Application deadlines must be positive timer-safe integers.');
+        }
+        if (typeof signals !== 'boolean') throw new TypeError('`signals` must be a boolean.');
+        this.options = { ...rest, pages: classes(pages, 'pages'), sockets: classes(sockets, 'sockets'),
+            services: classes(services, 'services'), port, bind, startupTimeoutMs, shutdownTimeoutMs, signals };
+        if (this.options.services.some(Type => Type === SocketService || Type.prototype instanceof SocketService)) {
+            throw new TypeError('SocketService belongs to a socket route, not application services.');
+        }
+        this.services = [];
+        this.server = null;
+        this.app = null;
+        this.http = null;
+        this.sockets = null;
+        this._live = null;
+        this._owner = null;
+        this._runPromise = null;
+        this._shutdownPromise = null;
+        this._cleanupPromise = null;
+        this._stopping = false;
+        this._abort = new AbortController();
+        this._onSignal = () => this._stopProcess();
+        this._onClose = () => {
+            if (this._stopping) return;
+            if (this.options.signals) this._stopProcess();
+            else void this.shutdown().catch(() => {});
+        };
+        this._onError = () => {
+            if (this.options.signals) process.exitCode = 1;
+            this._onClose();
+        };
+    }
+
+    run() {
+        if (this._stopping) return Promise.reject(new Error('An application cannot run after shutdown. Define a new application.'));
+        if (this._runPromise) return this._runPromise;
+        this._startupDeadline = performance.now() + this.options.startupTimeoutMs;
+        this._runPromise = this._start().catch(async error => {
+            this._stopping = true;
+            this._abort.abort();
+            try {
+                const results = await Promise.allSettled([
+                    this._withinShutdown(() => awaitStartupCleanup(error), 'Construction rollback'), this._cleanup(),
+                ]);
+                const errors = results.filter(result => result.status === 'rejected').map(result => result.reason);
+                if (errors.length) throw new AggregateError(errors, 'Application rollback failed.');
+            }
+            catch (cleanup) { throw new AggregateError([error, cleanup], 'Application startup and cleanup failed.', { cause: error }); }
+            throw error;
+        });
+        return this._runPromise;
+    }
+
+    async _start() {
+        const { pages, sockets, services, startupTimeoutMs, shutdownTimeoutMs, signals, httpServices = [], ...options } = this.options;
+        if (signals) {
+            process.on('SIGINT', this._onSignal);
+            process.on('SIGTERM', this._onSignal);
+        }
+        const httpOptions = { ...options, services: httpServices, listen: false, shutdownTimeoutMs };
+        if (pages.length) {
+            this._live = new LiveHtmlServer({ ...httpOptions, pages, socketRoutes: sockets });
+            this.http = this._live.http;
+            this.sockets = this._live.sockets;
+            this._owner = this._live._ownedServer;
+        } else {
+            const Server = options.ssl ? HttpsServer : HttpServer;
+            this.http = new Server(httpOptions);
+            this._owner = new OwnedServerLifecycle(this.http.server);
+        }
+        this.server = this.http.server;
+        this.app = this.http.app;
+        if (!pages.length && sockets.length) {
+            this.sockets = new SocketServer({ server: this.server, routes: sockets, listen: false,
+                closeServerOnShutdown: false, logger: options.logger });
+        }
+        for (const Service of services) {
+            this._checkStarting();
+            const service = new Service();
+            this.services.push(service);
+            if (typeof service.onInit !== 'function' || typeof service.onShutdown !== 'function') {
+                throw new TypeError('Application services require onInit(app, signal) and onShutdown().');
+            }
+            await this._withinStartup(() => service.onInit(this, this._abort.signal), 'Application service initialization');
+        }
+        this._checkStarting();
+        await this._listen();
+        this._checkStarting();
+        this.server.on('error', this._onError);
+        this.server.once('close', this._onClose);
+        if (options.listenCallback) await this._withinStartup(() => options.listenCallback(), 'Application listening callback');
+        else this.http.logger?.log?.(`Redweb application listening on ${options.bind}:${this.server.address().port}`);
+        this._checkStarting();
+        return this;
+    }
+
+    _checkStarting() {
+        if (this._stopping) throw new Error('Application startup was cancelled.');
+    }
+
+    _listen() {
+        const { server } = this;
+        return this._withinStartup(() => new Promise((resolve, reject) => {
+            // A cancelled or timed-out native lookup can still complete on
+            // Node 18. Only native settlement detaches these one-shot guards.
+            const detach = () => { server.off('listening', ready); server.off('error', failed); };
+            const failed = error => { detach(); reject(error); };
+            const ready = () => {
+                try {
+                    if (this._abort.signal.aborted) server.close();
+                    detach();
+                    resolve();
+                } catch (error) { failed(error); }
+            };
+            server.once('listening', ready);
+            server.once('error', failed);
+            try { server.listen({ port: this.options.port, host: this.options.bind, signal: this._abort.signal }); }
+            catch (error) { failed(error); }
+        }), 'Application listener startup');
+    }
+
+    shutdown() {
+        if (!this._shutdownPromise) {
+            this._stopping = true;
+            this._deadline ??= performance.now() + this.options.shutdownTimeoutMs;
+            this._abort.abort();
+            this._shutdownPromise = Promise.resolve(this._runPromise).catch(() => {}).then(() => this._cleanup());
+        }
+        return this._shutdownPromise;
+    }
+
+    revoke(principal) { return this._live ? this._live.revoke(principal) : Promise.resolve(0); }
+
+    inspect() { return this._live ? this._live.inspect() : null; }
+
+    _stopProcess() {
+        if (this._processStopping) return;
+        this._processStopping = true;
+        const timer = setTimeout(() => { process.exitCode = 1; process.exit(); }, this.options.shutdownTimeoutMs);
+        void this.shutdown().then(() => clearTimeout(timer), () => { process.exitCode = 1; timer.unref(); });
+    }
+
+    _withinShutdown(operation, label) {
+        this._deadline ??= performance.now() + this.options.shutdownTimeoutMs;
+        return bounded(operation, Math.max(0, this._deadline - performance.now()), label);
+    }
+
+    _withinStartup(operation, label) {
+        const remaining = this._startupDeadline - performance.now();
+        if (remaining <= 0) return Promise.reject(new Error(`${label} exceeded its deadline.`));
+        return bounded(operation, remaining, label, this._abort.signal);
+    }
+
+    _cleanup() {
+        if (!this._cleanupPromise) this._cleanupPromise = this._dispose();
+        return this._cleanupPromise;
+    }
+
+    async _dispose() {
+        const errors = [];
+        const close = async (operation, label) => {
+            try { await this._withinShutdown(operation, label); } catch (error) { errors.push(error); }
+        };
+        // Drain handlers and close listeners before releasing their dependencies.
+        if (this.server?.listening) {
+            try { this.server.close(); } catch (error) { errors.push(error); }
+        }
+        if (this.sockets) await close(() => this.sockets.shutdown(), 'Socket shutdown');
+        if (this._live) await close(() => this._live.manager.shutdown(), 'Page shutdown');
+        if (this._owner) {
+            // OwnedServerLifecycle applies this same remaining deadline and
+            // force-closes peers when it expires. A second racing timer could
+            // report failure just before that successful force-close.
+            try { await this._owner.close(Math.max(0, this._deadline - performance.now()), () => this.http.shutdown()); }
+            catch (error) { errors.push(error); }
+            errors.push(...this._owner.forceClose());
+        }
+        for (const service of [...this.services].reverse()) {
+            await close(() => service.onShutdown(), 'Application service shutdown');
+        }
+        this.server?.off('error', this._onError);
+        this.server?.off('close', this._onClose);
+        if (!errors.length || !this._processStopping) {
+            process.off('SIGINT', this._onSignal);
+            process.off('SIGTERM', this._onSignal);
+        }
+        if (errors.length) throw new AggregateError(errors, 'Application shutdown failed.');
+    }
+}
+
+function defineApp(options) { return new Application(options); }
+
+module.exports = { Application, defineApp };

package/src/StartupCleanup.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const pending = new WeakMap();
+const { isNativeError } = require('node:util').types;
+
+/** Preserve synchronous constructor errors while letting async owners await rollback. */
+function scheduleStartupCleanup(error, cleanup) {
+    const failure = error instanceof Error || isNativeError(error) ? error : new Error('Application construction failed.', { cause: error });
+    const previous = pending.get(failure);
+    // Each partially constructed owner must start releasing its resources even
+    // when another owner's cleanup stalls. Retain every failure for the caller.
+    const rollback = Promise.allSettled([previous, Promise.resolve().then(cleanup)]).then(results => {
+        const errors = results.filter(result => result.status === 'rejected').map(result => result.reason);
+        if (errors.length) throw new AggregateError(errors, 'Construction rollback failed.');
+    });
+    pending.set(failure, rollback);
+    // Synchronous callers cannot await a constructor; async owners inspect the original task.
+    rollback.catch(() => {});
+    return failure;
+}
+
+function awaitStartupCleanup(error) { return pending.get(error); }
+
+module.exports = { scheduleStartupCleanup, awaitStartupCleanup };

package/src/cli/SourceInspector.js

@@ -108,6 +108,11 @@ class SourceInspector {
             this.group(args[0], 'page', node, args[1]);
         } else if (api === 'LiveHtmlServer') {
             this.group(read.property(args[0], 'pages'), 'page', node, args[0]);
+        } else if (['defineApp', 'Application'].includes(api)) {
+            for (const [field, kind] of [['pages', 'page'], ['sockets', 'route']]) {
+                const registrations = read.property(args[0], field);
+                if (registrations !== undefined) this.group(registrations, kind, node, args[0]);
+            }
         } else if (['SocketServer', 'SecureSocketServer'].includes(api)) {
             const routes = read.property(args[0], 'routes');
             if (routes !== undefined) this.group(routes, 'route', node);

package/src/cli/templates.js

@@ -16,8 +16,8 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
             build: 'tsc && node scripts/copy-assets.cjs',
             start: 'node dist/app.js',
             dev: 'nodemon',
-            test: 'npm run build && node --test test/app.test.cjs test/run-app.test.cjs',
-            'test:coverage': 'npm run build && c8 --all --src=dist --include=dist/** --reporter=text --reporter=json node --test test/app.test.cjs test/run-app.test.cjs',
+            test: 'npm run build && node --test test/app.test.cjs test/lifecycle.test.cjs',
+            'test:coverage': 'npm run build && c8 --all --src=dist --include=dist/** --reporter=text --reporter=json node --test test/app.test.cjs test/lifecycle.test.cjs',
         },
         dependencies: {
             redweb: `^${version}`,
@@ -52,12 +52,11 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
             include: ['src/**/*.ts', 'src/**/*.tsx'],
         }) },
         { path: 'src/app.tsx', content: read(`${template}/app.tsx`) },
-        { path: 'src/run-app.ts', content: read('shared/run-app.ts') },
         { path: 'src/app.css', content: read(`${template === 'dashboard' ? template : 'shared'}/app.css`) },
         { path: 'scripts/copy-assets.cjs', content: read('shared/copy-assets.cjs') },
         { path: 'test/network.cjs', content: read('shared/network.cjs') },
         { path: 'test/app.test.cjs', content: read(`${template}/app.test.cjs`) },
-        { path: 'test/run-app.test.cjs', content: read('shared/run-app.test.cjs') },
+        { path: 'test/lifecycle.test.cjs', content: read('shared/lifecycle.test.cjs') },
         { path: 'README.md', content: `${read('shared/README.md')}\n${read(`${template}/README.md`)}` },
         { path: '.gitignore', content: 'node_modules/\ndist/\ncoverage/\n.env\ndata/\n*.sqlite\n*.sqlite-wal\n*.sqlite-shm\n' },
     ];

package/src/htmx/LiveHtmlServer.js

@@ -7,14 +7,21 @@ const { createInspection } = require('../development/Inspection');
 const developmentSettings = require('../development/settings');
 const OwnedServerLifecycle = require('../OwnedServerLifecycle');
 const { listenServer, validateListenerOptions } = require('../serverLifecycle');
+const { scheduleStartupCleanup } = require('../StartupCleanup');
 
 class LiveHtmlServer {
     constructor(options = {}) {
+        try { this.initialize(options); }
+        catch (error) { throw scheduleStartupCleanup(error, () => this.shutdown()); }
+    }
+
+    initialize(options) {
         if (!options || typeof options !== 'object' || Array.isArray(options)) {
             throw new TypeError('Live HTML server options must be an object.');
         }
         const {
             pages,
+            socketRoutes = [],
             templateRoot,
             livePaths,
             sessionTtlMs,
@@ -29,6 +36,9 @@ class LiveHtmlServer {
             server: suppliedApp,
             ...httpOptions
         } = options;
+        if (!Array.isArray(socketRoutes) || socketRoutes.some(Route => typeof Route !== 'function')) {
+            throw new TypeError('`socketRoutes` must be an array of route classes.');
+        }
         const settings = developmentSettings(development, ['inspect', 'refresh'], { refresh: process.env.REDWEB_DEV_REFRESH === '1' });
         this._inspection = createInspection({ inspect: settings.inspect });
         const app = suppliedApp === undefined ? express() : suppliedApp;
@@ -58,11 +68,10 @@ class LiveHtmlServer {
         validateListenerOptions({ ...this.http, listen });
         this._ownedServer = new OwnedServerLifecycle(this.http.server);
         try {
-            if (this.manager.hasLivePages) {
-                const Route = this.manager.route();
+            if (this.manager.hasLivePages || socketRoutes.length) {
                 this.sockets = new SocketServer({
                     server: this.http.server,
-                    routes: [Route],
+                    routes: [...(this.manager.hasLivePages ? [this.manager.route()] : []), ...socketRoutes],
                     listen,
                     port: this.http.port,
                     bind: this.http.bind,
@@ -100,11 +109,11 @@ class LiveHtmlServer {
             try { await this.sockets.shutdown(); }
             catch (error) { errors.push(error); }
         }
-        try { await this.manager.shutdown(); }
+        try { await this.manager?.shutdown(); }
         catch (error) {
             errors.push(error);
         }
-        try { await this._ownedServer.close(this.manager.shutdownTimeoutMs, () => this.http.shutdown()); }
+        try { await this._ownedServer?.close(this.manager.shutdownTimeoutMs, () => this.http.shutdown()); }
         catch (error) { errors.push(error); }
         if (errors.length) throw new AggregateError(errors, 'Live HTML shutdown failed.');
     }

package/src/htmx/PageManager.js

@@ -16,6 +16,7 @@ const { AccessDenied } = require('../access/AccessPolicy');
 const { PageIdentity, AuthenticationFailure, isPrincipal } = require('./PageIdentity');
 const PageLifetime = require('./PageLifetime');
 const requestSnapshot = require('../context/RequestSnapshot');
+const { scheduleStartupCleanup } = require('../StartupCleanup');
 
 const PROTOCOL_VERSION = '1';
 const DEFAULT_HEARTBEAT = Object.freeze({ intervalMs: 15_000, timeoutMs: 10_000 });
@@ -122,7 +123,8 @@ class PageManager {
         this.renderAbortController = new AbortController();
         setMaxListeners(maxSessions + maxConcurrentRenders + 1, this.renderAbortController.signal);
         this.closing = false;
-        pages.forEach(PageClass => this.register(PageClass));
+        try { pages.forEach(PageClass => this.register(PageClass)); }
+        catch (error) { throw scheduleStartupCleanup(error, () => this.shutdown()); }
         this.hasLivePages = [...this.records.values()].some(record => record.metadata.live !== false);
     }
 

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/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);
 

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);
-        }
-    });
-}