@undefineds.co/xpod 0.4.13 → 0.4.15

package/dist/tunnel/NgrokTunnelProvider.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NgrokTunnelProvider = void 0;
+exports.isLocalAgentUrl = isLocalAgentUrl;
 const node_child_process_1 = require("node:child_process");
 const global_logger_factory_1 = require("global-logger-factory");
+const TunnelLifecycle_1 = require("./TunnelLifecycle");
 /**
  * Starts a user-owned ngrok agent for Local SP access.
  *
@@ -37,6 +39,7 @@ class NgrokTunnelProvider {
             endpoint: normalizeEndpointForConfig(this.configuredUrl) ?? '',
             originUrl,
         };
+        this.expectedLocalOrigin = originUrl;
         this.currentConfig = config;
         return config;
     }
@@ -59,11 +62,9 @@ class NgrokTunnelProvider {
             args.push('--url', endpointForCli);
         }
         args.push(actualConfig.originUrl);
-        this.status = {
-            running: true,
-            connected: false,
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('process-started', {
             endpoint: normalizeEndpointForConfig(endpointForCli),
-        };
+        });
         this.currentConfig = {
             ...actualConfig,
             endpoint: this.status.endpoint ?? actualConfig.endpoint,
@@ -81,23 +82,20 @@ class NgrokTunnelProvider {
         this.process.stderr?.on('data', (data) => this.handleOutput(data.toString()));
         this.process.on('exit', (code) => {
             this.logger.info(`ngrok 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 ? undefined : `ngrok exited with code ${code}`),
-            };
+                error: this.status.error ?? (code === 0 ? 'ngrok-exited' : `ngrok exited with code ${code}`),
+            });
             this.process = null;
             this.managedByUs = false;
         });
         this.process.on('error', (error) => {
-            this.logger.error(`Failed to start ngrok: ${error.message}`);
-            this.status = {
-                running: false,
-                connected: false,
+            const described = (0, TunnelLifecycle_1.describeSpawnError)('ngrok', this.ngrokPath, error);
+            this.logger.error(`Failed to start ngrok: ${described}`);
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', {
                 endpoint: this.status.endpoint,
-                error: error.message,
-            };
+                error: described,
+            });
             this.process = null;
             this.managedByUs = false;
         });
@@ -105,7 +103,8 @@ class NgrokTunnelProvider {
     }
     async stop() {
         if (!this.managedByUs) {
-            this.status = { running: false, connected: false, endpoint: this.status.endpoint };
+            // Keep the last error: stopping must not turn 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) {
@@ -122,7 +121,7 @@ class NgrokTunnelProvider {
             });
             this.process = null;
         }
-        this.status = { running: false, connected: false, endpoint: this.status.endpoint };
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('stopped', { endpoint: this.status.endpoint, error: this.status.error });
         this.managedByUs = false;
     }
     getStatus() {
@@ -158,17 +157,36 @@ class NgrokTunnelProvider {
         }
     }
     markConnected(endpoint) {
-        const normalized = normalizeEndpointForConfig(endpoint);
-        if (!normalized) {
+        // Readiness requires a process we still own: without one, any endpoint we just learned
+        // about (for example from the machine-wide agent API) belongs to someone else.
+        if (!this.process || !this.managedByUs) {
+            return;
+        }
+        const discovered = normalizeEndpointForConfig(endpoint);
+        const declared = normalizeEndpointForConfig(this.configuredUrl);
+        // A discovered entry has to be a real public endpoint: the local agent's own web
+        // interface is not one, and accepting it made a tunnel that published nothing look up.
+        if (!declared && (!discovered || isLocalAgentUrl(discovered))) {
             return;
         }
-        this.status.connected = true;
-        this.status.endpoint = normalized;
-        this.status.lastHeartbeat = new Date();
+        const effective = declared ?? discovered;
+        if (!effective) {
+            return;
+        }
+        if (declared && discovered && normalizeOrigin(declared) !== normalizeOrigin(discovered)) {
+            // The operator declared one entry and ngrok published another; report the declared
+            // one but leave the discrepancy in the log for whoever has to explain reachability.
+            this.logger.warn(`ngrok published ${discovered} while ${declared} is declared; keeping the declared entry`);
+        }
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('proxy-ready', {
+            endpoint: effective,
+            lastHeartbeat: new Date(),
+            error: this.status.error,
+        });
         this.currentConfig = {
-            ...(this.currentConfig ?? { subdomain: 'local', provider: 'ngrok', endpoint: normalized }),
+            ...(this.currentConfig ?? { subdomain: 'local', provider: 'ngrok', endpoint: effective }),
             provider: 'ngrok',
-            endpoint: normalized,
+            endpoint: effective,
         };
     }
     async waitForConnection() {
@@ -180,49 +198,71 @@ class NgrokTunnelProvider {
             if (!this.status.running && this.status.error) {
                 throw new Error(`ngrok failed to start: ${this.status.error}`);
             }
-            const endpoint = await this.discoverEndpointFromAgentApi();
-            if (endpoint) {
-                this.markConnected(endpoint);
-                return;
+            // The agent API is machine-wide: another instance's agent answers on the same port.
+            // Only consult it while this provider actually has a process, otherwise a provider
+            // that failed to start would adopt someone else's tunnel as its own.
+            if (this.process && this.managedByUs) {
+                const endpoint = await this.discoverEndpointFromAgentApi();
+                if (endpoint) {
+                    this.markConnected(endpoint);
+                    // Discovery may have been refused (foreign entry, no live process); only an
+                    // actual readiness transition ends the wait.
+                    if (this.status.connected) {
+                        return;
+                    }
+                }
             }
             await new Promise((resolve) => setTimeout(resolve, Math.min(250, Math.max(25, this.connectTimeoutMs))));
         }
         if (!this.status.running && this.status.error) {
             throw new Error(`ngrok failed to start: ${this.status.error}`);
         }
-        if (this.status.endpoint) {
-            this.logger.warn('ngrok connection was not confirmed before timeout; keeping configured endpoint as degraded.');
-            this.status.connected = false;
-            return;
-        }
-        throw new Error('ngrok connection timeout');
+        // A timeout must not be reported as a running tunnel that merely lacks a heartbeat:
+        // the endpoint is recorded, but the stage says nothing is serving yet.
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', {
+            endpoint: this.status.endpoint,
+            error: this.status.error ?? 'ngrok-connect-timeout',
+        });
+        throw new Error(`ngrok connection timeout${this.status.endpoint ? ` for ${this.status.endpoint}` : ''}`);
     }
     async discoverEndpointFromAgentApi() {
         const base = this.agentApiUrl.replace(/\/+$/u, '');
-        return await readNgrokAgentEndpoint(`${base}/api/tunnels`)
-            ?? await readNgrokAgentEndpoint(`${base}/api/endpoints`);
+        return await readNgrokAgentEndpoint(`${base}/api/tunnels`, this.expectedLocalOrigin)
+            ?? await readNgrokAgentEndpoint(`${base}/api/endpoints`, this.expectedLocalOrigin);
     }
 }
 exports.NgrokTunnelProvider = NgrokTunnelProvider;
-async function readNgrokAgentEndpoint(url) {
+/** Loopback endpoints belong to the agent itself, never to a published tunnel. */
+function isLocalAgentUrl(url) {
+    try {
+        const { hostname } = new URL(url);
+        const normalized = hostname.replace(/^\[/u, '').replace(/\]$/u, '').toLowerCase();
+        return normalized === 'localhost' || normalized === '::1' || normalized.startsWith('127.');
+    }
+    catch {
+        return true;
+    }
+}
+async function readNgrokAgentEndpoint(url, expectedLocalOrigin) {
     try {
         const response = await fetch(url);
         if (!response.ok) {
             return undefined;
         }
         const body = await response.json();
-        return extractEndpointFromAgentBody(body);
+        return extractEndpointFromAgentBody(body, expectedLocalOrigin);
     }
     catch {
         return undefined;
     }
 }
