@undefineds.co/xpod 0.4.13 → 0.4.15

package/dist/runtime/port-finder.js

@@ -3,7 +3,10 @@ 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.requireFreePortForWildcard = requireFreePortForWildcard;
 exports.getFreePortForWildcard = getFreePortForWildcard;
 const node_net_1 = __importDefault(require("node:net"));
 const node_os_1 = __importDefault(require("node:os"));
@@ -97,6 +100,23 @@ 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.
+ */
+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();
+}
 async function getFreePort(basePort, host = '127.0.0.1', timeoutMs = PORT_PROBE_TIMEOUT_MS) {
     for (let port = basePort; port <= HIGHEST_PORT; port++) {
         if (await canListen(port, host, timeoutMs)) {
@@ -105,6 +125,32 @@ async function getFreePort(basePort, host = '127.0.0.1', timeoutMs = PORT_PROBE_
     }
     throw new Error(`No open port available from ${host}:${basePort} to ${host}:${HIGHEST_PORT}`);
 }
+/**
+ * Loopback port handed out by the OS for a listener that must not collide with ports the
+ * embedding process plans for other services.
+ *
+ * Probing next to the ports this runtime already owns is not safe: a host that allocates
+ * `gateway + 10`/`gateway + 11` (the full integration matrix does) has already reserved
+ * the neighbour of our own `api` port for another runtime, and binding it steals that
+ * 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);
+            });
+        });
+    });
+}
 function hasIpv6Address() {
     return Object.values(node_os_1.default.networkInterfaces()).some((entries) => entries?.some((entry) => entry.family === 'IPv6'));
 }
@@ -113,6 +159,24 @@ function hasIpv6Address() {
  * 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.
+ *
+ * A port that a tunnel console forwards to cannot be substituted: `getFreePortForWildcard`
+ * scans upward, which would leave the runtime listening somewhere the tunnel never reaches.
+ */
+async function requireFreePortForWildcard(port, timeoutMs = PORT_PROBE_TIMEOUT_MS) {
+    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)) {
+        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;
+}
 async function getFreePortForWildcard(basePort, timeoutMs = PORT_PROBE_TIMEOUT_MS) {
     const probeIpv6 = hasIpv6Address();
     for (let port = basePort; port <= HIGHEST_PORT; port++) {

package/dist/runtime/runner/node/NodeGatewayRuntimeRunner.js

@@ -15,6 +15,7 @@ class NodeGatewayRuntimeRunner {
             runtimeHost: options.runtimeHost,
             internalAdminAuthSecret: options.internalAdminAuthSecret,
             clientRemoteAddressResolver: options.clientRemoteAddressResolver,
+            ingressPort: options.ingressPort,
         });
         gateway.setTargets(options.targets);
         await gateway.start();

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

@@ -33,6 +33,11 @@ export interface GatewayRuntimeRunnerStartOptions {
     supervisor: Supervisor;
     internalAdminAuthSecret: string;
     clientRemoteAddressResolver?: (req: http.IncomingMessage) => string | undefined;
+    /**
+     * Loopback-only ingress listener for remote forwarding paths (tunnels, P2P).
+     * Port transport only; socket transport has no remote ingress.
+     */
+    ingressPort?: number;
     targets: {
         css: RuntimeConnectionTarget;
         api: RuntimeConnectionTarget;

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

@@ -10,6 +10,7 @@ export interface XpodRuntimePorts {
     gateway?: number;
     css?: number;
     api?: number;
+    ingress?: number;
 }
 export interface XpodRuntimeSockets {
     gateway?: string;

package/dist/test-utils/local-managed-client-p2p-e2e-smoke.js

@@ -38,7 +38,7 @@ async function runLocalManagedClientP2PE2ESmoke(options = {}) {
         const { token: serviceToken } = await serviceTokenRepo.createToken({
             serviceType: 'cloud',
             serviceId: 'managed-client-smoke',
-            scopes: ['reachability:read', 'reachability:write'],
+            scopes: ['network:read', 'network:write'],
         });
         const signalApi = await startSignalApi({
             nodeRepo,

package/dist/tunnel/AutoTunnelProvider.d.ts

@@ -0,0 +1,56 @@
+import type { TunnelConfig, TunnelProvider, TunnelSetupOptions, TunnelStatus } from './TunnelProvider';
+/** One tunnel the auto provider may bring up, in the order it is worth trying. */
+export interface AutoTunnelCandidate {
+    /** Provider or profile id, used in status and in the failure detail. */
+    id: string;
+    provider: TunnelProvider;
+}
+export interface AutoTunnelProviderOptions {
+    candidates: readonly AutoTunnelCandidate[];
+    /**
+     * How long one candidate gets to reach `proxy-ready` before the next one is
+     * tried. A candidate that is blocked (network policy, rejected credential)
+     * usually fails faster than this; the timeout only bounds the silent ones.
+     */
+    readinessTimeoutMs?: number;
+    /** Poll interval while waiting for readiness. */
+    pollIntervalMs?: number;
+}
+/**
+ * Brings up whichever tunnel actually works.
+ *
+ * An operator configures the providers they have credentials for; which of them
+ * can reach its control plane is a property of the network, not of the list. So
+ * the candidates are tried in order and the first one that publishes a proxy
+ * wins, with the losers stopped and their reasons kept for the failure report.
+ * An explicit selection never goes through here: the runtime registers that
+ * provider directly, so a closed or pinned tunnel cannot come back on its own.
+ */
+export declare class AutoTunnelProvider implements TunnelProvider {
+    readonly name = "auto";
+    private readonly logger;
+    private readonly candidates;
+    private readonly readinessTimeoutMs;
+    private readonly pollIntervalMs;
+    private configs;
+    private active?;
+    private started;
+    private status;
+    /** Why each candidate that did not win was dropped. */
+    private readonly attempts;
+    constructor(options: AutoTunnelProviderOptions);
+    setup(options: TunnelSetupOptions): Promise<TunnelConfig>;
+    start(config?: TunnelConfig): Promise<void>;
+    stop(): Promise<void>;
+    getStatus(): TunnelStatus;
+    getEndpoint(): string | undefined;
+    cleanup(config: TunnelConfig): Promise<void>;
+    /** Id of the candidate currently serving, once one is ready. */
+    getActiveId(): string | undefined;
+    /** The candidates that were tried, and why the ones that lost did. */
+    getAttempts(): readonly string[];
+    private waitForReady;
+    /** Stop a candidate that lost and stop counting it as started. */
+    private dropCandidate;
+    private stopLosers;
+}

package/dist/tunnel/AutoTunnelProvider.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutoTunnelProvider = void 0;
+const global_logger_factory_1 = require("global-logger-factory");
+const TunnelLifecycle_1 = require("./TunnelLifecycle");
+const DEFAULT_READINESS_TIMEOUT_MS = 30_000;
+const DEFAULT_POLL_INTERVAL_MS = 250;
+/**
+ * Brings up whichever tunnel actually works.
+ *
+ * An operator configures the providers they have credentials for; which of them
+ * can reach its control plane is a property of the network, not of the list. So
+ * the candidates are tried in order and the first one that publishes a proxy
+ * wins, with the losers stopped and their reasons kept for the failure report.
+ * An explicit selection never goes through here: the runtime registers that
+ * provider directly, so a closed or pinned tunnel cannot come back on its own.
+ */
+class AutoTunnelProvider {
+    constructor(options) {
+        this.name = 'auto';
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        this.configs = new Map();
+        this.started = [];
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('stopped');
+        /** Why each candidate that did not win was dropped. */
+        this.attempts = [];
+        this.candidates = options.candidates;
+        this.readinessTimeoutMs = options.readinessTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    }
+    async setup(options) {
+        this.configs = new Map();
+        for (const candidate of this.candidates) {
+            try {
+                this.configs.set(candidate.id, await candidate.provider.setup(options));
+            }
+            catch (error) {
+                this.attempts.push(`${candidate.id}: ${describeError(error)}`);
+                this.logger.warn(`Tunnel candidate ${candidate.id} could not be prepared: ${describeError(error)}`);
+            }
+        }
+        // The driver round-trips this config back into `start`, which drives the
+        // candidates itself, so it only has to describe the requested origin.
+        const first = this.candidates[0];
+        const config = first ? this.configs.get(first.id) : undefined;
+        return config ?? {
+            subdomain: options.subdomain,
+            provider: 'cloudflare',
+            endpoint: '',
+            originUrl: `${options.localProtocol ?? 'http'}://127.0.0.1:${options.localPort}`,
+        };
+    }
+    async start(config) {
+        void config;
+        for (const candidate of this.candidates) {
+            const candidateConfig = this.configs.get(candidate.id);
+            if (!candidateConfig) {
+                continue;
+            }
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('process-started', { endpoint: candidate.provider.getEndpoint() });
+            try {
+                this.started.push(candidate);
+                await candidate.provider.start(candidateConfig);
+                const ready = await this.waitForReady(candidate.provider);
+                if (ready) {
+                    this.active = candidate;
+                    this.status = withCandidate(candidate, candidate.provider.getStatus());
+                    this.logger.info(`Tunnel ready through ${candidate.id}`);
+                    await this.stopLosers(candidate);
+                    return;
+                }
+                this.attempts.push(`${candidate.id}: ${describeStatus(candidate.provider.getStatus())}`);
+                this.logger.warn(`Tunnel candidate ${candidate.id} did not become ready; trying the next one`);
+                await this.dropCandidate(candidate);
+            }
+            catch (error) {
+                this.attempts.push(`${candidate.id}: ${describeError(error)}`);
+                this.logger.warn(`Tunnel candidate ${candidate.id} failed: ${describeError(error)}`);
+                await this.dropCandidate(candidate);
+            }
+        }
+        // Nothing worked: report which candidates were tried and why, so a caller
+        // never has to guess whether the tunnel is off or merely unreachable.
+        const detail = this.attempts.length > 0
+            ? this.attempts.join('; ')
+            : 'no tunnel provider is configured';
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', { error: `no-tunnel-candidate-ready: ${detail}` });
+    }
+    async stop() {
+        const targets = this.started;
+        this.started = [];
+        this.active = undefined;
+        await Promise.all(targets.map(async (candidate) => {
+            await candidate.provider.stop().catch((error) => {
+                this.logger.warn(`Stopping tunnel candidate ${candidate.id} failed: ${describeError(error)}`);
+            });
+        }));
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('stopped');
+    }
+    getStatus() {
+        if (!this.active) {
+            return this.status;
+        }
+        const current = this.active.provider.getStatus();
+        // A tunnel that was ready and then died is still the active one, so its
+        // failure is what callers must see - never a stale "connected".
+        return withCandidate(this.active, current);
+    }
+    getEndpoint() {
+        return this.active?.provider.getEndpoint();
+    }
+    async cleanup(config) {
+        await Promise.all(this.candidates.map(async (candidate) => {
+            await candidate.provider.cleanup(config).catch((error) => {
+                this.logger.warn(`Cleaning up tunnel candidate ${candidate.id} failed: ${describeError(error)}`);
+            });
+        }));
+    }
+    /** Id of the candidate currently serving, once one is ready. */
+    getActiveId() {
+        return this.active?.id;
+    }
+    /** The candidates that were tried, and why the ones that lost did. */
+    getAttempts() {
+        return this.attempts;
+    }
+    async waitForReady(provider) {
+        const deadline = Date.now() + this.readinessTimeoutMs;
+        while (Date.now() < deadline) {
+            const status = provider.getStatus();
+            if (status.stage === 'proxy-ready' || status.connected) {
+                return true;
+            }
+            if (status.stage === 'failed') {
+                return false;
+            }
+            await delay(this.pollIntervalMs);
+        }
+        return false;
+    }
+    /** Stop a candidate that lost and stop counting it as started. */
+    async dropCandidate(candidate) {
+        await candidate.provider.stop().catch((error) => {
+            this.logger.warn(`Stopping tunnel candidate ${candidate.id} failed: ${describeError(error)}`);
+        });
+        this.started = this.started.filter((started) => started.id !== candidate.id);
+    }
+    async stopLosers(winner) {
+        await Promise.all(this.started
+            .filter((candidate) => candidate.id !== winner.id)
+            .map(async (candidate) => {
+            await candidate.provider.stop().catch(() => undefined);
+        }));
+        this.started = [winner];
+    }
+}
+exports.AutoTunnelProvider = AutoTunnelProvider;
+/**
+ * The winning candidate's own status, with its error text attributed to the
+ * profile id the operator configured rather than to the provider class name.
+ */
+function withCandidate(candidate, status) {
+    const stage = status.stage ?? (status.connected ? 'proxy-ready' : 'process-started');
+    const error = status.error ? `${candidate.id}: ${status.error}` : undefined;
+    return (0, TunnelLifecycle_1.createTunnelStatus)(stage, {
+        ...status,
+        ...(error ? { error } : {}),
+    });
+}
+function describeStatus(status) {
+    return status.error ?? status.stage ?? (status.connected ? 'connected' : 'unknown');
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+//# sourceMappingURL=AutoTunnelProvider.js.map

package/dist/tunnel/LocalTunnelProvider.d.ts

@@ -10,6 +10,8 @@ export interface LocalTunnelProviderOptions {
     publicUrl?: string;
     /** cloudflared 可执行文件路径 (默认 'cloudflared') */
     cloudflaredPath?: string;
+    /** 等待代理发布的毫秒数；超时后状态为 failed，而不是"仍在连接" */
+    connectTimeoutMs?: number;
 }
 /**
  * Local Tunnel Provider
@@ -28,6 +30,7 @@ export declare class LocalTunnelProvider implements TunnelProvider {
     private readonly tunnelToken;
     private readonly publicUrl?;
     private readonly cloudflaredPath;
+    private readonly connectTimeoutMs;
     private process;
     private status;
     private currentConfig;
@@ -46,6 +49,8 @@ export declare class LocalTunnelProvider implements TunnelProvider {
     /**
      * 解析并打印 cloudflared 日志
      */
+    /** Set when the dashboard's origin port and this runtime's ingress port disagree. */
+    private originMismatch?;
     private logOutput;
     /**
      * 停止隧道
@@ -86,3 +91,13 @@ export declare class LocalTunnelProvider implements TunnelProvider {
      */
     isManagedByUs(): boolean;
 }
+/**
+ * The origin a remotely-managed tunnel declares for its hostname.
+ *
+ * Both halves are reported: pointing the dashboard at `https://localhost:<port>` while this
+ * runtime serves plain HTTP there fails the TLS handshake, and the edge shows only a 502.
+ */
+export declare function readDashboardOrigin(output: string): {
+    scheme: string;
+    port: number;
+} | undefined;

package/dist/tunnel/LocalTunnelProvider.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocalTunnelProvider = void 0;
+exports.readDashboardOrigin = readDashboardOrigin;
 const node_child_process_1 = require("node:child_process");
 const global_logger_factory_1 = require("global-logger-factory");
+const TunnelLifecycle_1 = require("./TunnelLifecycle");
 /** cloudflared metrics 端口 */
 const CLOUDFLARED_METRICS_PORT = 33863;
 /**
@@ -31,6 +33,7 @@ class LocalTunnelProvider {
         this.tunnelToken = options.tunnelToken;
         this.publicUrl = normalizePublicEndpoint(options.publicUrl);
         this.cloudflaredPath = options.cloudflaredPath ?? 'cloudflared';
+        this.connectTimeoutMs = options.connectTimeoutMs ?? 30_000;
     }
     /**
      * Local 模式不需要 setup，直接返回基于 Token 的配置
@@ -71,7 +74,7 @@ class LocalTunnelProvider {
             throw new Error('Tunnel token is required');
         }
         this.logger.info('Starting cloudflared tunnel...');
-        this.status = { running: true, connected: false };
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('process-started', { endpoint: this.status.endpoint });
         this.managedByUs = true;
         const args = [
             'tunnel',
@@ -92,10 +95,13 @@ class LocalTunnelProvider {
             if (output) {
                 this.logOutput(output);
             }
-            // 检测连接成功
-            if (output.includes('Connection registered') || output.includes('Registered tunnel connection')) {
-                this.status.connected = true;
-                this.status.lastHeartbeat = new Date();
+            // 检测连接成功：只有连接注册成功才代表代理已发布
+            if (output.includes('Registered tunnel connection') || output.includes('Connection registered')) {
+                this.status = (0, TunnelLifecycle_1.createTunnelStatus)('proxy-ready', {
+                    endpoint: this.status.endpoint,
+                    lastHeartbeat: new Date(),
+                    error: this.status.error,
+                });
                 this.logger.info('Tunnel connected successfully');
             }
         });
@@ -106,10 +112,31 @@ class LocalTunnelProvider {
                 this.logOutput(output);
                 // 检测连接成功
                 if (output.includes('Registered tunnel connection') || output.includes('Connection registered')) {
-                    this.status.connected = true;
-                    this.status.lastHeartbeat = new Date();
+                    this.status = (0, TunnelLifecycle_1.createTunnelStatus)('proxy-ready', {
+                        endpoint: this.status.endpoint,
+                        lastHeartbeat: new Date(),
+                        error: this.status.error ?? this.originMismatch,
+                    });
                     // logOutput 已经打印了信息，这里不需要重复打印
                 }
+                // A remotely-managed tunnel forwards to the port the dashboard declares, which is
+                // not the port we dialled if the operator never matched them: naming that mismatch
+                // is the difference between "the entry is unreachable" and a fixable configuration.
+                const declared = readDashboardOrigin(output);
+                if (declared !== undefined) {
+                    const dialled = this.currentConfig?.originUrl;
+                    // Scheme matters as much as the port: an https service pointed at this plain-HTTP
+                    // ingress listener fails the handshake, which the edge reports as a bare 502.
+                    this.originMismatch = dialled && (declared.port !== readPort(dialled) || declared.scheme !== readScheme(dialled))
+                        ? `origin-mismatch:dashboard=${declared.scheme}://localhost:${declared.port},runtime=${dialled}`
+                        : undefined;
+                    if (this.originMismatch) {
+                        this.logger.warn(`The Cloudflare dashboard forwards this hostname to ${declared.scheme}://localhost:${declared.port}, but this runtime serves ${dialled}: set the dashboard service to that address`);
+                    }
+                    if (this.status.stage === 'proxy-ready') {
+                        this.status.error = this.originMismatch ?? this.status.error;
+                    }
+                }
                 // 检测错误
                 if (output.includes('ERR') || output.includes('failed')) {
                     this.status.error = output;
@@ -118,24 +145,25 @@ class LocalTunnelProvider {
         });
         this.process.on('exit', (code) => {
             this.logger.info(`Process exited with code ${code}`);
-            this.status = { running: false, connected: false };
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', {
+                endpoint: this.status.endpoint,
+                error: this.status.error ?? (code === 0 ? 'cloudflared-exited' : `cloudflared exited with code ${code}`),
+            });
             this.process = null;
             this.managedByUs = false;
         });
         this.process.on('error', (error) => {
-            this.logger.error(`Failed to start: ${error.message}`);
-            this.status = { running: false, connected: false, error: error.message };
+            const described = (0, TunnelLifecycle_1.describeSpawnError)('cloudflare', this.cloudflaredPath, error);
+            this.logger.error(`Failed to start: ${described}`);
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', { endpoint: this.status.endpoint, error: described });
             this.process = null;
             this.managedByUs = false;
         });
         this.currentConfig = actualConfig;
         this.status.endpoint = actualConfig.endpoint;
         // 等待连接建立
-        await this.waitForConnection();
+        await this.waitForConnection(this.connectTimeoutMs);
     }
-    /**
-     * 解析并打印 cloudflared 日志
-     */
     logOutput(raw) {
         const lines = raw.split('\n');
         for (const line of lines) {
@@ -174,7 +202,8 @@ class LocalTunnelProvider {
     async stop() {
         if (!this.managedByUs) {
             this.logger.info('Not managed by us, skipping stop');
-            this.status = { running: false, connected: false };
+            // Keep the last error: stopping must not launder a failed tunnel into a clean one.
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('stopped', { endpoint: this.status.endpoint, error: this.status.error });
             return;
         }
         if (this.process) {
@@ -195,7 +224,7 @@ class LocalTunnelProvider {
             this.process = null;
             this.logger.info('Tunnel stopped');
         }
-        this.status = { running: false, connected: false };
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('stopped', { endpoint: this.status.endpoint, error: this.status.error });
         this.managedByUs = false;
     }
     /**
@@ -280,8 +309,13 @@ class LocalTunnelProvider {
             }
             await new Promise((r) => setTimeout(r, 500));
         }
-        // 超时不抛错，cloudflared 可能还在连接中
-        this.logger.warn('Connection timeout, tunnel may still be connecting...');
+        // A timeout is a fact the caller has to see: the process exists but nothing is
+        // published yet, so the tunnel is not ready.
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', {
+            endpoint: this.status.endpoint,
+            error: this.status.error ?? 'cloudflared-connect-timeout',
+        });
+        this.logger.warn('cloudflared did not register a tunnel connection before the timeout');
     }
     /**
      * 获取是否由我们管理
@@ -306,4 +340,39 @@ function normalizePublicEndpoint(value) {
         return value.trim();
     }
 }
+/**
+ * The origin a remotely-managed tunnel declares for its hostname.
+ *
+ * Both halves are reported: pointing the dashboard at `https://localhost:<port>` while this
+ * runtime serves plain HTTP there fails the TLS handshake, and the edge shows only a 502.
+ */
+function readDashboardOrigin(output) {
+    const match = /"service"\s*:\s*"(https?):\/\/(?:localhost|127\.0\.0\.1):(\d+)/iu.exec(output)
+        ?? /ingress[^\n]*service["']?\s*[:=]\s*["']?(https?):\/\/(?:localhost|127\.0\.0\.1):(\d+)/iu.exec(output);
+    if (!match) {
+        return undefined;
+    }
+    const port = Number.parseInt(match[2], 10);
+    return Number.isInteger(port) && port > 0 ? { scheme: match[1].toLowerCase(), port } : undefined;
+}
+function readPort(value) {
+    if (!value)
+        return undefined;
+    try {
+        return Number.parseInt(new URL(value).port, 10) || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readScheme(value) {
+    if (!value)
+        return undefined;
+    try {
+        return new URL(value).protocol.replace(':', '');
+    }
+    catch {
+        return undefined;
+    }
+}
 //# sourceMappingURL=LocalTunnelProvider.js.map

package/dist/tunnel/LocalTunnelProvider.jsonld

@@ -43,6 +43,19 @@
             ]
           },
           "comment": "cloudflared 可执行文件路径 (默认 'cloudflared')"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_connectTimeoutMs",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:number",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "等待代理发布的毫秒数；超时后状态为 failed，而不是\"仍在连接\""
         }
       ],
       "memberFields": [
@@ -66,6 +79,10 @@
           "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider__member_cloudflaredPath",
           "memberFieldName": "cloudflaredPath"
         },
+        {
+          "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider__member_connectTimeoutMs",
+          "memberFieldName": "connectTimeoutMs"
+        },
         {
           "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider__member_process",
           "memberFieldName": "process"
@@ -94,6 +111,10 @@
           "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider__member_start",
           "memberFieldName": "start"
         },
+        {
+          "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider__member_originMismatch",
+          "memberFieldName": "originMismatch"
+        },
         {
           "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider__member_logOutput",
           "memberFieldName": "logOutput"
@@ -156,6 +177,12 @@
               "value": {
                 "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_cloudflaredPath"
               }
+            },
+            {
+              "keyRaw": "connectTimeoutMs",
+              "value": {
+                "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_connectTimeoutMs"
+              }
             }
           ]
         }

package/dist/tunnel/NgrokTunnelProvider.d.ts

@@ -31,6 +31,8 @@ export declare class NgrokTunnelProvider implements TunnelProvider {
     private status;
     private currentConfig;
     private managedByUs;
+    /** Origin this instance asked ngrok to expose; the agent answer must match it. */
+    private expectedLocalOrigin?;
     constructor(options?: NgrokTunnelProviderOptions);
     setup(options: TunnelSetupOptions): Promise<TunnelConfig>;
     start(config?: TunnelConfig): Promise<void>;
@@ -44,3 +46,5 @@ export declare class NgrokTunnelProvider implements TunnelProvider {
     private waitForConnection;
     private discoverEndpointFromAgentApi;
 }
+/** Loopback endpoints belong to the agent itself, never to a published tunnel. */
+export declare function isLocalAgentUrl(url: string): boolean;