@undefineds.co/xpod 0.4.14 → 0.4.16

package/dist/runtime/ingress-port.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IngressPortConflictError = void 0;
+exports.defaultIngressPortDeps = defaultIngressPortDeps;
+exports.assertUsableIngressPort = assertUsableIngressPort;
+exports.parseExplicitIngressPort = parseExplicitIngressPort;
+exports.resolveIngressPort = resolveIngressPort;
+const global_logger_factory_1 = require("global-logger-factory");
+const port_finder_1 = require("./port-finder");
+const ingress_occupant_1 = require("./ingress-occupant");
+const TunnelDeclaredOrigin_1 = require("../tunnel/TunnelDeclaredOrigin");
+const TunnelProviderCatalog_1 = require("../tunnel/TunnelProviderCatalog");
+/** A strict port that could not be taken: the occupant is named, and nothing was signalled. */
+class IngressPortConflictError extends Error {
+    constructor(port, occupant) {
+        super(`tunnel entry port ${port} is already in use by ${occupant}`);
+        this.port = port;
+        this.occupant = occupant;
+        this.name = 'IngressPortConflictError';
+    }
+}
+exports.IngressPortConflictError = IngressPortConflictError;
+function defaultIngressPortDeps() {
+    const logger = (0, global_logger_factory_1.getLoggerFor)('IngressPort');
+    return {
+        findDefaultPort: port_finder_1.findGatewayIngressPort,
+        isFree: port_finder_1.isFreePortForWildcard,
+        identifyOccupants: (port) => (0, ingress_occupant_1.identifyIngressPortOccupants)(port).description,
+        readDeclaredOrigin: async (profile, options) => await (0, TunnelDeclaredOrigin_1.readDeclaredIngressOrigin)(profile, {
+            env: options.env,
+            active: options.active,
+        }),
+        logger: {
+            info: (message) => logger.info(message),
+            warn: (message) => logger.warn(message),
+        },
+    };
+}
+/**
+ * Validates a port that came from outside this runtime (an operator pin or a console).
+ *
+ * Zero, out-of-range and privileged ports are refused with the reason spelled out: binding
+ * them either fails later with a bare errno, or needs privileges the runtime should not hold.
+ */
+function assertUsableIngressPort(port, options) {
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535) {
+        throw new Error(`${options.label} is not a usable port (expected 1-65535); `
+            + 'a tunnel origin has to be a real port number');
+    }
+    if (port < 1024) {
+        throw new Error(`${options.label} is a privileged port (1-1023); this runtime does not take root `
+            + 'to bind a tunnel origin, so point the tunnel at a port at or above 1024');
+    }
+    if (options.reservedPorts?.has(port)) {
+        throw new Error(`${options.label} is a port this runtime already serves (gateway/CSS/API); `
+            + 'the tunnel entry has to be its own listener, or forwarded traffic would land on another service');
+    }
+}
+/** Reads the explicit pin strictly: present but malformed is an error, not an absent value. */
+function parseExplicitIngressPort(raw) {
+    const trimmed = raw?.trim();
+    if (trimmed === undefined || trimmed === '') {
+        return undefined;
+    }
+    if (!/^\d+$/u.test(trimmed)) {
+        throw new Error(`XPOD_GATEWAY_INGRESS_PORT="${trimmed}" is not a valid port number (expected 1-65535)`);
+    }
+    return Number.parseInt(trimmed, 10);
+}
+async function resolveIngressPort(request) {
+    const deps = { ...defaultIngressPortDeps(), ...request.deps };
+    const env = request.env ?? process.env;
+    const reservedPorts = new Set(request.reservedPorts ?? []);
+    const profiles = request.profiles ?? [];
+    const activeProfileId = request.activeProfileId?.trim();
+    const active = activeProfileId && activeProfileId !== 'none'
+        ? profiles.find((profile) => profile.id === activeProfileId)
+        : undefined;
+    const explicit = parseExplicitIngressPort(env.XPOD_GATEWAY_INGRESS_PORT);
+    if (explicit !== undefined) {
+        assertUsableIngressPort(explicit, {
+            label: `XPOD_GATEWAY_INGRESS_PORT=${explicit}`,
+            reservedPorts,
+        });
+        await requireFree(explicit, `XPOD_GATEWAY_INGRESS_PORT=${explicit}`, deps);
+        deps.logger.info(`Tunnel entry pinned to ${explicit} by XPOD_GATEWAY_INGRESS_PORT `
+            + '(a provider console value is not read while an explicit pin is present)');
+        return { port: explicit, source: 'explicit', inactiveDeclarations: [] };
+    }
+    const inactiveDeclarations = await readInactiveConsoleDeclarations({ profiles, active, env, deps });
+    for (const declaration of inactiveDeclarations) {
+        deps.logger.warn(`profile ${declaration.profileId} (${declaration.provider}) is not active, but its console declares `
+            + `tunnel origin ${declaration.port} (${declaration.readBack}); `
+            + `the active profile is ${active?.id ?? 'none'}, so its entry decides this runtime's listener`);
+    }
+    const activeDescriptor = active ? (0, TunnelProviderCatalog_1.tunnelProviderDescriptor)(active.provider) : undefined;
+    if (active && activeDescriptor?.originOwner === 'console') {
+        const read = await deps.readDeclaredOrigin(active, { env, active: true });
+        if (read.origin) {
+            const label = `the ${activeDescriptor.label} console's declared tunnel origin ${read.origin.port}`;
+            assertUsableIngressPort(read.origin.port, { label, reservedPorts });
+            await requireFree(read.origin.port, label, deps);
+            if (read.origin.scheme && read.origin.scheme !== 'http') {
+                deps.logger.warn(`${activeDescriptor.label} declares the origin as ${read.origin.scheme}://localhost:${read.origin.port}, `
+                    + `but this runtime's tunnel entry speaks plain HTTP; the port is adopted, the scheme is not `
+                    + '(terminate TLS in the provider, or point the console at http://)');
+            }
+            deps.logger.info(`Adopting the ${activeDescriptor.label} console's tunnel origin ${read.origin.port} `
+                + `(${read.origin.readBack}); the operator does not have to edit the console`);
+            return {
+                port: read.origin.port,
+                source: 'console-declared',
+                declared: {
+                    profileId: active.id,
+                    provider: activeDescriptor.id,
+                    port: read.origin.port,
+                    readBack: read.origin.readBack,
+                    ...(read.origin.scheme ? { scheme: read.origin.scheme } : {}),
+                },
+                inactiveDeclarations,
+            };
+        }
+        // The console owns the number, so the runtime cannot invent a different one and still be
+        // reachable. The declaration is unreadable here, which is reported loudly; an explicit pin
+        // (handled above) is the deterministic way out.
+        deps.logger.warn(`the ${activeDescriptor.label} console's tunnel origin could not be read `
+            + `(${read.error ?? 'no reason reported'}); this runtime will serve the default tunnel entry `
+            + 'instead, and the tunnel provider will report its own failure. '
+            + 'Pin XPOD_GATEWAY_INGRESS_PORT to decide the entry explicitly');
+    }
+    const port = await deps.findDefaultPort(request.mainPort);
+    deps.logger.info(`Tunnel entry ${port} chosen from the gateway port ${request.mainPort} (gateway+3..+9, first free port)`);
+    return { port, source: 'gateway-default', inactiveDeclarations };
+}
+/** A strict port is taken as-is or not at all; the occupant is named, never signalled. */
+async function requireFree(port, label, deps) {
+    if (await deps.isFree(port)) {
+        return;
+    }
+    const occupant = deps.identifyOccupants(port);
+    throw new IngressPortConflictError(port, occupant);
+}
+async function readInactiveConsoleDeclarations(input) {
+    const declarations = [];
+    for (const profile of input.profiles) {
+        if (profile.id === input.active?.id) {
+            continue;
+        }
+        if ((0, TunnelProviderCatalog_1.tunnelProviderDescriptor)(profile.provider)?.originOwner !== 'console') {
+            continue;
+        }
+        const read = await input.deps.readDeclaredOrigin(profile, { env: input.env, active: false });
+        if (read.origin) {
+            declarations.push({
+                profileId: profile.id,
+                provider: profile.provider,
+                port: read.origin.port,
+                readBack: read.origin.readBack,
+                ...(read.origin.scheme ? { scheme: read.origin.scheme } : {}),
+            });
+        }
+    }
+    return declarations;
+}
+//# sourceMappingURL=ingress-port.js.map