-function extractEndpointFromAgentBody(body) {
+function extractEndpointFromAgentBody(body, expectedLocalOrigin) {
     if (!body || typeof body !== 'object') {
         return undefined;
     }
     const record = body;
     const lists = [record.tunnels, record.endpoints].filter(Array.isArray);
+    const candidates = [];
     for (const list of lists) {
         for (const item of list) {
             if (!item || typeof item !== 'object') {
@@ -232,12 +272,44 @@ function extractEndpointFromAgentBody(body) {
             const publicUrl = typeof value.public_url === 'string' ? value.public_url : undefined;
             const url = typeof value.url === 'string' ? value.url : undefined;
             const endpoint = normalizeEndpointForConfig(publicUrl ?? url);
-            if (endpoint?.startsWith('https://')) {
-                return endpoint;
+            if (!endpoint?.startsWith('https://') || isLocalAgentUrl(endpoint)) {
+                continue;
             }
+            const config = value.config;
+            const address = config && typeof config === 'object'
+                ? config.addr
+                : undefined;
+            candidates.push({ endpoint, ...(typeof address === 'string' ? { address } : {}) });
         }
     }
-    return undefined;
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    if (!expectedLocalOrigin) {
+        return candidates[0].endpoint;
+    }
+    // An entry exposing our own origin is ours. When the agent reports no address at all we
+    // can only accept it if there is exactly one candidate, otherwise ownership is a guess.
+    const matched = candidates.find((candidate) => candidate.address
+        && normalizeOrigin(candidate.address) === normalizeOrigin(expectedLocalOrigin));
+    if (matched) {
+        return matched.endpoint;
+    }
+    return candidates.length === 1 && !candidates[0].address ? candidates[0].endpoint : undefined;
+}
+function normalizeOrigin(value) {
+    try {
+        const url = new URL(value);
+        const hostname = url.hostname.replace(/^\[/u, '').replace(/\]$/u, '').toLowerCase();
+        // `localhost`, `::1` and `127.x` are the same machine; agents spell them differently.
+        const host = hostname === 'localhost' || hostname === '::1' || hostname.startsWith('127.')
+            ? '127.0.0.1'
+            : hostname;
+        return `${url.protocol}//${host}:${url.port || (url.protocol === 'https:' ? '443' : '80')}`;
+    }
+    catch {
+        return value.trim().replace(/\/+$/u, '');
+    }
 }
 function extractEndpoint(output) {
     try {
@@ -261,10 +333,12 @@ function extractEndpointFromText(value) {
 }
 function isConnectionLine(output) {
     const lower = output.toLowerCase();
+    // A bare "started" is not evidence that a tunnel exists: the agent logs it for its own
+    // web interface as well.
     return lower.includes('started tunnel')
         || lower.includes('tunnel started')
         || lower.includes('client session established')
-        || lower.includes('started');
+        || lower.includes('started tunnel session');
 }
 function extractError(output) {
     try {

package/dist/tunnel/NgrokTunnelProvider.jsonld

@@ -124,6 +124,10 @@
           "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_managedByUs",
           "memberFieldName": "managedByUs"
         },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_expectedLocalOrigin",
+          "memberFieldName": "expectedLocalOrigin"
+        },
         {
           "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_constructor",
           "memberFieldName": "constructor"

package/dist/tunnel/SakuraFrpTunnelProvider.d.ts

@@ -4,21 +4,30 @@
  * 使用 SakuraFRP 提供隧道服务
  * 用于没有公网 IP 的 Local 节点
  *
- * 需要用户在 SakuraFRP 控制台创建隧道并获取 Token
+ * 凭据就是控制台「配置文件」里那串启动参数 (`<访问密钥>:<隧道ID>`)。公网入口
+ * **不由用户声明**：控制台只让用户选节点和本地端口，访问地址是平台分配的，因此
+ * provider 用同一个凭据向 SakuraFrp 开放 API 查询分配结果（节点地址 + 远程端口），
+ * 声明字段只作为 API 不可用时的可选兜底。
  */
 import type { TunnelProvider, TunnelConfig, TunnelSetupOptions, TunnelStatus } from './TunnelProvider';
 /**
  * SakuraFRP Tunnel Provider 配置
  */
 export interface SakuraFrpTunnelProviderOptions {
-    /** SakuraFRP Token (从环境变量 SAKURA_TUNNEL_TOKEN 获取) */
+    /** SakuraFRP 启动参数 (`<访问密钥>:<隧道ID>[,<隧道ID>...]`)，来自 SAKURA_TUNNEL_TOKEN */
     token: string;
-    /** Active profile public endpoint, shown in status and DDNS diagnostics. */
+    /** Optional declared endpoint, used only when the provider cannot be asked. */
     publicUrl?: string;
     /** frpc 可执行文件路径 (默认 'frpc') */
     frpcPath?: string;
+    /** 等待代理发布的毫秒数；超时后状态为 failed */
+    connectTimeoutMs?: number;
     /** SakuraFRP 服务端地址 (如果需要自定义) */
     serverAddr?: string;
+    /** SakuraFrp open API base, where the assigned public entry can be read back. */
+    apiBaseUrl?: string;
+    /** Injection point for tests; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
 }
 /**
  * SakuraFRP Tunnel Provider
@@ -31,12 +40,49 @@ export declare class SakuraFrpTunnelProvider implements TunnelProvider {
     private readonly token;
     private readonly publicUrl?;
     private readonly frpcPath;
+    private readonly connectTimeoutMs;
     private readonly serverAddr?;
+    private readonly apiBaseUrl;
+    private readonly fetchImpl;
+    /** Endpoint the platform assigned, once discovery has answered. */
+    private discoveredEndpoint?;
+    /** Credential actually handed to frpc, completed from the platform answer when needed. */
+    private clientCredential?;
+    /** Why no browser-facing entry can be claimed, when the platform refuses plain HTTP. */
+    private discoveryBlockedReason?;
+    /** Whether the platform terminates TLS for this entry (auto HTTPS). */
+    private autoHttpsEnabled;
+    /** Entry the client itself printed, used when the platform API cannot name one. */
+    private logEndpoint?;
     private process;
     private status;
     private currentConfig;
     private managedByUs;
     constructor(options: SakuraFrpTunnelProviderOptions);
+    /**
+     * Reads back the entry the platform assigned to this tunnel.
+     *
+     * The console never asks for a domain: for a TCP tunnel it assigns a node host and a
+     * remote port, and for a bound tunnel it assigns the domain itself. Asking the provider
+     * is therefore the only honest way to learn the entry, and a failure to ask changes
+     * nothing except that the status stops short of naming an endpoint.
+     */
+    private discoverEndpoint;
+    /**
+     * Builds the parameter frpc needs, completing a bare access key with the tunnel it owns.
+     *
+     * `-f` accepts `<访问密钥>:<隧道ID>`; an operator who pasted only the access key would
+     * otherwise get `Bad fetch parameter` even though discovery can read the tunnel with that
+     * same key. Completion is only safe when the answer is unambiguous.
+     */
+    private resolveClientCredential;
+    private resolveNodeHost;
+    private fetchJson;
+    /**
+     * The endpoint to report: what the platform assigned, else what the client printed, else
+     * what was declared. Nothing is invented when no source names an entry.
+     */
+    private currentEndpoint;
     /**
      * Setup: 解析 Token 获取配置
      */
@@ -60,3 +106,19 @@ export declare class SakuraFrpTunnelProvider implements TunnelProvider {
     private waitForConnection;
     isManagedByUs(): boolean;
 }
+/**
+ * The local port the SakuraFrp console told the tunnel to forward to.
+ *
+ * The console already owns this fact, and the provider reads the same API for the public
+ * entry, so the runtime must take the port from there instead of asking the operator to type
+ * it a second time.
+ */
+export declare function resolveSakuraAssignedLocalPort(token: string | undefined, options?: {
+    apiBaseUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<number | undefined>;
+/** Splits the console's startup parameter into the access key and the tunnel ids. */
+export declare function parseSakuraCredential(value: string | undefined): {
+    accessKey?: string;
+    tunnelIds: string[];
+};