@undefineds.co/xpod 0.4.19 → 0.4.25

package/dist/runtime/Proxy.js

@@ -12,6 +12,8 @@ const global_logger_factory_1 = require("global-logger-factory");
 const NodeRuntimeHost_1 = require("./host/node/NodeRuntimeHost");
 const GatewayAdminProxyAuth_1 = require("./GatewayAdminProxyAuth");
 const BunNativeUpgradeRelay_1 = require("./upgrade/BunNativeUpgradeRelay");
+const xpod_route_policy_1 = require("../shared/xpod-route-policy");
+const PodDeletionRoute_1 = require("../provision/PodDeletionRoute");
 // CORS configuration matching CSS CorsHandler defaults
 const CORS_CONFIG = {
     methods: ['GET', 'HEAD', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE'],
@@ -46,6 +48,7 @@ class GatewayProxy {
     constructor(port, supervisor, bindHost = '0.0.0.0', options = {}) {
         this.supervisor = supervisor;
         this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        this.proxyResponses = new WeakMap();
         this.targets = {};
         /** Sockets created by `upgrade` events, dropped on shutdown. */
         this.upgradeSockets = new Set();
@@ -64,14 +67,11 @@ class GatewayProxy {
         this.proxy = http_proxy_1.default.createProxyServer({
             xfwd: true,
         });
-        this.proxy.on('error', (err, _req, res) => {
-            this.logger.error('Proxy error:', err);
-            if (res && 'writeHead' in res && !res.headersSent) {
-                res.writeHead(502, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: 'Service Unavailable', details: err.message }));
-            }
-        });
+        this.proxy.on('error', (err, req, res) => this.handleProxyError(err, req, res));
         this.proxy.on('proxyRes', (proxyRes, req, res) => {
+            this.proxyResponses.set(req, proxyRes);
+            proxyRes.once('close', () => this.proxyResponses.delete(req));
+            proxyRes.once('error', (err) => this.handleProxyError(err, req, res));
             this.normalizeProxiedCorsHeaders(req, proxyRes);
             this.sanitizeProxyResponseHeaders(req, proxyRes);
             const interceptedRequest = req;
@@ -101,6 +101,29 @@ class GatewayProxy {
             });
         }
     }
+    handleProxyError(err, req, res) {
+        this.logger.error('Proxy error:', err);
+        if (!res || !('writeHead' in res))
+            return;
+        // http-proxy copies headers before piping data. A parser error can arrive
+        // between those steps, so terminate that stream before writing a new body.
+        const upstream = this.proxyResponses.get(req);
+        this.proxyResponses.delete(req);
+        upstream?.unpipe(res);
+        upstream?.destroy();
+        if (res.writableEnded || res.destroyed)
+            return;
+        if (res.headersSent) {
+            res.destroy();
+            return;
+        }
+        const body = Buffer.from(JSON.stringify({ error: 'Service Unavailable', details: err.message }));
+        res.removeHeader('Content-Length');
+        res.removeHeader('Transfer-Encoding');
+        res.removeHeader('Content-Encoding');
+        res.writeHead(502, { 'Content-Type': 'application/json', 'Content-Length': String(body.byteLength) });
+        res.end(body);
+    }
     /**
      * Builds one HTTP listener plus its WebSocket routing.
      *
@@ -236,15 +259,16 @@ class GatewayProxy {
         const localCanonicalProto = originalClientLoopback
             ? this.firstHeaderValue(req.headers['x-xpod-canonical-origin'])?.split(':', 1)[0] ?? originalProto
             : undefined;
-        const apiHost = this.isApiHost(originalHost);
-        const apiPath = this.shouldRouteToApi(pathname);
+        const podDeletion = (0, PodDeletionRoute_1.podDeletionRouteName)(req.method, url) !== undefined;
+        const apiHost = !podDeletion && this.isApiHost(originalHost);
+        const apiPath = this.shouldRouteToApi(pathname, req.method);
         const clientCanonicalUrl = originalClientLoopback
             ? this.firstHeaderValue(req.headers[SOLID_LOCAL_ROUTE_CANONICAL_URL_HEADER])
             : undefined;
         const clientCanonicalOrigin = originalClientLoopback
             ? this.firstHeaderValue(req.headers[SOLID_LOCAL_ROUTE_CANONICAL_ORIGIN_HEADER])
             : undefined;
-        const clientLocalRouteUrl = originalClientLoopback && localCanonicalHost
+        const clientLocalRouteUrl = originalClientLoopback
             ? this.localRouteUrlFromRequest(originalHost, url)
             : undefined;
         this.stripSolidLocalRouteHeaders(req.headers);
@@ -284,6 +308,16 @@ class GatewayProxy {
                 const parsedBaseUrl = new URL(baseUrl);
                 req.headers.host = parsedBaseUrl.host;
                 req.headers['x-forwarded-host'] = parsedBaseUrl.host;
+                if (clientLocalRouteUrl) {
+                    // Ordinary local Account requests have no SDK routing headers. When
+                    // the Gateway canonicalizes their host, preserve the original URL
+                    // for CSS to verify the same DPoP proof, just as for an SDK route.
+                    // Derive all route metadata here; incoming route headers were stripped.
+                    req.headers[SOLID_LOCAL_ROUTE_CANONICAL_URL_HEADER] = new URL(url, parsedBaseUrl.origin).href;
+                    req.headers[SOLID_LOCAL_ROUTE_CANONICAL_ORIGIN_HEADER] = parsedBaseUrl.origin;
+                    req.headers[SOLID_LOCAL_ROUTE_CANONICAL_HOST_HEADER] = parsedBaseUrl.host;
+                    req.headers[SOLID_LOCAL_ROUTE_LOCAL_URL_HEADER] = clientLocalRouteUrl;
+                }
             }
             catch {
                 if (!req.headers['x-forwarded-host']) {
@@ -330,7 +364,7 @@ class GatewayProxy {
             }
             const interceptedRequest = req;
             interceptedRequest.__xpodInspectRootMutation = this.shouldInspectRootMutation(req);
-            if (clientLocalRouteUrl && clientCanonicalUrl) {
+            if (req.headers[SOLID_LOCAL_ROUTE_LOCAL_URL_HEADER] && req.headers[SOLID_LOCAL_ROUTE_CANONICAL_URL_HEADER]) {
                 // Unix-socket CSS peers have no IP address. Attest the original local
                 // transport using the existing internal signature; CSS still verifies
                 // the user's DPoP proof against the actual ingress URL.
@@ -348,20 +382,16 @@ class GatewayProxy {
     }
     isApiWebProductPath(url) {
         const pathname = this.pathnameFromRequestUrl(url);
-        return [
-            '/dashboard',
-            '/status',
-            '/network',
-            '/settings',
-            '/ai-config',
-            '/ai-connections',
-        ].some((prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`))
+        return (0, xpod_route_policy_1.isXpodProductPath)(pathname)
             || pathname === '/auth/callback'
             || pathname === '/auth/callback/theme-init.js'
             || pathname === '/auth/callback/assets'
             || pathname.startsWith('/auth/callback/assets/');
     }
-    shouldRouteToApi(url) {
+    shouldRouteToApi(url, method) {
+        if ((0, PodDeletionRoute_1.podDeletionRouteName)(method, url) !== undefined) {
+            return false;
+        }
         const pathname = this.pathnameFromRequestUrl(url);
         return pathname.startsWith('/v1/')
             || pathname.startsWith('/api/')
@@ -594,8 +624,11 @@ class GatewayProxy {
             // Status is the entry probe every client uses, and it carries no secrets.
             if (pathname === '/service/status') {
                 const status = this.supervisor.getAllStatus();
-                const cssReady = await this.isCssReady();
-                const code = cssReady ? 200 : 503;
+                // Readiness must cover every supervised child, not just CSS: a gateway whose API child
+                // crashed and gave up used to answer 200 here for hours while /api/* returned 502 (N20).
+                const servicesReady = this.supervisor.isReady();
+                const cssReady = servicesReady && await this.isCssReady();
+                const code = servicesReady && cssReady ? 200 : 503;
                 res.writeHead(code, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify(status));
                 return;

package/dist/runtime/XpodRuntime.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startXpodRuntime = startXpodRuntime;
+const ensureSupportedBun_1 = require("./compat/ensureSupportedBun");
 const global_logger_factory_1 = require("global-logger-factory");
 const container_1 = require("../api/container");
 const runtime_1 = require("../api/runtime");
+const HostedPodRoute_1 = require("../api/ai-gateway/pod/HostedPodRoute");
 const db_1 = require("../identity/drizzle/db");
 const Supervisor_1 = require("../supervisor/Supervisor");
 const bootstrap_1 = require("./bootstrap");
@@ -12,6 +14,7 @@ const NodeRuntimeDriver_1 = require("./driver/node/NodeRuntimeDriver");
 const environment_1 = require("./environment");
 const lifecycle_1 = require("./lifecycle");
 async function startXpodRuntime(options = {}) {
+    (0, ensureSupportedBun_1.ensureSupportedBun)();
     const driver = options.driver ?? NodeRuntimeDriver_1.nodeRuntimeDriver;
     const host = options.host ?? driver.host;
     const platform = options.platform ?? driver.platform;
@@ -109,6 +112,11 @@ async function startXpodRuntime(options = {}) {
             clientRemoteAddressResolver: options.gatewayClientRemoteAddressResolver,
         });
         environment.restore();
+        const listenerRoute = state.transport === 'port' ? (0, HostedPodRoute_1.resolveHostedPodRoute)({
+            canonicalBaseUrl: state.baseUrl,
+            gatewayHost: state.bindHost,
+            gatewayPort: state.ports.gateway,
+        }) : undefined;
         return {
             id,
             mode: state.mode,
@@ -118,10 +126,18 @@ async function startXpodRuntime(options = {}) {
             ports: state.ports,
             sockets: state.sockets,
             fetch: async (input, init) => {
-                if (typeof input === 'string' || input instanceof URL) {
-                    return platform.fetch(new URL(String(input), state.baseUrl), init);
-                }
-                return platform.fetch(input, init);
+                const request = input instanceof Request ? input : new URL(String(input), state.baseUrl);
+                if (!listenerRoute)
+                    return platform.fetch(request, init);
+                const requestUrl = request instanceof Request ? new URL(request.url) : request;
+                const headers = new Headers(init?.headers ?? (request instanceof Request ? request.headers : undefined));
+                if (!headers.has('host'))
+                    headers.set('host', requestUrl.host);
+                // Only replace the socket destination. Preserve the caller's authority and
+                // headers: adding Pod-route metadata here would override the Gateway's own
+                // canonicalization (or an outer DPoP transport's existing route metadata).
+                const runtimeFetch = await (0, HostedPodRoute_1.createHostedPodRouteTransport)((wireInput, wireInit) => platform.fetch(wireInput, { ...wireInit, headers }), listenerRoute);
+                return runtimeFetch(request, init);
             },
             stop,
         };

package/dist/runtime/bootstrap.js

@@ -165,6 +165,7 @@ async function resolveRuntimeBootstrap(id, options, host, platform = NodeRuntime
             gatewayPort: options.gatewayPort,
             cssPort: options.cssPort,
             apiPort: options.apiPort,
+            ingressPort: options.ingressPort,
             basePort: 5600,
         })
         : {};

package/dist/runtime/compat/ensureSupportedBun.d.ts

@@ -0,0 +1,2 @@
+/** Fail before opening services on runtimes with broken WebSocket shutdown. */
+export declare function ensureSupportedBun(version?: string | undefined): void;

package/dist/runtime/compat/ensureSupportedBun.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureSupportedBun = ensureSupportedBun;
+// Keep the supported service runtime in package.json; the single-file build
+// bundles this manifest together with the check.
+const { engines } = require('../../../package.json');
+/** Fail before opening services on runtimes with broken WebSocket shutdown. */
+function ensureSupportedBun(version = process.versions.bun) {
+    if (version === undefined) {
+        return;
+    }
+    const minimum = engines.bun.slice(2).split('.').map(Number);
+    const parsed = /^(\d+)\.(\d+)\.(\d+)(-[^+]+)?(?:\+.*)?$/u.exec(version);
+    if (parsed) {
+        const actual = parsed.slice(1, 4).map(Number);
+        const difference = actual.map((value, index) => value - minimum[index]).find((value) => value !== 0) ?? 0;
+        if (difference > 0 || (difference === 0 && !parsed[4])) {
+            return;
+        }
+    }
+    throw new Error(`Xpod requires Bun ${engines.bun}; found ${version}. Older Bun versions can hang during WebSocket shutdown. Upgrade Bun before starting Xpod.`);
+}
+//# sourceMappingURL=ensureSupportedBun.js.map

package/dist/runtime/css-process.d.ts

@@ -6,13 +6,13 @@ import type { AuthMode } from '../authorization/AuthMode';
  * The legacy CSS child process path injects it through a generated
  * Components.js config instead of CSS_* env aliases.
  */
-export declare function buildCssChildEnv(baseUrl: string, cssPort: number, oidcIssuer?: string, authModeInput?: AuthMode | string, baseEnv?: NodeJS.ProcessEnv, gatewayAdminProxyAuthSecret?: string, mode?: 'local' | 'cloud'): Record<string, string>;
+export declare function buildCssChildEnv(baseUrl: string, cssPort: number, oidcIssuer?: string, authModeInput?: AuthMode | string, baseEnv?: Record<string, string | undefined>, gatewayAdminProxyAuthSecret?: string, mode?: 'local' | 'cloud'): Record<string, string>;
 export declare function createCssChildRuntimeConfig(options: {
     configPath: string;
     runtimeRoot: string;
     authMode?: AuthMode | string;
     externalOidcIssuer?: string;
-    baseEnv?: NodeJS.ProcessEnv;
+    baseEnv?: Record<string, string | undefined>;
 }): {
     configPath: string;
     cwd?: string;
@@ -36,5 +36,5 @@ export declare function buildApiChildEnv(options: {
     authMode?: AuthMode | string;
     externalOidcIssuer?: string;
     gatewayAdminProxyAuthSecret?: string;
-    baseEnv?: NodeJS.ProcessEnv;
+    baseEnv?: Record<string, string | undefined>;
 }): Record<string, string>;

package/dist/runtime/gateway-locator-secret.js

@@ -1,17 +1,9 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolvePersistentGatewayLocatorSecret = resolvePersistentGatewayLocatorSecret;
 exports.secretPathForGatewayLocatorDatabase = secretPathForGatewayLocatorDatabase;
-const node_crypto_1 = require("node:crypto");
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
 const database_url_1 = require("./database-url");
-const SECRET_BYTES = 32;
-const SECRET_FILE_MODE = 0o600;
-const SECRET_DIR_MODE = 0o700;
+const local_secret_file_1 = require("./local-secret-file");
 function resolvePersistentGatewayLocatorSecret(options) {
     if (options.edition === 'cloud') {
         throw new Error('XPOD_GATEWAY_LOCATOR_SECRET is required for Cloud Gateway API keys; configure one stable shared value across replicas.');
@@ -20,137 +12,19 @@ function resolvePersistentGatewayLocatorSecret(options) {
     if (!databasePath) {
         throw new Error('XPOD_GATEWAY_LOCATOR_SECRET is required when CSS_IDENTITY_DB_URL is not a file-backed SQLite database.');
     }
-    return readOrCreateSecret(secretPathForDatabase(databasePath), node_path_1.default.dirname(databasePath));
+    return (0, local_secret_file_1.readOrCreateLocalSecret)({
+        databasePath,
+        purpose: 'gateway-locator-secret',
+        label: 'Gateway locator secret',
+        // Keep existing locator strings readable; only newly generated values are fixed at 32 bytes.
+        isValid: value => /^[A-Za-z0-9_-]{32,}$/u.test(value),
+    });
 }
 function secretPathForGatewayLocatorDatabase(databaseUrl) {
     const databasePath = (0, database_url_1.sqliteDatabaseFilePath)(databaseUrl);
     return databasePath ? secretPathForDatabase(databasePath) : undefined;
 }
 function secretPathForDatabase(databasePath) {
-    return node_path_1.default.join(node_path_1.default.dirname(databasePath), '.xpod', 'secrets', 'gateway-locator-secret');
-}
-function readOrCreateSecret(filePath, privateRoot) {
-    const dirPath = node_path_1.default.dirname(filePath);
-    try {
-        node_fs_1.default.mkdirSync(dirPath, { recursive: true, mode: SECRET_DIR_MODE });
-        assertPrivateDirectoryPath(privateRoot, dirPath);
-    }
-    catch (error) {
-        throw new Error(`Failed to prepare Gateway locator secret directory at ${dirPath}: ${error.message}`, {
-            cause: error,
-        });
-    }
-    if (!node_fs_1.default.existsSync(filePath)) {
-        publishNewSecret(filePath);
-    }
-    const secret = readExistingSecret(filePath);
-    if (!isValidSecret(secret)) {
-        throw new Error(`Gateway locator secret file at ${filePath} is invalid; refusing to replace it automatically.`);
-    }
-    return secret;
-}
-function publishNewSecret(filePath) {
-    const dirPath = node_path_1.default.dirname(filePath);
-    const tempPath = node_path_1.default.join(dirPath, `.gateway-locator-secret.${process.pid}.${(0, node_crypto_1.randomBytes)(8).toString('hex')}.tmp`);
-    let fd;
-    try {
-        fd = node_fs_1.default.openSync(tempPath, 'wx', SECRET_FILE_MODE);
-        node_fs_1.default.writeFileSync(fd, `${(0, node_crypto_1.randomBytes)(SECRET_BYTES).toString('base64url')}\n`, { encoding: 'utf8' });
-        node_fs_1.default.fsyncSync(fd);
-        node_fs_1.default.closeSync(fd);
-        fd = undefined;
-        node_fs_1.default.linkSync(tempPath, filePath);
-        fsyncDirectory(dirPath);
-    }
-    catch (error) {
-        if (!isAlreadyExists(error)) {
-            throw new Error(`Failed to create Gateway locator secret file at ${filePath}: ${error.message}`, {
-                cause: error,
-            });
-        }
-    }
-    finally {
-        if (fd !== undefined) {
-            node_fs_1.default.closeSync(fd);
-        }
-        try {
-            node_fs_1.default.unlinkSync(tempPath);
-        }
-        catch (error) {
-            if (!isNotFound(error)) {
-                throw error;
-            }
-        }
-    }
-}
-function isValidSecret(value) {
-    return /^[A-Za-z0-9_-]{32,}$/u.test(value);
-}
-function readExistingSecret(filePath) {
-    const stat = node_fs_1.default.lstatSync(filePath);
-    if (stat.isSymbolicLink()) {
-        throw new Error(`Gateway locator secret file at ${filePath} must not be a symlink.`);
-    }
-    if (!stat.isFile()) {
-        throw new Error(`Gateway locator secret file at ${filePath} must be a regular file.`);
-    }
-    const fd = node_fs_1.default.openSync(filePath, node_fs_1.default.constants.O_RDONLY | noFollowFlag());
-    try {
-        const fdStat = node_fs_1.default.fstatSync(fd);
-        if (!fdStat.isFile()) {
-            throw new Error(`Gateway locator secret file at ${filePath} must be a regular file.`);
-        }
-        if (process.platform !== 'win32' && (fdStat.mode & 0o777) !== SECRET_FILE_MODE) {
-            throw new Error(`Gateway locator secret file at ${filePath} must have mode 0600.`);
-        }
-        return node_fs_1.default.readFileSync(fd, 'utf8').trim();
-    }
-    finally {
-        node_fs_1.default.closeSync(fd);
-    }
-}
-function assertPrivateDirectoryPath(privateRoot, dirPath) {
-    const relative = node_path_1.default.relative(privateRoot, dirPath);
-    if (relative.startsWith('..') || node_path_1.default.isAbsolute(relative)) {
-        throw new Error('Gateway locator secret directory must stay under the identity database directory.');
-    }
-    let current = privateRoot;
-    for (const segment of relative.split(node_path_1.default.sep).filter(Boolean)) {
-        current = node_path_1.default.join(current, segment);
-        const stat = node_fs_1.default.lstatSync(current);
-        if (stat.isSymbolicLink()) {
-            throw new Error(`Gateway locator secret directory at ${current} must not be a symlink.`);
-        }
-        if (!stat.isDirectory()) {
-            throw new Error(`Gateway locator secret directory at ${current} must be a directory.`);
-        }
-    }
-}
-function fsyncDirectory(dirPath) {
-    if (process.platform === 'win32') {
-        return;
-    }
-    const fd = node_fs_1.default.openSync(dirPath, node_fs_1.default.constants.O_RDONLY);
-    try {
-        node_fs_1.default.fsyncSync(fd);
-    }
-    finally {
-        node_fs_1.default.closeSync(fd);
-    }
-}
-function noFollowFlag() {
-    return typeof node_fs_1.default.constants.O_NOFOLLOW === 'number' ? node_fs_1.default.constants.O_NOFOLLOW : 0;
-}
-function isAlreadyExists(error) {
-    return typeof error === 'object'
-        && error !== null
-        && 'code' in error
-        && error.code === 'EEXIST';
-}
-function isNotFound(error) {
-    return typeof error === 'object'
-        && error !== null
-        && 'code' in error
-        && error.code === 'ENOENT';
+    return (0, local_secret_file_1.localSecretPathForDatabase)(databasePath, 'gateway-locator-secret');
 }
 //# sourceMappingURL=gateway-locator-secret.js.map

package/dist/runtime/host/node/NodeRuntimeHost.d.ts

@@ -1,4 +1,4 @@
-import type { RuntimeConnectionTarget, RuntimeHost, RuntimeListenEndpoint, RuntimeListenableServer, RuntimePortAllocationOptions, RuntimePorts, RuntimeTransport, RuntimeTransportPreference } from '../types';
+import type { RuntimeConnectionTarget, RuntimeCloseOptions, RuntimeHost, RuntimeListenEndpoint, RuntimeListenableServer, RuntimePortAllocationOptions, RuntimePorts, RuntimeTransport, RuntimeTransportPreference } from '../types';
 export declare class NodeRuntimeHost implements RuntimeHost {
     readonly name = "node";
     resolveTransport(preference?: RuntimeTransportPreference): RuntimeTransport;
@@ -10,7 +10,8 @@ export declare class NodeRuntimeHost implements RuntimeHost {
     }): RuntimeListenEndpoint;
     formatListenEndpoint(endpoint: RuntimeListenEndpoint): string;
     listen(server: RuntimeListenableServer, endpoint: RuntimeListenEndpoint): Promise<void>;
-    close(server: RuntimeListenableServer, endpoint?: RuntimeListenEndpoint): Promise<void>;
+    close(server: RuntimeListenableServer, endpoint?: RuntimeListenEndpoint, options?: RuntimeCloseOptions): Promise<void>;
+    private closeListener;
     waitForPortReady(port: number, host?: string, timeoutMs?: number): Promise<void>;
     isConnectionTargetReady(target: RuntimeConnectionTarget, timeoutMs?: number): Promise<boolean>;
     registerSocketOrigins(origin: string, socketPath: string): () => Promise<void>;

package/dist/runtime/host/node/NodeRuntimeHost.js

@@ -20,14 +20,28 @@ class NodeRuntimeHost {
         return process.platform === 'win32' ? 'port' : 'socket';
     }
     async allocatePorts(options = {}) {
-        const gateway = options.gatewayPort ?? await (0, port_finder_1.getFreePort)(options.basePort ?? 5600);
-        const css = options.cssPort ?? await (0, port_finder_1.getFreePort)(gateway + 1);
-        const api = options.apiPort ?? await (0, port_finder_1.getFreePort)(css + 1);
+        const explicitPorts = [options.gatewayPort, options.cssPort, options.apiPort, options.ingressPort]
+            .filter((port) => port !== undefined);
+        const selected = new Set(explicitPorts);
+        if (selected.size !== explicitPorts.length) {
+            throw new Error('Runtime service ports must be distinct');
+        }
+        // Probes release their sockets, so the OS cannot see ports planned for this runtime.
+        // Reserve both explicit and newly selected ports locally until allocation finishes.
+        // Probe wildcard and loopback addresses in both families before selecting each port.
+        const allocate = async (explicit, base) => {
+            const port = explicit ?? await (0, port_finder_1.getFreePortForWildcard)(base, undefined, selected);
+            selected.add(port);
+            return port;
+        };
+        const gateway = await allocate(options.gatewayPort, options.basePort ?? 5600);
+        const css = await allocate(options.cssPort, gateway + 1);
+        const api = await allocate(options.apiPort, css + 1);
         // Tunnels (and the P2P data plane) terminate here, and this listener never treats a
         // caller as local whatever headers it carries - that is the gate. Its port is the one
         // number the user copies into a provider console, so it is predictable rather than
         // random, and it is what the runtime reports as the tunnel origin.
-        const ingress = options.ingressPort ?? await (0, port_finder_1.findGatewayIngressPort)(gateway);
+        const ingress = options.ingressPort ?? await (0, port_finder_1.findGatewayIngressPort)(gateway, selected);
         return { gateway, css, api, ingress };
     }
     createListenEndpoint(options) {
@@ -60,7 +74,25 @@ class NodeRuntimeHost {
             server.listen(endpoint.port, endpoint.host, () => resolve());
         });
     }
-    async close(server, endpoint) {
+    async close(server, endpoint, options) {
+        if (options?.connectionsDrained && server.closeAllConnections) {
+            // Subscribe before closing: Bun stops the native listener here as well,
+            // whereas Node keeps it listening until close(). Never synthesize completion.
+            const closed = new Promise((resolve) => { server.once('close', resolve); });
+            server.closeAllConnections();
+            if (server.listening !== false) {
+                await this.closeListener(server);
+            }
+            await closed;
+        }
+        else {
+            await this.closeListener(server);
+        }
+        if (endpoint?.type === 'socket') {
+            (0, socket_utils_1.removeSocketPath)(endpoint.socketPath);
+        }
+    }
+    async closeListener(server) {
         await new Promise((resolve, reject) => {
             server.close((error) => {
                 if (error) {
@@ -70,9 +102,6 @@ class NodeRuntimeHost {
                 resolve();
             });
         });
-        if (endpoint?.type === 'socket') {
-            (0, socket_utils_1.removeSocketPath)(endpoint.socketPath);
-        }
     }
     async waitForPortReady(port, host = '127.0.0.1', timeoutMs = 5_000) {
         const deadline = Date.now() + timeoutMs;

package/dist/runtime/host/types.d.ts

@@ -16,6 +16,9 @@ export interface RuntimeConnectionTarget {
 }
 export interface RuntimeListenableServer {
     once(event: 'error', listener: (error: Error) => void): unknown;
+    once(event: 'close', listener: () => void): unknown;
+    readonly listening?: boolean;
+    closeAllConnections?(): void;
     listen(socketPath: string, listeningListener?: () => void): unknown;
     listen(port: number, host: string, listeningListener?: () => void): unknown;
     close(callback: (error?: Error | null) => void): unknown;
@@ -37,6 +40,10 @@ export interface RuntimePorts {
      */
     ingress: number;
 }
+export interface RuntimeCloseOptions {
+    /** Caller has fenced new work and awaited all handlers, responses and upgrades. */
+    connectionsDrained?: boolean;
+}
 export interface RuntimeHost {
     readonly name: string;
     resolveTransport(preference?: RuntimeTransportPreference): RuntimeTransport;
@@ -48,7 +55,7 @@ export interface RuntimeHost {
     }): RuntimeListenEndpoint;
     formatListenEndpoint(endpoint: RuntimeListenEndpoint): string;
     listen(server: RuntimeListenableServer, endpoint: RuntimeListenEndpoint): Promise<void>;
-    close(server: RuntimeListenableServer, endpoint?: RuntimeListenEndpoint): Promise<void>;
+    close(server: RuntimeListenableServer, endpoint?: RuntimeListenEndpoint, options?: RuntimeCloseOptions): Promise<void>;
     waitForPortReady(port: number, host?: string, timeoutMs?: number): Promise<void>;
     isConnectionTargetReady(target: RuntimeConnectionTarget, timeoutMs?: number): Promise<boolean>;
     registerSocketOrigins(origin: string, socketPath: string): () => Promise<void>;

package/dist/runtime/index.d.ts

@@ -10,7 +10,13 @@ export { createOpenAuthContext, registerManagedRuntimeServices, startApiRuntime,
 export type { RuntimeServices } from './lifecycle';
 export { GatewayProxy } from './Proxy';
 export { createGatewayAdminProxyAuthSecret } from './GatewayAdminProxyAuth';
-export { findGatewayIngressPort, getEphemeralLoopbackPort, getFreePort, getFreePortForWildcard, requireFreePortForWildcard } from './port-finder';
+export { findGatewayIngressPort, getEphemeralLoopbackPort, getFreePort, getFreePortForWildcard, isFreePortForWildcard, requireFreePortForWildcard } from './port-finder';
+export { assertUsableIngressPort, parseExplicitIngressPort, resolveIngressPort, IngressPortConflictError } from './ingress-port';
+export type { IngressPortDeclaration, IngressPortResolution, IngressPortSource } from './ingress-port';
+export { identifyIngressPortOccupants } from './ingress-occupant';
+export { getUnreservedEphemeralPort, listenOnUnreservedPort, PORT_RESERVATION_DIR_ENV, RESERVED_PORTS_ENV, portReservation, portReservationDir, readPortReservations, releasePort, reservePort, reservedPorts, } from './port-reservations';
+export type { PortReservation } from './port-reservations';
+export type { IngressPortOccupant, IngressPortOccupants } from './ingress-occupant';
 export { ensureTrailingSlash, INVALID_CONFIGURATION_PREFIX, validateBaseUrl } from './base-url';
 export type { ValidateBaseUrlOptions } from './base-url';
 export { applyEnv, loadEnvFile } from './env-utils';

package/dist/runtime/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startXpodRuntime = exports.nodeGatewayRuntimeRunner = exports.NodeGatewayRuntimeRunner = exports.nodeApiRuntimeRunner = exports.NodeApiRuntimeRunner = exports.communitySolidServerCssRunner = exports.CommunitySolidServerCssRunner = exports.registerSocketOriginShims = exports.registerSocketFetchOrigin = exports.nodeRuntimePlatform = exports.NodeRuntimePlatform = exports.nodeRuntimeHost = exports.NodeRuntimeHost = exports.resolveXpodEnvPath = exports.defaultXpodEnvPath = exports.loadEnvFile = exports.applyEnv = exports.validateBaseUrl = exports.INVALID_CONFIGURATION_PREFIX = exports.ensureTrailingSlash = exports.requireFreePortForWildcard = exports.getFreePortForWildcard = exports.getFreePort = exports.getEphemeralLoopbackPort = exports.findGatewayIngressPort = exports.createGatewayAdminProxyAuthSecret = exports.GatewayProxy = exports.stopRuntimeServices = exports.startGatewayRuntime = exports.startCssRuntime = exports.startApiRuntime = exports.registerManagedRuntimeServices = exports.createOpenAuthContext = exports.createRuntimeEnvironmentSession = exports.nodeRuntimeDriver = exports.NodeRuntimeDriver = exports.resolveRuntimeBootstrap = exports.initRuntimeLogger = exports.createCssRuntimeConfig = exports.buildRuntimeShorthand = exports.buildRuntimeEnv = exports.ensureBunUndiciCompat = exports.findPackageRoot = exports.PACKAGE_ROOT = void 0;
+exports.NodeRuntimePlatform = exports.nodeRuntimeHost = exports.NodeRuntimeHost = exports.resolveXpodEnvPath = exports.defaultXpodEnvPath = exports.loadEnvFile = exports.applyEnv = exports.validateBaseUrl = exports.INVALID_CONFIGURATION_PREFIX = exports.ensureTrailingSlash = exports.reservedPorts = exports.reservePort = exports.releasePort = exports.readPortReservations = exports.portReservationDir = exports.portReservation = exports.RESERVED_PORTS_ENV = exports.PORT_RESERVATION_DIR_ENV = exports.listenOnUnreservedPort = exports.getUnreservedEphemeralPort = exports.identifyIngressPortOccupants = exports.IngressPortConflictError = exports.resolveIngressPort = exports.parseExplicitIngressPort = exports.assertUsableIngressPort = exports.requireFreePortForWildcard = exports.isFreePortForWildcard = exports.getFreePortForWildcard = exports.getFreePort = exports.getEphemeralLoopbackPort = exports.findGatewayIngressPort = exports.createGatewayAdminProxyAuthSecret = exports.GatewayProxy = exports.stopRuntimeServices = exports.startGatewayRuntime = exports.startCssRuntime = exports.startApiRuntime = exports.registerManagedRuntimeServices = exports.createOpenAuthContext = exports.createRuntimeEnvironmentSession = exports.nodeRuntimeDriver = exports.NodeRuntimeDriver = exports.resolveRuntimeBootstrap = exports.initRuntimeLogger = exports.createCssRuntimeConfig = exports.buildRuntimeShorthand = exports.buildRuntimeEnv = exports.ensureBunUndiciCompat = exports.findPackageRoot = exports.PACKAGE_ROOT = void 0;
+exports.startXpodRuntime = exports.nodeGatewayRuntimeRunner = exports.NodeGatewayRuntimeRunner = exports.nodeApiRuntimeRunner = exports.NodeApiRuntimeRunner = exports.communitySolidServerCssRunner = exports.CommunitySolidServerCssRunner = exports.registerSocketOriginShims = exports.registerSocketFetchOrigin = exports.nodeRuntimePlatform = void 0;
 require("./configure-drizzle-solid");
 var package_root_1 = require("./package-root");
 Object.defineProperty(exports, "PACKAGE_ROOT", { enumerable: true, get: function () { return package_root_1.PACKAGE_ROOT; } });
@@ -34,7 +35,26 @@ Object.defineProperty(exports, "findGatewayIngressPort", { enumerable: true, get
 Object.defineProperty(exports, "getEphemeralLoopbackPort", { enumerable: true, get: function () { return port_finder_1.getEphemeralLoopbackPort; } });
 Object.defineProperty(exports, "getFreePort", { enumerable: true, get: function () { return port_finder_1.getFreePort; } });
 Object.defineProperty(exports, "getFreePortForWildcard", { enumerable: true, get: function () { return port_finder_1.getFreePortForWildcard; } });
+Object.defineProperty(exports, "isFreePortForWildcard", { enumerable: true, get: function () { return port_finder_1.isFreePortForWildcard; } });
 Object.defineProperty(exports, "requireFreePortForWildcard", { enumerable: true, get: function () { return port_finder_1.requireFreePortForWildcard; } });
+var ingress_port_1 = require("./ingress-port");
+Object.defineProperty(exports, "assertUsableIngressPort", { enumerable: true, get: function () { return ingress_port_1.assertUsableIngressPort; } });
+Object.defineProperty(exports, "parseExplicitIngressPort", { enumerable: true, get: function () { return ingress_port_1.parseExplicitIngressPort; } });
+Object.defineProperty(exports, "resolveIngressPort", { enumerable: true, get: function () { return ingress_port_1.resolveIngressPort; } });
+Object.defineProperty(exports, "IngressPortConflictError", { enumerable: true, get: function () { return ingress_port_1.IngressPortConflictError; } });
+var ingress_occupant_1 = require("./ingress-occupant");
+Object.defineProperty(exports, "identifyIngressPortOccupants", { enumerable: true, get: function () { return ingress_occupant_1.identifyIngressPortOccupants; } });
+var port_reservations_1 = require("./port-reservations");
+Object.defineProperty(exports, "getUnreservedEphemeralPort", { enumerable: true, get: function () { return port_reservations_1.getUnreservedEphemeralPort; } });
+Object.defineProperty(exports, "listenOnUnreservedPort", { enumerable: true, get: function () { return port_reservations_1.listenOnUnreservedPort; } });
+Object.defineProperty(exports, "PORT_RESERVATION_DIR_ENV", { enumerable: true, get: function () { return port_reservations_1.PORT_RESERVATION_DIR_ENV; } });
+Object.defineProperty(exports, "RESERVED_PORTS_ENV", { enumerable: true, get: function () { return port_reservations_1.RESERVED_PORTS_ENV; } });
+Object.defineProperty(exports, "portReservation", { enumerable: true, get: function () { return port_reservations_1.portReservation; } });
+Object.defineProperty(exports, "portReservationDir", { enumerable: true, get: function () { return port_reservations_1.portReservationDir; } });
+Object.defineProperty(exports, "readPortReservations", { enumerable: true, get: function () { return port_reservations_1.readPortReservations; } });
+Object.defineProperty(exports, "releasePort", { enumerable: true, get: function () { return port_reservations_1.releasePort; } });
+Object.defineProperty(exports, "reservePort", { enumerable: true, get: function () { return port_reservations_1.reservePort; } });
+Object.defineProperty(exports, "reservedPorts", { enumerable: true, get: function () { return port_reservations_1.reservedPorts; } });
 var base_url_1 = require("./base-url");
 Object.defineProperty(exports, "ensureTrailingSlash", { enumerable: true, get: function () { return base_url_1.ensureTrailingSlash; } });
 Object.defineProperty(exports, "INVALID_CONFIGURATION_PREFIX", { enumerable: true, get: function () { return base_url_1.INVALID_CONFIGURATION_PREFIX; } });

package/dist/runtime/ingress-occupant.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Who holds a port.
+ *
+ * A tunnel console forwards to a number, not to a process: if something else already listens
+ * there, binding "somewhere else" would make the tunnel reach that other process, and killing
+ * it is not this runtime's decision to make. So the only thing this module does is *name* the
+ * occupant (pid, command line, cwd, start time) so a refused start points at a culprit instead
+ * of at a number. Nothing here ever signals a process.
+ */
+export interface IngressPortOccupant {
+    pid: number;
+    /** Full command line when it could be read. */
+    command: string;
+    cwd?: string;
+    startedAt?: string;
+}
+export interface IngressPortOccupants {
+    port: number;
+    occupants: IngressPortOccupant[];
+    /**
+     * One line naming every occupant, for an error message. When nothing can be identified it
+     * says so explicitly: "taken by something we cannot name" is a different fact from "free".
+     */
+    description: string;
+}
+export interface IdentifyOccupantsDeps {
+    /** Runs a command and returns stdout. Injected in tests. */
+    exec?: (file: string, args: readonly string[]) => string;
+}
+/**
+ * Names every process listening on the port.
+ *
+ * `lsof` is the portable answer on macOS and most Linux images; `ss` covers Linux hosts
+ * without lsof. When neither is available the answer is "an unidentified listener", never a
+ * silent success.
+ */
+export declare function identifyIngressPortOccupants(port: number, deps?: IdentifyOccupantsDeps): IngressPortOccupants;
+/** One line for an operator: pid, command, cwd and start time of everything on the port. */
+export declare function describeOccupants(port: number, occupants: readonly IngressPortOccupant[], probeFailure?: string): string;