package/dist/runtime/js-runtime.js

@@ -19,8 +19,15 @@ function findBunExecutable() {
     return result.status === 0 ? result.stdout.trim() || undefined : undefined;
 }
 function jsEntrypointArgs(entrypoint, isBun) {
-    return !isBun && entrypoint.endsWith('.ts')
-        ? ['-r', require.resolve('ts-node/register/transpile-only'), entrypoint]
-        : [entrypoint];
+    if (!isBun) {
+        return entrypoint.endsWith('.ts')
+            ? ['-r', require.resolve('ts-node/register/transpile-only'), entrypoint]
+            : [entrypoint];
+    }
+    // A child service runs on the environment its parent decided for it. Without this, Bun loads
+    // whichever .env files happen to sit in the child's cwd, so a checkout's developer env files
+    // leak into a runtime that was started standalone (`bun run local` already loads them once, for
+    // the parent, on purpose).
+    return ['--no-env-file', entrypoint];
 }
 //# sourceMappingURL=js-runtime.js.map

package/dist/runtime/lifecycle.js

@@ -7,6 +7,7 @@ exports.startApiRuntime = startApiRuntime;
 exports.startGatewayRuntime = startGatewayRuntime;
 exports.stopRuntimeServices = stopRuntimeServices;
 const package_root_1 = require("./package-root");
