@undefineds.co/xpod 0.4.17 → 0.4.19

package/dist/runtime/ingress-port.js

@@ -1,165 +0,0 @@
-"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/port-reservations.d.ts

@@ -1,86 +0,0 @@
-/**
- * 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>;

package/dist/runtime/port-reservations.js

@@ -1,183 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PORT_RESERVATION_DIR_ENV = exports.RESERVED_PORTS_ENV = void 0;
-exports.portReservationDir = portReservationDir;
-exports.portReservationFile = portReservationFile;
-exports.reservePort = reservePort;
-exports.releasePort = releasePort;
-exports.parseReservedPortsEnv = parseReservedPortsEnv;
-exports.readPortReservations = readPortReservations;
-exports.reservedPorts = reservedPorts;
-exports.portReservation = portReservation;
-exports.listenOnUnreservedPort = listenOnUnreservedPort;
-exports.getUnreservedEphemeralPort = getUnreservedEphemeralPort;
-const node_fs_1 = require("node:fs");
-const node_net_1 = __importDefault(require("node:net"));
-const node_path_1 = __importDefault(require("node:path"));
-/**
- * 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.
- */
-exports.RESERVED_PORTS_ENV = 'XPOD_RESERVED_PORTS';
-exports.PORT_RESERVATION_DIR_ENV = 'XPOD_PORT_RESERVATION_DIR';
-const DEFAULT_TTL_MS = 12 * 60 * 60 * 1_000;
-const DEFAULT_DIRECTORY = node_path_1.default.join('.test-data', 'port-reservations');
-function portReservationDir(root = process.cwd()) {
-    return process.env[exports.PORT_RESERVATION_DIR_ENV]?.trim() || node_path_1.default.join(root, DEFAULT_DIRECTORY);
-}
-function portReservationFile(port, root = process.cwd()) {
-    return node_path_1.default.join(portReservationDir(root), `${port}.json`);
-}
-/** Publishes a reservation (idempotent for the same owner and port). */
-function reservePort(reservation, root = process.cwd()) {
-    const record = {
-        ...reservation,
-        reservedAt: reservation.reservedAt ?? new Date().toISOString(),
-        source: 'file',
-    };
-    const directory = portReservationDir(root);
-    (0, node_fs_1.mkdirSync)(directory, { recursive: true });
-    (0, node_fs_1.writeFileSync)(portReservationFile(record.port, root), JSON.stringify(record, null, 2), 'utf8');
-    return record;
-}
-/** Removes a reservation this owner wrote; another owner's reservation is left alone. */
-function releasePort(port, owner, root = process.cwd()) {
-    const file = portReservationFile(port, root);
-    const existing = readReservationFile(file);
-    if (!existing) {
-        return false;
-    }
-    if (existing.owner !== owner) {
-        return false;
-    }
-    (0, node_fs_1.rmSync)(file, { force: true });
-    return true;
-}
-function parseReservedPortsEnv(value) {
-    if (!value) {
-        return [];
-    }
-    return value
-        .split(/[\s,]+/u)
-        .map((entry) => Number.parseInt(entry.trim(), 10))
-        .filter((port) => Number.isInteger(port) && port > 0 && port <= 65_535);
-}
-/** Every reservation in force right now: env var plus unexpired files. */
-function readPortReservations(options = {}) {
-    const env = options.env ?? process.env;
-    const root = options.root ?? process.cwd();
-    const now = options.now ?? Date.now();
-    const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
-    const reservations = [];
-    // Files first: they carry owner, group and timestamp, so a failure message can name who
-    // reserved the port. The env var only says "this number is spoken for".
-    let entries;
-    try {
-        entries = (0, node_fs_1.readdirSync)(portReservationDir(root));
-    }
-    catch {
-        entries = [];
-    }
-    for (const entry of entries) {
-        if (!entry.endsWith('.json')) {
-            continue;
-        }
-        const record = readReservationFile(node_path_1.default.join(portReservationDir(root), entry));
-        if (!record) {
-            continue;
-        }
-        if (now - Date.parse(record.reservedAt) > ttlMs) {
-            // A crashed run must not block a port forever; expiry is the whole reason for the stamp.
-            continue;
-        }
-        reservations.push({ ...record, source: 'file' });
-    }
-    for (const port of parseReservedPortsEnv(env[exports.RESERVED_PORTS_ENV])) {
-        if (reservations.some((reservation) => reservation.port === port)) {
-            continue;
-        }
-        reservations.push({
-            port,
-            owner: `${exports.RESERVED_PORTS_ENV}`,
-            group: 'env',
-            reservedAt: new Date(now).toISOString(),
-            source: 'env',
-        });
-    }
-    return reservations;
-}
-/** The set every allocator skips. Cheap enough to call once per allocation. */
-function reservedPorts(options = {}) {
-    return new Set(readPortReservations(options).map((reservation) => reservation.port));
-}
-/** The reservation covering a port, when there is one: what a failure message should name. */
-function portReservation(port, options = {}) {
-    return readPortReservations(options).find((reservation) => reservation.port === port);
-}
-function readReservationFile(file) {
-    try {
-        const parsed = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
-        return typeof parsed?.port === 'number' && typeof parsed?.reservedAt === 'string' ? parsed : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * 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.
- */
-async function listenOnUnreservedPort(server, host = '127.0.0.1', attempts = 8) {
-    const reserved = reservedPorts();
-    for (let attempt = 0; attempt < attempts; attempt += 1) {
-        const port = await new Promise((resolve, reject) => {
-            server.once('error', reject);
-            server.listen(0, host, () => {
-                const address = server.address();
-                resolve(typeof address === 'object' && address ? address.port : 0);
-            });
-        });
-        if (!reserved.has(port)) {
-            return port;
-        }
-        await new Promise((resolve) => server.close(() => resolve()));
-    }
-    throw new Error('the OS only offered reserved ephemeral ports; release a reservation or widen the pool');
-}
-/** An unreserved OS-assigned port, released again so the caller can bind it itself. */
-async function getUnreservedEphemeralPort(host = '127.0.0.1', attempts = 8) {
-    const server = node_net_1.default.createServer();
-    try {
-        return await listenOnUnreservedPort(server, host, attempts);
-    }
-    finally {
-        await new Promise((resolve) => server.close(() => resolve()));
-    }
-}
-//# sourceMappingURL=port-reservations.js.map

package/dist/tunnel/TunnelClientManager.d.ts

@@ -1,73 +0,0 @@
-import { getLoggerFor } from 'global-logger-factory';
-import { type ResolvedTunnelClient } from './TunnelClientResolver';
-import { type TunnelProviderId } from './TunnelProviderCatalog';
-/**
- * The settings page's "check" and "download" buttons for tunnel clients (audit N16).
- *
- * The plugin model says the artifacts ship no clients; the operator still deserves a button
- * instead of a shell command. "Check" reports where each provider's client would come from and
- * whether it runs; "download" fetches a client from its vendor into the plugin directory and
- * verifies it before anything is kept.
- *
- * Only clients with a stable, direct, platform-addressed download are installable this way
- * (cloudflared today). ngrok ships through a CDN whose URL scheme we do not pin, and the natfrp
- * frpc fork has no published direct asset: for those the answer is the install hint, not a guess.
- */
-export type TunnelClientState = 'ready' | 'missing';
-export interface TunnelClientInspection {
-    provider: TunnelProviderId;
-    label: string;
-    binary: string;
-    state: TunnelClientState;
-    source: ResolvedTunnelClient['source'];
-    /** Absolute path when one was resolved. */
-    path?: string;
-    /** `--version` output, when the client answered. */
-    version?: string;
-    installHint: string;
-    redistributable: boolean;
-    license: string;
-    /** Whether the "download" action can install this client on this platform. */
-    installable: boolean;
-    /** Why not, when `installable` is false. */
-    installableReason?: string;
-}
-export interface TunnelClientManagerOptions {
-    packageRoot?: string;
-    env?: Record<string, string | undefined>;
-    platform?: NodeJS.Platform;
-    arch?: string;
-    fetchImpl?: typeof fetch;
-    /** Runs `<binary> --version`; injected in tests. */
-    runVersion?: (binary: string) => Promise<string | undefined>;
-    /** Extracts a `.tgz` asset; injected in tests. */
-    extractTgz?: (archivePath: string, destination: string) => Promise<void>;
-    logger?: Pick<ReturnType<typeof getLoggerFor>, 'info' | 'warn'>;
-}
-export interface InstallTunnelClientResult {
-    provider: TunnelProviderId;
-    installedPath: string;
-    version?: string;
-    sourceUrl: string;
-}
-export declare class TunnelClientManager {
-    private readonly options;
-    private readonly logger;
-    private readonly packageRoot;
-    private readonly platform;
-    private readonly arch;
-    constructor(options?: TunnelClientManagerOptions);
-    /** Where downloaded clients live; also the resolver's second source. */
-    pluginDirectory(): string;
-    inspectAll(): Promise<TunnelClientInspection[]>;
-    inspect(provider: TunnelProviderId): Promise<TunnelClientInspection>;
-    /**
-     * Downloads a client into the plugin directory and keeps it only if it runs.
-     *
-     * Verification is "does the freshly written binary answer `--version`"; a file that cannot run
-     * is deleted again, so a broken or bogus download never looks installed.
-     */
-    install(provider: TunnelProviderId, options?: {
-        signal?: AbortSignal;
-    }): Promise<InstallTunnelClientResult>;
-}