@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.04a1e5b9e484

package/dist/runtime/host-listener-inspector.js

@@ -0,0 +1,385 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const windowsListenerOwnerPath = fileURLToPath(new URL("../../runtime/windows-listener-owner.ps1", import.meta.url));
+const windowsNetstatArgs = ["-ano", "-p", "TCP"];
+const windowsNetstatAttempts = 3;
+const windowsAncestryAttempts = 2;
+const windowsNetstatRetryDelayMs = 250;
+const inspectionCommandTimeoutMs = 15_000;
+/** Proves that a loopback listener belongs to one exact supervised child. */
+export class HostListenerInspector {
+    commands;
+    platform;
+    retryDelayMs;
+    constructor(commands = new ExecFileInspectionCommandRunner(), platform = process.platform, retryDelayMs = windowsNetstatRetryDelayMs) {
+        this.commands = commands;
+        this.platform = platform;
+        this.retryDelayMs = retryDelayMs;
+    }
+    async inspect(child, reservation, owner) {
+        if (reservation.hostIp !== "127.0.0.1" || reservation.protocol !== "tcp") {
+            throw new Error("host_listener_inspection_invalid: only TCP IPv4 loopback listeners are supported.");
+        }
+        const metadata = await loadMetadata(child.metadataPath);
+        if (!metadata)
+            return "unbound";
+        if (!matchesOwner(metadata, child, owner))
+            return "foreign";
+        if (this.platform === "win32") {
+            return await this.inspectWindows(metadata.rootPid, reservation.hostPort);
+        }
+        return await this.inspectUnix(metadata.rootPid, reservation.hostPort);
+    }
+    /** Returns loopback TCP ports opened by one exact supervised child process tree. */
+    async inspectOwnedLoopbackListeners(child, owner) {
+        const metadata = await loadMetadata(child.metadataPath);
+        if (!metadata || !matchesOwner(metadata, child, owner)) {
+            throw new Error("host_listener_inspection_invalid: supervised provider ownership metadata is unavailable.");
+        }
+        return this.platform === "win32"
+            ? await this.inspectAllWindows(metadata.rootPid)
+            : await this.inspectAllUnix(metadata.rootPid);
+    }
+    /** Snapshots loopback TCP ports that predate a supervised child launch. */
+    async inspectLoopbackListeners() {
+        if (this.platform === "win32") {
+            const netstat = await this.runWindowsNetstat();
+            return uniqueSorted(parseWindowsLoopbackListeners(netstat.stdout).map(listener => listener.port));
+        }
+        const lsof = await this.commands.run("lsof", [
+            "-nP",
+            "-a",
+            "-iTCP@127.0.0.1",
+            "-sTCP:LISTEN",
+            "-Fpn",
+        ]);
+        if (lsof.exitCode === 0 || lsof.exitCode === 1) {
+            return uniqueSorted(parseLsofLoopbackListeners(lsof.stdout).map(listener => listener.port));
+        }
+        if (lsof.errorCode !== "ENOENT")
+            throw commandError("lsof", lsof);
+        const ss = await this.commands.run("ss", ["-H", "-ltnp"]);
+        if (ss.exitCode !== 0)
+            throw commandError("ss", ss);
+        return uniqueSorted(parseSsLoopbackListeners(ss.stdout).map(listener => listener.port));
+    }
+    async inspectWindows(rootPid, port) {
+        const netstat = await this.runWindowsNetstat();
+        const listenerPids = parseWindowsListenerPids(netstat.stdout, port);
+        if (listenerPids.length === 0)
+            return "unbound";
+        const values = await this.runWindowsAncestry(rootPid, listenerPids);
+        return values.every(value => value) ? "owned" : "foreign";
+    }
+    async inspectAllWindows(rootPid) {
+        const netstat = await this.runWindowsNetstat();
+        const listeners = parseWindowsLoopbackListeners(netstat.stdout);
+        if (listeners.length === 0)
+            return [];
+        const pids = [...new Set(listeners.map(listener => listener.pid))];
+        const values = await this.runWindowsAncestry(rootPid, pids);
+        const ownedPids = new Set(pids.filter((_pid, index) => values[index] === true));
+        return uniqueSorted(listeners.filter(listener => ownedPids.has(listener.pid)).map(listener => listener.port));
+    }
+    async runWindowsAncestry(rootPid, listenerPids) {
+        let lastResult = null;
+        let lastParseError;
+        for (let attempt = 1; attempt <= windowsAncestryAttempts; attempt += 1) {
+            const result = await this.commands.run(windowsPowerShellPath(), [
+                "-NoLogo",
+                "-NoProfile",
+                "-NonInteractive",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                windowsListenerOwnerPath,
+                "-RootProcessId",
+                String(rootPid),
+                "-ListenerProcessIds",
+                listenerPids.join(","),
+            ]);
+            lastResult = result;
+            if (result.exitCode !== 0) {
+                if (!isTransientWindowsInspectionFailure(result) || attempt === windowsAncestryAttempts) {
+                    throw commandError("Windows process ancestry", result);
+                }
+            }
+            else {
+                try {
+                    const parsed = JSON.parse(result.stdout.trim());
+                    const values = Array.isArray(parsed) ? parsed : [parsed];
+                    if (values.length !== listenerPids.length || values.some(value => typeof value !== "boolean")) {
+                        throw new Error("Windows ancestry output was incomplete.");
+                    }
+                    return values;
+                }
+                catch (error) {
+                    lastParseError = error;
+                    if (attempt === windowsAncestryAttempts) {
+                        throw new Error(`host_diagnostics_temporary_unavailable: Windows process ancestry returned invalid output after ${attempt} attempts.`, { cause: error });
+                    }
+                }
+            }
+            await wait(this.retryDelayMs);
+        }
+        if (lastResult)
+            throw commandError("Windows process ancestry", lastResult);
+        throw new Error("host_diagnostics_temporary_unavailable: Windows process ancestry produced no result.", {
+            cause: lastParseError,
+        });
+    }
+    async runWindowsNetstat() {
+        let lastResult = null;
+        for (let attempt = 1; attempt <= windowsNetstatAttempts; attempt += 1) {
+            const result = await this.commands.run("netstat.exe", windowsNetstatArgs);
+            if (result.exitCode === 0)
+                return result;
+            lastResult = result;
+            if (!isTransientWindowsNetstatFailure(result) || attempt === windowsNetstatAttempts)
+                break;
+            await wait(this.retryDelayMs);
+        }
+        throw commandError("netstat", lastResult);
+    }
+    async inspectUnix(rootPid, port) {
+        let listenerPids = null;
+        const lsof = await this.commands.run("lsof", [
+            "-nP",
+            "-a",
+            `-iTCP@127.0.0.1:${port}`,
+            "-sTCP:LISTEN",
+            "-Fp",
+        ]);
+        if (lsof.exitCode === 0 || lsof.exitCode === 1) {
+            listenerPids = parseLsofPids(lsof.stdout);
+        }
+        else if (lsof.errorCode !== "ENOENT") {
+            throw commandError("lsof", lsof);
+        }
+        if (listenerPids === null) {
+            const ss = await this.commands.run("ss", ["-H", "-ltnp", "sport", "=", `:${port}`]);
+            if (ss.exitCode !== 0)
+                throw commandError("ss", ss);
+            listenerPids = parseSsPids(ss.stdout, port);
+        }
+        if (listenerPids.length === 0)
+            return "unbound";
+        const processGroups = await this.commands.run("ps", [
+            "-o",
+            "pid=,pgid=",
+            "-p",
+            listenerPids.join(","),
+        ]);
+        if (processGroups.exitCode !== 0)
+            throw commandError("ps", processGroups);
+        const groups = parseProcessGroups(processGroups.stdout);
+        return listenerPids.every(pid => groups.get(pid) === rootPid) ? "owned" : "foreign";
+    }
+    async inspectAllUnix(rootPid) {
+        const lsof = await this.commands.run("lsof", [
+            "-nP",
+            "-a",
+            "-iTCP@127.0.0.1",
+            "-sTCP:LISTEN",
+            "-Fpn",
+        ]);
+        let listeners;
+        if (lsof.exitCode === 0 || lsof.exitCode === 1) {
+            listeners = parseLsofLoopbackListeners(lsof.stdout);
+        }
+        else if (lsof.errorCode === "ENOENT") {
+            const ss = await this.commands.run("ss", ["-H", "-ltnp"]);
+            if (ss.exitCode !== 0)
+                throw commandError("ss", ss);
+            listeners = parseSsLoopbackListeners(ss.stdout);
+        }
+        else {
+            throw commandError("lsof", lsof);
+        }
+        if (listeners.length === 0)
+            return [];
+        const pids = [...new Set(listeners.map(listener => listener.pid))];
+        const processGroups = await this.commands.run("ps", ["-o", "pid=,pgid=", "-p", pids.join(",")]);
+        if (processGroups.exitCode !== 0)
+            throw commandError("ps", processGroups);
+        const groups = parseProcessGroups(processGroups.stdout);
+        return uniqueSorted(listeners
+            .filter(listener => groups.get(listener.pid) === rootPid)
+            .map(listener => listener.port));
+    }
+}
+export function parseWindowsLoopbackListeners(output) {
+    return uniqueListeners(output.split(/\r?\n/u).flatMap(line => {
+        const fields = line.trim().split(/\s+/u);
+        if (fields.length < 5 || fields[0]?.toUpperCase() !== "TCP" || fields[3]?.toUpperCase() !== "LISTENING")
+            return [];
+        const endpoint = parseIpv4LoopbackEndpoint(fields[1]);
+        const pids = validPid(fields[4]);
+        return endpoint && pids.length === 1 ? [{ pid: pids[0], port: endpoint }] : [];
+    }));
+}
+export function parseLsofLoopbackListeners(output) {
+    const listeners = [];
+    let pid = null;
+    for (const line of output.split(/\r?\n/u)) {
+        if (line.startsWith("p"))
+            pid = validPid(line.slice(1))[0] ?? null;
+        if (!line.startsWith("n") || pid === null)
+            continue;
+        const port = parseIpv4LoopbackEndpoint(line.slice(1));
+        if (port !== null)
+            listeners.push({ pid, port });
+    }
+    return uniqueListeners(listeners);
+}
+export function parseSsLoopbackListeners(output) {
+    return uniqueListeners(output.split(/\r?\n/u).flatMap(line => {
+        const endpoint = line.match(/127\.0\.0\.1:(\d+)/u)?.[1];
+        const port = endpoint ? Number.parseInt(endpoint, 10) : 0;
+        if (!Number.isSafeInteger(port) || port < 1 || port > 65535)
+            return [];
+        return [...line.matchAll(/pid=(\d+)/gu)].flatMap(match => {
+            const pid = validPid(match[1])[0];
+            return pid ? [{ pid, port }] : [];
+        });
+    }));
+}
+export class ExecFileInspectionCommandRunner {
+    run(command, args) {
+        return new Promise(resolve => {
+            const executable = process.platform === "win32" && command.toLowerCase() === "netstat.exe"
+                ? windowsSystemExecutable("netstat.exe")
+                : command;
+            execFile(executable, args, {
+                windowsHide: true,
+                timeout: inspectionCommandTimeoutMs,
+                maxBuffer: 4 * 1024 * 1024,
+            }, (error, stdout, stderr) => {
+                const processError = error;
+                const timedOut = Boolean(processError?.killed && processError.signal === "SIGTERM" && processError.code == null);
+                resolve({
+                    exitCode: typeof processError?.code === "number" ? processError.code : error ? 1 : 0,
+                    stdout: String(stdout),
+                    stderr: String(stderr),
+                    ...(typeof processError?.code === "string" ? { errorCode: processError.code } : {}),
+                    ...(timedOut ? { timedOut: true } : {}),
+                    ...(processError?.signal ? { signal: processError.signal } : {}),
+                });
+            });
+        });
+    }
+}
+export function parseWindowsListenerPids(output, port) {
+    const suffix = `:${port}`;
+    const pids = output.split(/\r?\n/u).flatMap(line => {
+        const fields = line.trim().split(/\s+/u);
+        if (fields.length < 5 || fields[0]?.toUpperCase() !== "TCP" || fields[3]?.toUpperCase() !== "LISTENING")
+            return [];
+        if (fields[1] !== `127.0.0.1${suffix}`)
+            return [];
+        return validPid(fields[4]);
+    });
+    return uniqueSorted(pids);
+}
+export function parseLsofPids(output) {
+    return uniqueSorted(output.split(/\r?\n/u).flatMap(line => line.startsWith("p") ? validPid(line.slice(1)) : []));
+}
+export function parseSsPids(output, port) {
+    return uniqueSorted(output.split(/\r?\n/u).flatMap(line => {
+        if (!line.includes(`127.0.0.1:${port}`))
+            return [];
+        return [...line.matchAll(/pid=(\d+)/gu)].flatMap(match => validPid(match[1]));
+    }));
+}
+export function parseProcessGroups(output) {
+    const groups = new Map();
+    for (const line of output.split(/\r?\n/u)) {
+        const fields = line.trim().split(/\s+/u);
+        const pid = validPid(fields[0]);
+        const group = validPid(fields[1]);
+        if (pid.length === 1 && group.length === 1)
+            groups.set(pid[0], group[0]);
+    }
+    return groups;
+}
+async function loadMetadata(metadataPath) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(metadataPath, "utf8"));
+        if (parsed.schemaVersion !== 1 || !Number.isSafeInteger(parsed.rootPid) || parsed.rootPid <= 0) {
+            throw new Error("host_listener_inspection_invalid: process supervisor metadata is invalid.");
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function matchesOwner(metadata, child, owner) {
+    return metadata.supervisorId === child.processSupervisorId
+        && metadata.runtimeLeaseId === owner.executionLeaseId
+        && metadata.dispatchAttemptId === owner.dispatchAttemptId
+        && metadata.fencingToken === owner.fencingToken;
+}
+function validPid(value) {
+    if (!value || !/^\d+$/u.test(value))
+        return [];
+    const pid = Number.parseInt(value, 10);
+    return Number.isSafeInteger(pid) && pid > 0 ? [pid] : [];
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left - right);
+}
+function parseIpv4LoopbackEndpoint(value) {
+    const match = value?.match(/^127\.0\.0\.1:(\d+)$/u);
+    if (!match)
+        return null;
+    const port = Number.parseInt(match[1], 10);
+    return Number.isSafeInteger(port) && port >= 1 && port <= 65535 ? port : null;
+}
+function uniqueListeners(values) {
+    const seen = new Set();
+    return values.filter(value => {
+        const key = `${value.pid}:${value.port}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    }).sort((left, right) => left.port - right.port || left.pid - right.pid);
+}
+function commandError(label, result) {
+    const detail = result.stderr.replaceAll(/[\r\n\t]+/gu, " ").trim().slice(0, 512);
+    const code = result.errorCode ? ` (${result.errorCode})` : "";
+    if (result.timedOut) {
+        return new Error(`host_diagnostics_temporary_unavailable: ${label} timed out after ${inspectionCommandTimeoutMs} ms${result.signal ? ` (${result.signal})` : ""}.`);
+    }
+    if (isTransientWindowsNetstatFailure(result)) {
+        return new Error(`host_diagnostics_temporary_unavailable: ${label} repeatedly exited ${result.exitCode} without diagnostics.`);
+    }
+    return new Error(`host_listener_inspection_failed: ${label} exited ${result.exitCode}${code}${detail ? `: ${detail}` : ""}.`);
+}
+function isTransientWindowsNetstatFailure(result) {
+    return isTransientWindowsInspectionFailure(result);
+}
+function isTransientWindowsInspectionFailure(result) {
+    return result.timedOut === true
+        || (result.exitCode === 1
+            && !result.errorCode
+            && !result.stdout.trim()
+            && !result.stderr.trim());
+}
+function wait(milliseconds) {
+    return milliseconds > 0
+        ? new Promise(resolve => setTimeout(resolve, milliseconds))
+        : Promise.resolve();
+}
+function windowsPowerShellPath() {
+    return path.win32.join(path.dirname(windowsSystemExecutable("netstat.exe")), "WindowsPowerShell", "v1.0", "powershell.exe");
+}
+function windowsSystemExecutable(name) {
+    const systemRoot = process.env.SystemRoot?.trim() || "C:\\Windows";
+    return path.win32.join(systemRoot, "System32", name);
+}

package/dist/runtime/host-port-broker.d.ts

@@ -0,0 +1,76 @@
+import type { RuntimeIsolationPort } from "./runtime-isolation-lease.js";
+export interface HostPortLeaseOwner {
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly fencingToken: string;
+    readonly processSupervisorId: string;
+}
+export interface HostPortRequest {
+    readonly name: string;
+    readonly protocol?: "tcp";
+    readonly targetPort?: number;
+}
+export type HostPortReservationState = "reserved" | "handed_off" | "active";
+export interface HostPortReservation extends RuntimeIsolationPort, HostPortLeaseOwner {
+    readonly schemaVersion: 1;
+    readonly reservationId: string;
+    readonly state: HostPortReservationState;
+    readonly reservedAt: string;
+    readonly handedOffAt: string | null;
+    readonly activatedAt: string | null;
+}
+export interface HostPortLaunchLifecycle<T> {
+    readonly launch: (port: HostPortReservation, signal?: AbortSignal) => Promise<T>;
+    readonly verifyOwnership: (value: T, port: HostPortReservation, signal?: AbortSignal) => Promise<boolean>;
+    readonly stop: (value: T) => Promise<void>;
+}
+export interface HostPortLaunch<T> {
+    readonly reservation: HostPortReservation;
+    readonly value: T;
+}
+export interface HostPortBrokerOptions {
+    readonly hostIp?: "127.0.0.1";
+    readonly minimumPort?: number;
+    readonly maximumPort?: number;
+    readonly maximumLaunchAttempts?: number;
+}
+export interface HostPortBrokerDiagnostics {
+    readonly hostIp: "127.0.0.1";
+    readonly pool: {
+        readonly minimumPort: number;
+        readonly maximumPort: number;
+    } | null;
+    readonly reservations: readonly Omit<HostPortReservation, "fencingToken">[];
+}
+export declare class HostPortCollisionError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Owns runner-local loopback ports for supervised host attempts.
+ *
+ * A reservation keeps a real listening socket open until an adapter is ready to
+ * launch. The adapter then performs a narrow handoff and must prove that the
+ * supervised child owns the assigned endpoint before the reservation is active.
+ */
+export declare class HostPortBroker {
+    private readonly hostIp;
+    private readonly minimumPort;
+    private readonly maximumPort;
+    private readonly maximumLaunchAttempts;
+    private readonly reservations;
+    private readonly claimedPorts;
+    private nextPort;
+    private launchGate;
+    constructor(options?: HostPortBrokerOptions);
+    reserve(owner: HostPortLeaseOwner, request: HostPortRequest, signal?: AbortSignal): Promise<HostPortReservation>;
+    handoff(reservationId: string, owner: HostPortLeaseOwner): Promise<HostPortReservation | null>;
+    activate(reservationId: string, owner: HostPortLeaseOwner): HostPortReservation | null;
+    release(reservationId: string, owner: HostPortLeaseOwner): Promise<boolean>;
+    snapshot(): readonly HostPortReservation[];
+    diagnostics(): HostPortBrokerDiagnostics;
+    launchWithRetry<T>(owner: HostPortLeaseOwner, request: HostPortRequest, lifecycle: HostPortLaunchLifecycle<T>, signal?: AbortSignal): Promise<HostPortLaunch<T>>;
+    private reserveExcluding;
+    private listen;
+    private owned;
+    private withLaunchGate;
+}