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

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

package/dist/runtime/host-port-broker.js

@@ -0,0 +1,333 @@
+import { randomUUID } from "node:crypto";
+import net from "node:net";
+export class HostPortCollisionError extends Error {
+    constructor(message = "host_port_collision: the launched process did not own its assigned loopback port.") {
+        super(message);
+        this.name = "HostPortCollisionError";
+    }
+}
+/**
+ * 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 class HostPortBroker {
+    hostIp;
+    minimumPort;
+    maximumPort;
+    maximumLaunchAttempts;
+    reservations = new Map();
+    claimedPorts = new Map();
+    nextPort;
+    launchGate = Promise.resolve();
+    constructor(options = {}) {
+        this.hostIp = options.hostIp ?? "127.0.0.1";
+        const hasMinimum = options.minimumPort !== undefined;
+        const hasMaximum = options.maximumPort !== undefined;
+        if (hasMinimum !== hasMaximum) {
+            throw new Error("host_port_broker_invalid: minimumPort and maximumPort must be configured together.");
+        }
+        this.minimumPort = hasMinimum ? validPort(options.minimumPort, "minimumPort") : null;
+        this.maximumPort = hasMaximum ? validPort(options.maximumPort, "maximumPort") : null;
+        if (this.minimumPort !== null && this.maximumPort !== null && this.minimumPort > this.maximumPort) {
+            throw new Error("host_port_broker_invalid: minimumPort cannot exceed maximumPort.");
+        }
+        this.maximumLaunchAttempts = options.maximumLaunchAttempts ?? 3;
+        if (!Number.isSafeInteger(this.maximumLaunchAttempts) || this.maximumLaunchAttempts < 1 || this.maximumLaunchAttempts > 10) {
+            throw new Error("host_port_broker_invalid: maximumLaunchAttempts must be between 1 and 10.");
+        }
+        this.nextPort = this.minimumPort;
+    }
+    async reserve(owner, request, signal) {
+        validateOwner(owner);
+        validateRequest(request);
+        if (signal?.aborted)
+            throw cancellationError(signal);
+        const { server, port } = await this.listen(signal, new Set());
+        const now = new Date().toISOString();
+        const reservation = {
+            schemaVersion: 1,
+            reservationId: randomUUID(),
+            ...owner,
+            name: request.name,
+            protocol: "tcp",
+            hostIp: this.hostIp,
+            hostPort: port,
+            targetPort: request.targetPort ?? port,
+            state: "reserved",
+            reservedAt: now,
+            handedOffAt: null,
+            activatedAt: null,
+        };
+        this.reservations.set(reservation.reservationId, { reservation, server });
+        this.claimedPorts.set(port, reservation.reservationId);
+        return reservation;
+    }
+    async handoff(reservationId, owner) {
+        const held = this.owned(reservationId, owner);
+        if (!held || held.reservation.state !== "reserved")
+            return null;
+        await closeServer(held.server);
+        held.server = null;
+        held.reservation = {
+            ...held.reservation,
+            state: "handed_off",
+            handedOffAt: new Date().toISOString(),
+        };
+        return held.reservation;
+    }
+    activate(reservationId, owner) {
+        const held = this.owned(reservationId, owner);
+        if (!held || held.reservation.state !== "handed_off")
+            return null;
+        held.reservation = {
+            ...held.reservation,
+            state: "active",
+            activatedAt: new Date().toISOString(),
+        };
+        return held.reservation;
+    }
+    async release(reservationId, owner) {
+        const held = this.owned(reservationId, owner);
+        if (!held)
+            return false;
+        await closeServer(held.server);
+        this.reservations.delete(reservationId);
+        if (this.claimedPorts.get(held.reservation.hostPort) === reservationId) {
+            this.claimedPorts.delete(held.reservation.hostPort);
+        }
+        return true;
+    }
+    snapshot() {
+        return [...this.reservations.values()]
+            .map(entry => entry.reservation)
+            .sort((left, right) => left.hostPort - right.hostPort);
+    }
+    diagnostics() {
+        return {
+            hostIp: this.hostIp,
+            pool: this.minimumPort === null || this.maximumPort === null
+                ? null
+                : { minimumPort: this.minimumPort, maximumPort: this.maximumPort },
+            reservations: this.snapshot().map(({ fencingToken: _fencingToken, ...reservation }) => reservation),
+        };
+    }
+    async launchWithRetry(owner, request, lifecycle, signal) {
+        const rejectedPorts = new Set();
+        let lastCollision = null;
+        for (let attempt = 1; attempt <= this.maximumLaunchAttempts; attempt += 1) {
+            if (signal?.aborted)
+                throw cancellationError(signal);
+            const reservation = await this.reserveExcluding(owner, request, rejectedPorts, signal);
+            try {
+                return await this.withLaunchGate(async () => {
+                    let value;
+                    try {
+                        if (signal?.aborted)
+                            throw cancellationError(signal);
+                        const handedOff = await this.handoff(reservation.reservationId, owner);
+                        if (!handedOff)
+                            throw new Error("host_port_broker_state: reservation handoff failed.");
+                        value = await lifecycle.launch(handedOff, signal);
+                        if (!await lifecycle.verifyOwnership(value, handedOff, signal)) {
+                            throw new HostPortCollisionError();
+                        }
+                        const active = this.activate(reservation.reservationId, owner);
+                        if (!active)
+                            throw new Error("host_port_broker_state: reservation activation failed.");
+                        return { reservation: active, value };
+                    }
+                    catch (error) {
+                        if (value !== undefined)
+                            await lifecycle.stop(value).catch(() => undefined);
+                        rejectedPorts.add(reservation.hostPort);
+                        await this.release(reservation.reservationId, owner);
+                        throw error;
+                    }
+                }, signal);
+            }
+            catch (error) {
+                if (this.reservations.has(reservation.reservationId)) {
+                    rejectedPorts.add(reservation.hostPort);
+                    await this.release(reservation.reservationId, owner);
+                }
+                if (!(error instanceof HostPortCollisionError))
+                    throw error;
+                lastCollision = error;
+            }
+        }
+        throw lastCollision ?? new HostPortCollisionError("host_port_collision: launch retry budget exhausted.");
+    }
+    async reserveExcluding(owner, request, excludedPorts, signal) {
+        validateOwner(owner);
+        validateRequest(request);
+        const { server, port } = await this.listen(signal, excludedPorts);
+        const now = new Date().toISOString();
+        const reservation = {
+            schemaVersion: 1,
+            reservationId: randomUUID(),
+            ...owner,
+            name: request.name,
+            protocol: "tcp",
+            hostIp: this.hostIp,
+            hostPort: port,
+            targetPort: request.targetPort ?? port,
+            state: "reserved",
+            reservedAt: now,
+            handedOffAt: null,
+            activatedAt: null,
+        };
+        this.reservations.set(reservation.reservationId, { reservation, server });
+        this.claimedPorts.set(port, reservation.reservationId);
+        return reservation;
+    }
+    async listen(signal, excludedPorts) {
+        if (this.minimumPort === null || this.maximumPort === null) {
+            for (let attempt = 0; attempt < 16; attempt += 1) {
+                const result = await listenOn(this.hostIp, 0, signal);
+                if (!this.claimedPorts.has(result.port) && !excludedPorts.has(result.port))
+                    return result;
+                await closeServer(result.server);
+            }
+            throw new Error("host_port_broker_exhausted: could not reserve a unique ephemeral loopback port.");
+        }
+        const poolSize = this.maximumPort - this.minimumPort + 1;
+        for (let attempt = 0; attempt < poolSize; attempt += 1) {
+            const port = this.nextPort ?? this.minimumPort;
+            this.nextPort = port >= this.maximumPort ? this.minimumPort : port + 1;
+            if (this.claimedPorts.has(port) || excludedPorts.has(port))
+                continue;
+            try {
+                return await listenOn(this.hostIp, port, signal);
+            }
+            catch (error) {
+                if (isAddressInUse(error))
+                    continue;
+                throw error;
+            }
+        }
+        throw new Error("host_port_broker_exhausted: no loopback ports are available in the configured pool.");
+    }
+    owned(reservationId, owner) {
+        const held = this.reservations.get(reservationId);
+        if (!held)
+            return null;
+        return sameOwner(held.reservation, owner) ? held : null;
+    }
+    async withLaunchGate(action, signal) {
+        const predecessor = this.launchGate;
+        let release = () => undefined;
+        const turn = new Promise(resolve => { release = resolve; });
+        this.launchGate = predecessor.then(() => turn, () => turn);
+        try {
+            await waitForTurn(predecessor, signal);
+        }
+        catch (error) {
+            void predecessor.finally(release);
+            throw error;
+        }
+        try {
+            return await action();
+        }
+        finally {
+            release();
+        }
+    }
+}
+function listenOn(host, port, signal) {
+    if (signal?.aborted)
+        return Promise.reject(cancellationError(signal));
+    return new Promise((resolve, reject) => {
+        const server = net.createServer(socket => socket.destroy());
+        const abort = () => {
+            server.close();
+            reject(cancellationError(signal));
+        };
+        const error = (cause) => {
+            signal?.removeEventListener("abort", abort);
+            reject(cause);
+        };
+        server.once("error", error);
+        signal?.addEventListener("abort", abort, { once: true });
+        server.listen({ host, port, exclusive: true }, () => {
+            signal?.removeEventListener("abort", abort);
+            server.removeListener("error", error);
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                void closeServer(server).then(() => reject(new Error("host_port_broker_invalid: listener address was unavailable.")));
+                return;
+            }
+            resolve({ server, port: address.port });
+        });
+    });
+}
+function closeServer(server) {
+    if (!server?.listening)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => server.close(error => error ? reject(error) : resolve()));
+}
+function validateOwner(owner) {
+    if (![owner.dispatchAttemptId, owner.executionLeaseId, owner.fencingToken].every(isUuid)
+        || !boundedText(owner.processSupervisorId, 255)) {
+        throw new Error("host_port_broker_invalid: owner identity or fence is invalid.");
+    }
+}
+function validateRequest(request) {
+    if (!/^[a-z][a-z0-9_-]{0,63}$/u.test(request.name)
+        || (request.protocol !== undefined && request.protocol !== "tcp")) {
+        throw new Error("host_port_broker_invalid: only named TCP loopback reservations are supported.");
+    }
+    if (request.targetPort !== undefined)
+        validPort(request.targetPort, "targetPort");
+}
+function validPort(value, label) {
+    if (!Number.isSafeInteger(value) || Number(value) < 1 || Number(value) > 65535) {
+        throw new Error(`host_port_broker_invalid: ${label} must be a valid TCP port.`);
+    }
+    return Number(value);
+}
+function sameOwner(left, right) {
+    return left.dispatchAttemptId === right.dispatchAttemptId
+        && left.executionLeaseId === right.executionLeaseId
+        && left.fencingToken === right.fencingToken
+        && left.processSupervisorId === right.processSupervisorId;
+}
+function isAddressInUse(error) {
+    return error instanceof Error && "code" in error && error.code === "EADDRINUSE";
+}
+function isUuid(value) {
+    return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(value);
+}
+function boundedText(value, maximumLength) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= maximumLength
+        && Array.from(value).every(character => {
+            const codePoint = character.codePointAt(0) ?? 0;
+            return codePoint > 31 && codePoint !== 127;
+        });
+}
+function cancellationError(signal) {
+    return new Error(String(signal?.reason ?? "Host port reservation cancelled."));
+}
+function waitForTurn(predecessor, signal) {
+    if (!signal)
+        return predecessor;
+    if (signal.aborted)
+        return Promise.reject(cancellationError(signal));
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            reject(cancellationError(signal));
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        void predecessor.then(() => {
+            signal.removeEventListener("abort", abort);
+            resolve();
+        }, error => {
+            signal.removeEventListener("abort", abort);
+            reject(error);
+        });
+    });
+}

package/dist/runtime/host-runtime-contract.d.ts

@@ -0,0 +1,58 @@
+export declare const hostRuntimeContractPath = ".forge/forge.runtime.yml";
+export declare const hostRuntimeTestPostgresAdminEnvironment = "FORGE_TEST_POSTGRES_ADMIN_CONNECTION_STRING";
+export declare const hostRuntimeLegacyTestPostgresEnvironment = "FORGE_TEST_POSTGRES_CONNECTION_STRING";
+export type RequestedHostConcurrency = "serial" | "parallel" | "disabled";
+export type HostRuntimePortAdapter = "node" | "vite" | "next" | "aspnetcore";
+export interface HostRuntimeLaunchConfig {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly workingDirectory: string;
+    readonly environment?: Readonly<Record<string, string>>;
+}
+export interface HostRuntimePortConfig {
+    readonly name: string;
+    readonly adapter: HostRuntimePortAdapter | null;
+    readonly launch: HostRuntimeLaunchConfig | null;
+    readonly env: string;
+    readonly baseUrlEnv: string | null;
+    readonly format: string | null;
+}
+export interface HostRuntimePlaywrightConfig {
+    readonly config: string;
+    readonly baseUrlPort: string;
+    readonly workers: number;
+}
+export interface HostRuntimeContract {
+    readonly schemaVersion: 1;
+    readonly runtime: {
+        readonly hostConcurrency: RequestedHostConcurrency;
+        readonly ports: readonly HostRuntimePortConfig[];
+        readonly playwright: HostRuntimePlaywrightConfig | null;
+        readonly browserProfile: "isolated";
+        readonly singletonResources: readonly string[];
+    };
+}
+export interface LoadedHostRuntimeContract {
+    readonly contract: HostRuntimeContract;
+    readonly source: "default" | "project" | "derived";
+    readonly discovery?: HostRuntimeDiscovery | null;
+}
+export interface HostRuntimeDiscovery {
+    readonly status: "derived" | "ambiguous" | "unsupported";
+    readonly reasonCode: string;
+    readonly summary: string;
+    readonly candidateFingerprint?: string | null;
+}
+/** Returns retained bytes (or retained absence) for one canonical discovery input. */
+export type HostRuntimeSourceSnapshot = (target: string) => Promise<Buffer | null>;
+export interface HostRuntimeDirectoryEntry {
+    readonly name: string;
+    readonly isDirectory: boolean;
+    readonly isFile: boolean;
+}
+/** Returns one identity-bound directory inventory for runtime discovery. */
+export type HostRuntimeDirectorySnapshot = (target: string) => Promise<readonly HostRuntimeDirectoryEntry[]>;
+export declare function loadHostRuntimeContract(worktreePath: string, snapshot?: HostRuntimeSourceSnapshot, directorySnapshot?: HostRuntimeDirectorySnapshot): Promise<LoadedHostRuntimeContract>;
+export declare function defaultHostRuntimeContract(): HostRuntimeContract;
+export declare function validateHostRuntimeContract(source: string): HostRuntimeContract;
+export declare function hostPortEnvironment(config: HostRuntimePortConfig, hostIp: "127.0.0.1", hostPort: number): Readonly<Record<string, string>>;