+const bootstrap_1 = require("./bootstrap");
 const RedisClientLifecycle_1 = require("../storage/redis/RedisClientLifecycle");
 const DEFAULT_SERVICE_STOP_TIMEOUT_MS = 5_000;
 async function stopWithTimeout(name, stop, timeoutMs) {
@@ -80,7 +81,7 @@ async function startCssRuntime({ state, host, runtimeShorthand, supervisor, crea
     }
     else {
         await host.waitForPortReady(state.ports.css, '127.0.0.1');
-        supervisor.addLog('css', 'info', `CSS started (http://127.0.0.1:${state.ports.css})`);
+        supervisor.addLog('css', 'info', `CSS started (${(0, bootstrap_1.localServiceUrl)(state.bindHost, state.ports.css)})`);
     }
     supervisor.setStatus('css', 'running', { startTime: Date.now() });
     return cssApp;
@@ -92,7 +93,7 @@ async function startApiRuntime({ state, host, supervisor, authContext, apiRunner
         authContext: createOpenAuthContext(state.canonicalBaseUrl ?? state.baseUrl, authContext),
         runtimeHost: host,
     });
-    supervisor.addLog('api', 'info', `API started (${state.transport === 'socket' ? `unix://${state.sockets.api}` : `http://127.0.0.1:${state.ports.api}`})`);
+    supervisor.addLog('api', 'info', `API started (${state.transport === 'socket' ? `unix://${state.sockets.api}` : (0, bootstrap_1.localServiceUrl)(state.bindHost, state.ports.api)})`);
     supervisor.setStatus('api', 'running', { startTime: Date.now() });
     return apiService;
 }
@@ -110,8 +111,8 @@ async function startGatewayRuntime({ state, host, supervisor, shutdownHandler, g
         clientRemoteAddressResolver,
         ingressPort: state.ports.ingress,
         targets: {
-            css: state.transport === 'socket' ? { socketPath: state.sockets.css } : { url: `http://127.0.0.1:${state.ports.css}` },
-            api: state.transport === 'socket' ? { socketPath: state.sockets.api } : { url: `http://127.0.0.1:${state.ports.api}` },
+            css: state.transport === 'socket' ? { socketPath: state.sockets.css } : { url: (0, bootstrap_1.localServiceUrl)(state.bindHost, state.ports.css) },
+            api: state.transport === 'socket' ? { socketPath: state.sockets.api } : { url: (0, bootstrap_1.localServiceUrl)(state.bindHost, state.ports.api) },
         },
     });
     supervisor.addLog('xpod', 'info', `Gateway started (${state.transport === 'socket' ? `unix://${state.sockets.gateway}` : state.baseUrl})`);

package/dist/runtime/oidc-issuer.d.ts

@@ -11,4 +11,13 @@ export declare const DEFAULT_LOCAL_OIDC_ISSUER = "https://id.undefineds.co/";
  */
 export declare function resolveExternalOidcIssuer(env: RuntimeEnv): string | undefined;
 export declare function oidcTokenEndpoint(issuer: string): string;
+/**
+ * Whether an issuer only this machine could serve.
+ *
+ * An explicit `SOLID_OIDC_ISSUER` may be loopback on purpose (a developer running their own IdP
+ * next to the runtime). A *remembered* issuer is different: nothing in this process serves it, so
+ * a loopback value there can only be residue from an older run - and adopting it sends every
+ * login to a port with no listener.
+ */
+export declare function isLoopbackIssuer(issuer: string | undefined): boolean;
 export declare function cloudApiEndpointFromIssuer(issuer: string): string;

package/dist/runtime/oidc-issuer.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_LOCAL_OIDC_ISSUER = exports.OIDC_ISSUER_ENV_KEYS = void 0;
 exports.resolveExternalOidcIssuer = resolveExternalOidcIssuer;
 exports.oidcTokenEndpoint = oidcTokenEndpoint;
+exports.isLoopbackIssuer = isLoopbackIssuer;
 exports.cloudApiEndpointFromIssuer = cloudApiEndpointFromIssuer;
 exports.OIDC_ISSUER_ENV_KEYS = [
     'SOLID_OIDC_ISSUER',
@@ -32,6 +33,28 @@ function resolveExternalOidcIssuer(env) {
 function oidcTokenEndpoint(issuer) {
     return `${issuer.replace(/\/+$/u, '')}/.oidc/token`;
 }
+/**
+ * Whether an issuer only this machine could serve.
+ *
+ * An explicit `SOLID_OIDC_ISSUER` may be loopback on purpose (a developer running their own IdP
+ * next to the runtime). A *remembered* issuer is different: nothing in this process serves it, so
+ * a loopback value there can only be residue from an older run - and adopting it sends every
+ * login to a port with no listener.
+ */
+function isLoopbackIssuer(issuer) {
+    const value = issuer?.trim();
+    if (!value) {
+        return false;
+    }
+    try {
+        const host = new URL(value).hostname.toLowerCase().replace(/^\[|\]$/gu, '');
+        // A literal in 127.0.0.0/8, not any host that merely starts with "127.".
+        return host === 'localhost' || host === '::1' || /^127(?:\.\d{1,3}){3}$/u.test(host);
+    }
+    catch {
+        return false;
+    }
+}
 function cloudApiEndpointFromIssuer(issuer) {
     const identity = new URL(issuer);
     return identity.origin === 'https://id.undefineds.co'

package/dist/runtime/port-finder.d.ts

@@ -1,3 +1,24 @@
+/**
+ * The port a remote tunnel forwards to: the Gateway's tunnel entry.
+ *
+ * It sits a few ports above the Gateway so it is predictable - the user copies this one number
+ * into a provider console and it survives restarts - while staying clear of the block a
+ * neighbouring runtime plans for its own services. When the neighbourhood is busy the caller
+ * gets an OS-assigned port instead of a stolen one; the runtime reports whichever it got.
+ *
+ * Reserved ports are skipped here too: a group that needs a fixed port has published a
+ * reservation, and a dynamic entry that took it would break that group's tunnel instead of
+ * merely moving its own listener.
+ */
+export declare function findGatewayIngressPort(gatewayPort: number): Promise<number>;
+/**
+ * The first free port at or above `basePort`.
+ *
+ * Reserved ports are skipped, not merely avoided by convention: a group that needs a fixed port
+ * (the tunnel acceptance's console-owned 5737) publishes a reservation, and every allocator -
+ * the runtime, the test helpers, the integration runners - goes around it instead of racing for
+ * it. That is the difference between "usually fine" and "cannot collide".
+ */
 export declare function getFreePort(basePort: number, host?: string, timeoutMs?: number): Promise<number>;
 /**
  * Loopback port handed out by the OS for a listener that must not collide with ports the
@@ -10,23 +31,16 @@ export declare function getFreePort(basePort: number, host?: string, timeoutMs?:
  */
 export declare function getEphemeralLoopbackPort(): Promise<number>;
 /**
- * The ingress port this deployment should keep using.
+ * Whether this runtime could take the port as-is, on both address families.
  *
- * Remote tunnels forward to a port the operator typed into a provider console, so an
- * OS-assigned port would invalidate that copy on every restart. The port is remembered in
- * the runtime state directory; if something else took it meanwhile, a new one is chosen and
- * persisted — the caller reports the change so the stale console value can be corrected.
- */
-export declare function resolveStableLoopbackPort(stateFile: string): Promise<{
-    port: number;
-    changed: boolean;
-}>;
-export declare function readPortFile(stateFile: string): number | undefined;
-/**
- * Allocates a port for child services that bind wildcard addresses.
- * CSS may bind `::` while the API binds `0.0.0.0`, so probing only localhost
- * can miss an occupied port on the other address family.
+ * A tunnel origin is bound on the wildcard address, so a listener on `*:<port>` owns the
+ * number even when IPv4 loopback alone still looks free.
+ *
+ * This is a probe, not an allocation: it answers about the socket, so a *reserved* port that is
+ * genuinely free answers `true` (the group that reserved it still has to bind it). The
+ * `getFreePort*` family is the allocating one, and it skips reserved ports.
  */
+export declare function isFreePortForWildcard(port: number, timeoutMs?: number): Promise<boolean>;
 /**
  * Takes exactly this port or fails.
  *
@@ -34,4 +48,10 @@ export declare function readPortFile(stateFile: string): number | undefined;
  * scans upward, which would leave the runtime listening somewhere the tunnel never reaches.
  */
 export declare function requireFreePortForWildcard(port: number, timeoutMs?: number): Promise<number>;
+/**
+ * Allocates a port for child services that bind wildcard addresses.
+ *
+ * CSS may bind `::` while the API binds `0.0.0.0`, so probing only localhost can miss an
+ * occupied port on the other address family - and a reserved port is skipped either way.
+ */
 export declare function getFreePortForWildcard(basePort: number, timeoutMs?: number): Promise<number>;

package/dist/runtime/port-finder.js

@@ -3,16 +3,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.findGatewayIngressPort = findGatewayIngressPort;
 exports.getFreePort = getFreePort;
 exports.getEphemeralLoopbackPort = getEphemeralLoopbackPort;
-exports.resolveStableLoopbackPort = resolveStableLoopbackPort;
-exports.readPortFile = readPortFile;
+exports.isFreePortForWildcard = isFreePortForWildcard;
 exports.requireFreePortForWildcard = requireFreePortForWildcard;
 exports.getFreePortForWildcard = getFreePortForWildcard;
 const node_net_1 = __importDefault(require("node:net"));
 const node_os_1 = __importDefault(require("node:os"));
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
+const port_reservations_1 = require("./port-reservations");
 const HIGHEST_PORT = 65_535;
 const PORT_PROBE_TIMEOUT_MS = 1_000;
 const RETRYABLE_PORT_ERRORS = new Set([
@@ -103,8 +102,41 @@ async function canListen(port, host, timeoutMs = PORT_PROBE_TIMEOUT_MS) {
         server.listen(port, host);
     });
 }
+/**
+ * The port a remote tunnel forwards to: the Gateway's tunnel entry.
+ *
+ * It sits a few ports above the Gateway so it is predictable - the user copies this one number
+ * into a provider console and it survives restarts - while staying clear of the block a
+ * neighbouring runtime plans for its own services. When the neighbourhood is busy the caller
+ * gets an OS-assigned port instead of a stolen one; the runtime reports whichever it got.
+ *
+ * Reserved ports are skipped here too: a group that needs a fixed port has published a
+ * reservation, and a dynamic entry that took it would break that group's tunnel instead of
+ * merely moving its own listener.
+ */
+async function findGatewayIngressPort(gatewayPort) {
+    for (let offset = 3; offset < 10; offset += 1) {
+        const candidate = gatewayPort + offset;
+        if (await getFreePortForWildcard(candidate) === candidate) {
+            return candidate;
+        }
+    }
+    return await getEphemeralLoopbackPort();
+}
+/**
+ * The first free port at or above `basePort`.
+ *
+ * Reserved ports are skipped, not merely avoided by convention: a group that needs a fixed port
+ * (the tunnel acceptance's console-owned 5737) publishes a reservation, and every allocator -
+ * the runtime, the test helpers, the integration runners - goes around it instead of racing for
+ * it. That is the difference between "usually fine" and "cannot collide".
+ */
 async function getFreePort(basePort, host = '127.0.0.1', timeoutMs = PORT_PROBE_TIMEOUT_MS) {
+    const reserved = (0, port_reservations_1.reservedPorts)();
     for (let port = basePort; port <= HIGHEST_PORT; port++) {
+        if (reserved.has(port)) {
+            continue;
+        }
         if (await canListen(port, host, timeoutMs)) {
             return port;
         }
@@ -121,63 +153,35 @@ async function getFreePort(basePort, host = '127.0.0.1', timeoutMs = PORT_PROBE_
  * runtime's service.
  */
 async function getEphemeralLoopbackPort() {
-    return await new Promise((resolve, reject) => {
-        const server = node_net_1.default.createServer();
-        server.once('error', reject);
-        server.listen(0, '127.0.0.1', () => {
-            const address = server.address();
-            const port = typeof address === 'object' && address ? address.port : 0;
-            server.close((error) => {
-                if (error) {
-                    reject(error);
-                    return;
-                }
-                resolve(port);
-            });
-        });
-    });
+    // One retry rule for "the OS does not know about reservations", shared with the fixtures that
+    // bind their own server (`listenOnUnreservedPort`).
+    return await (0, port_reservations_1.getUnreservedEphemeralPort)('127.0.0.1');
+}
+function hasIpv6Address() {
+    return Object.values(node_os_1.default.networkInterfaces()).some((entries) => entries?.some((entry) => entry.family === 'IPv6'));
 }
 /**
- * The ingress port this deployment should keep using.
+ * Whether this runtime could take the port as-is, on both address families.
  *
- * Remote tunnels forward to a port the operator typed into a provider console, so an
- * OS-assigned port would invalidate that copy on every restart. The port is remembered in
- * the runtime state directory; if something else took it meanwhile, a new one is chosen and
- * persisted — the caller reports the change so the stale console value can be corrected.
+ * A tunnel origin is bound on the wildcard address, so a listener on `*:<port>` owns the
+ * number even when IPv4 loopback alone still looks free.
+ *
+ * This is a probe, not an allocation: it answers about the socket, so a *reserved* port that is
+ * genuinely free answers `true` (the group that reserved it still has to bind it). The
+ * `getFreePort*` family is the allocating one, and it skips reserved ports.
  */
-async function resolveStableLoopbackPort(stateFile) {
-    const remembered = readPortFile(stateFile);
-    if (remembered !== undefined && await canListen(remembered, '127.0.0.1')) {
-        return { port: remembered, changed: false };
-    }
-    const port = await getEphemeralLoopbackPort();
-    try {
-        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(stateFile), { recursive: true });
-        (0, node_fs_1.writeFileSync)(stateFile, `${port}\n`);
-    }
-    catch {
-        // A deployment without a writable state directory still gets a working port; it just
-        // cannot promise the same one next time.
+async function isFreePortForWildcard(port, timeoutMs = PORT_PROBE_TIMEOUT_MS) {
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        return false;
     }
-    return { port, changed: remembered !== undefined };
-}
-function readPortFile(stateFile) {
-    try {
-        const port = Number.parseInt((0, node_fs_1.readFileSync)(stateFile, 'utf8').trim(), 10);
-        return Number.isInteger(port) && port > 0 && port <= 65535 ? port : undefined;
+    if (!await canListen(port, '0.0.0.0', timeoutMs)) {
+        return false;
     }
-    catch {
-        return undefined;
+    if (hasIpv6Address() && !await canListen(port, '::', timeoutMs)) {
+        return false;
     }
+    return true;
 }
-function hasIpv6Address() {
-    return Object.values(node_os_1.default.networkInterfaces()).some((entries) => entries?.some((entry) => entry.family === 'IPv6'));
-}
-/**
- * Allocates a port for child services that bind wildcard addresses.
- * CSS may bind `::` while the API binds `0.0.0.0`, so probing only localhost
- * can miss an occupied port on the other address family.
- */
 /**
  * Takes exactly this port or fails.
  *
@@ -188,17 +192,24 @@ async function requireFreePortForWildcard(port, timeoutMs = PORT_PROBE_TIMEOUT_M
     if (!Number.isInteger(port) || port <= 0 || port > 65535) {
         throw new Error(`ingress port ${port} is not a valid port number`);
     }
-    if (!await canListen(port, '0.0.0.0', timeoutMs)) {
+    if (!await isFreePortForWildcard(port, timeoutMs)) {
         throw new Error(`ingress port ${port} is already in use; free it or point the tunnel at another port`);
     }
-    if (hasIpv6Address() && !await canListen(port, '::', timeoutMs)) {
-        throw new Error(`ingress port ${port} is already in use on IPv6; free it or point the tunnel at another port`);
-    }
     return port;
 }
+/**
+ * Allocates a port for child services that bind wildcard addresses.
+ *
+ * CSS may bind `::` while the API binds `0.0.0.0`, so probing only localhost can miss an
+ * occupied port on the other address family - and a reserved port is skipped either way.
+ */
 async function getFreePortForWildcard(basePort, timeoutMs = PORT_PROBE_TIMEOUT_MS) {
     const probeIpv6 = hasIpv6Address();
+    const reserved = (0, port_reservations_1.reservedPorts)();
     for (let port = basePort; port <= HIGHEST_PORT; port++) {
+        if (reserved.has(port)) {
+            continue;
+        }
         if (!await canListen(port, '0.0.0.0', timeoutMs)) {
             continue;
         }

package/dist/runtime/port-reservations.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Port reservations: one small mechanism that keeps every *other* group off the fixed ports a
+ * group needs.
+ *
+ * The tunnel acceptance has two legs whose origin port is not ours to choose — the Cloudflare
+ * Dashboard's local service port and the SakuraFrp console's `local_port`, both 5737 on the
+ * operator's machine. Those are fixed parameters, so the group that needs them publishes a
+ * reservation, and every port *allocator* in the repo skips reserved ports:
+ *
+ * - allocation helpers in `src/runtime/port-finder.ts` (which is what the runtime, the test
+ *   helpers, `run-integration-full`/`run-integration-lite` and the acceptance harness use);
+ * - the harness's own free-port helpers.
+ *
+ * Two sources, both optional and both additive:
+ * - the `XPOD_RESERVED_PORTS` env var (`"5737,4599"`), for a run that knows its fixed ports;
+ * - one JSON file per reservation under `.test-data/port-reservations/`, for a group that
+ *   holds a port for the duration of a run.
+ *
+ * A reservation is a *claim about the future*, not a lock: it is never enforced against a
+ * process that ignores it. That is deliberate — the network group fails loudly naming whoever
+ * holds its port, and nothing in this repo signals a process it does not own.
+ *
+ * Reservations expire (12h by default) so a crashed run cannot block a port forever.
+ */
+export declare const RESERVED_PORTS_ENV = "XPOD_RESERVED_PORTS";
+export declare const PORT_RESERVATION_DIR_ENV = "XPOD_PORT_RESERVATION_DIR";
+export interface PortReservation {
+    port: number;
+    /** Who holds it: a run id, a harness name, an operator. */
+    owner: string;
+    /** Which group needs the fixed port (`network` for the tunnel acceptance). */
+    group: string;
+    /** ISO timestamp the reservation was written. */
+    reservedAt: string;
+    /** Why this port is fixed, so the next person does not have to guess. */
+    note?: string;
+    /** Where the reservation came from, so a log line can name the source. */
+    source?: 'file' | 'env';
+}
+export declare function portReservationDir(root?: string): string;
+export declare function portReservationFile(port: number, root?: string): string;
+/** Publishes a reservation (idempotent for the same owner and port). */
+export declare function reservePort(reservation: Omit<PortReservation, 'reservedAt'> & {
+    reservedAt?: string;
+}, root?: string): PortReservation;
+/** Removes a reservation this owner wrote; another owner's reservation is left alone. */
+export declare function releasePort(port: number, owner: string, root?: string): boolean;
+export declare function parseReservedPortsEnv(value: string | undefined): number[];
+/** Every reservation in force right now: env var plus unexpired files. */
+export declare function readPortReservations(options?: {
+    env?: Record<string, string | undefined>;
+    root?: string;
+    now?: number;
+    ttlMs?: number;
+}): PortReservation[];
+/** The set every allocator skips. Cheap enough to call once per allocation. */
+export declare function reservedPorts(options?: {
+    env?: Record<string, string | undefined>;
+    root?: string;
+    now?: number;
+}): Set<number>;
+/** The reservation covering a port, when there is one: what a failure message should name. */
+export declare function portReservation(port: number, options?: {
+    env?: Record<string, string | undefined>;
+    root?: string;
+    now?: number;
+}): PortReservation | undefined;
+/** The slice of `net.Server`/`http.Server` this needs, so both can be passed in. */
+export interface ReservingListenable {
+    listen(port: number, host: string, callback: () => void): unknown;
+    address(): {
+        port: number;
+    } | string | null;
+    close(callback?: (error?: Error) => void): unknown;
+    once(event: 'error', listener: (error: Error) => void): unknown;
+}
+/**
+ * Binds a server to an OS-assigned port that is not reserved.
+ *
+ * `listen(0)` hands out whatever the kernel likes, reservations included. Fixtures that bind
+ * their own server therefore come through here: one retry loop, one rule, and a reserved port is
+ * never taken even by accident.
+ */
+export declare function listenOnUnreservedPort(server: ReservingListenable, host?: string, attempts?: number): Promise<number>;
+/** An unreserved OS-assigned port, released again so the caller can bind it itself. */
+export declare function getUnreservedEphemeralPort(host?: string, attempts?: number): Promise<number>;