@undefineds.co/xpod 0.4.13 → 0.4.15

package/dist/tunnel/SakuraFrpTunnelProvider.js

@@ -5,12 +5,20 @@
  * 使用 SakuraFRP 提供隧道服务
  * 用于没有公网 IP 的 Local 节点
  *
- * 需要用户在 SakuraFRP 控制台创建隧道并获取 Token
+ * 凭据就是控制台「配置文件」里那串启动参数 (`<访问密钥>:<隧道ID>`)。公网入口
+ * **不由用户声明**：控制台只让用户选节点和本地端口，访问地址是平台分配的，因此
+ * provider 用同一个凭据向 SakuraFrp 开放 API 查询分配结果（节点地址 + 远程端口），
+ * 声明字段只作为 API 不可用时的可选兜底。
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SakuraFrpTunnelProvider = void 0;
+exports.resolveSakuraAssignedLocalPort = resolveSakuraAssignedLocalPort;
+exports.parseSakuraCredential = parseSakuraCredential;
 const node_child_process_1 = require("node:child_process");
 const global_logger_factory_1 = require("global-logger-factory");
+const TunnelLifecycle_1 = require("./TunnelLifecycle");
+/** Where SakuraFrp assigns each tunnel's public entry. */
+const DEFAULT_SAKURA_API_BASE_URL = 'https://api.natfrp.com/v4';
 /**
  * SakuraFRP Tunnel Provider
  *
@@ -20,6 +28,8 @@ class SakuraFrpTunnelProvider {
     constructor(options) {
         this.name = 'sakura-frp';
         this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        /** Whether the platform terminates TLS for this entry (auto HTTPS). */
+        this.autoHttpsEnabled = false;
         this.process = null;
         this.status = {
             running: false,
@@ -30,7 +40,131 @@ class SakuraFrpTunnelProvider {
         this.token = options.token;
         this.publicUrl = normalizePublicEndpoint(options.publicUrl);
         this.frpcPath = options.frpcPath ?? 'frpc';
+        this.connectTimeoutMs = options.connectTimeoutMs ?? 30_000;
         this.serverAddr = options.serverAddr;
+        this.apiBaseUrl = (options.apiBaseUrl ?? DEFAULT_SAKURA_API_BASE_URL).replace(/\/+$/u, '');
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    /**
+     * 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.
+     */
+    async discoverEndpoint() {
+        const { accessKey, tunnelIds } = parseSakuraCredential(this.token);
+        if (!accessKey) {
+            return undefined;
+        }
+        try {
+            const tunnels = await this.fetchJson('/tunnels', accessKey);
+            if (!Array.isArray(tunnels)) {
+                return undefined;
+            }
+            const selected = tunnelIds.length > 0
+                ? tunnels.filter((tunnel) => tunnelIds.includes(String(tunnel?.id ?? '')))
+                : tunnels;
+            const tunnel = selected[0];
+            if (!tunnel) {
+                return undefined;
+            }
+            const remote = typeof tunnel.remote === 'string' ? tunnel.remote.trim() : '';
+            if (!remote) {
+                return undefined;
+            }
+            // Whether the platform terminates TLS is decided before any address lookup, because
+            // it also governs the entry the client prints in its own log.
+            this.autoHttpsEnabled = /auto_https\s*=\s*(auto|on|true)/iu.test(tunnel.extra ?? '')
+                || tunnel.type === 'https';
+            // A bound domain arrives as the remote value itself; a TCP tunnel arrives as a
+            // remote port and needs the node's host to become an address.
+            if (/[a-z]/iu.test(remote) && !remote.startsWith(':')) {
+                return `https://${remote.replace(/^https?:\/\//u, '')}/`;
+            }
+            const nodeHost = await this.resolveNodeHost(tunnel.node, accessKey);
+            // A TCP tunnel without auto-HTTPS leaves the entry as plain HTTP. SakuraFrp refuses
+            // plain HTTP to a web service on its mainland nodes by policy ("网页（国内节点）必须"
+            // enable it, per their own auto-HTTPS guide), so claiming such a URL would be a
+            // reachability claim the platform itself rejects.
+            if (!this.autoHttpsEnabled) {
+                this.discoveryBlockedReason = nodeHost
+                    ? `sakura-auto-https-required: enable 自动 HTTPS in the SakuraFrp console for ${nodeHost}:${remote}`
+                    : `sakura-auto-https-required: enable 自动 HTTPS in the SakuraFrp console for the entry on port ${remote}`;
+                return undefined;
+            }
+            if (!nodeHost) {
+                // No API host: the client's own log names the entry, and the reason is not a policy
+                // block, so leave discoveryBlockedReason unset and let the log answer.
+                return undefined;
+            }
+            return `https://${nodeHost}:${remote}/`;
+        }
+        catch (error) {
+            this.logger.warn(`Could not read the assigned SakuraFrp endpoint: ${error.message}`);
+            return undefined;
+        }
+    }
+    /**
+     * 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.
+     */
+    async resolveClientCredential() {
+        const { accessKey, tunnelIds } = parseSakuraCredential(this.token);
+        if (!accessKey || tunnelIds.length > 0) {
+            return undefined;
+        }
+        try {
+            const tunnels = await this.fetchJson('/tunnels', accessKey);
+            if (!Array.isArray(tunnels) || tunnels.length !== 1) {
+                if (Array.isArray(tunnels) && tunnels.length > 1) {
+                    this.logger.warn(`SakuraFrp credential holds no tunnel id and the account has ${tunnels.length} tunnels; use the console startup parameter`);
+                }
+                return undefined;
+            }
+            const completed = `${accessKey}:${tunnels[0]?.id}`;
+            this.logger.info(`SakuraFrp credential completed with the single tunnel id ${tunnels[0]?.id}`);
+            return completed;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async resolveNodeHost(node, accessKey) {
+        if (node === undefined) {
+            return undefined;
+        }
+        const nodes = await this.fetchJson('/nodes', accessKey);
+        const record = nodes?.[String(node)];
+        const host = record?.host?.trim();
+        if (!host) {
+            return undefined;
+        }
+        return host.replace(/^https?:\/\//u, '').replace(/\/+$/u, '');
+    }
+    async fetchJson(path, accessKey) {
+        const response = await this.fetchImpl(`${this.apiBaseUrl}${path}`, {
+            headers: { authorization: `Bearer ${accessKey}`, accept: 'application/json' },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            throw new Error(`${path} answered ${response.status}`);
+        }
+        return await response.json();
+    }
+    /**
+     * 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.
+     */
+    currentEndpoint() {
+        return normalizePublicEndpoint(this.discoveredEndpoint)
+            ?? this.logEndpoint
+            ?? this.publicUrl
+            ?? this.status.endpoint;
     }
     /**
      * Setup: 解析 Token 获取配置
@@ -40,7 +174,7 @@ class SakuraFrpTunnelProvider {
         // 这里返回基本配置，实际配置由 frpc 从 Token 获取
         const config = {
             subdomain: 'sakura',
-            provider: 'sakura-frp',
+            provider: 'sakura_frp',
             endpoint: this.publicUrl ?? '',
             tunnelToken: this.token,
         };
@@ -53,14 +187,30 @@ class SakuraFrpTunnelProvider {
     async start(config) {
         const actualConfig = config ?? {
             subdomain: 'sakura',
-            provider: 'sakura-frp',
+            provider: 'sakura_frp',
             endpoint: this.publicUrl ?? '',
             tunnelToken: this.token,
         };
-        // 检测是否已经在运行
+        // Ask the platform where this tunnel is reachable before claiming any endpoint.
+        // The same answer completes the client parameter: the console's access key alone is not
+        // enough for `frpc -f`, which needs `<访问密钥>:<隧道ID>`.
+        this.discoveryBlockedReason = undefined;
+        this.discoveredEndpoint = await this.discoverEndpoint();
+        this.clientCredential = await this.resolveClientCredential();
+        if (this.discoveredEndpoint) {
+            this.logger.info(`SakuraFrp assigned ${this.discoveredEndpoint}`);
+        }
+        else if (this.discoveryBlockedReason) {
+            this.logger.warn(this.discoveryBlockedReason);
+        }
+        // A foreign frpc is not ours to adopt: another instance's tunnel would be reported as
+        // this provider's readiness and its stop would kill a process we do not own.
         if (this.isFrpcRunning()) {
-            this.logger.info('frpc already running externally');
-            this.status = { running: true, connected: true };
+            this.logger.warn('Another frpc process is already running; refusing to take it over');
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', {
+                endpoint: this.currentEndpoint(),
+                error: 'frpc-already-running',
+            });
             this.currentConfig = actualConfig;
             this.managedByUs = false;
             return;
@@ -69,12 +219,12 @@ class SakuraFrpTunnelProvider {
             this.logger.info('Already running (managed by us)');
             return;
         }
-        const token = actualConfig.tunnelToken ?? this.token;
+        const token = this.clientCredential ?? actualConfig.tunnelToken ?? this.token;
         if (!token) {
             throw new Error('SakuraFRP token is required');
         }
         this.logger.info('Starting SakuraFRP tunnel...');
-        this.status = { running: true, connected: false };
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('process-started', { endpoint: this.currentEndpoint() });
         this.managedByUs = true;
         // SakuraFRP 使用 frpc 客户端
         // 命令格式: frpc -f <token>
@@ -101,32 +251,67 @@ class SakuraFrpTunnelProvider {
         });
         this.process.on('exit', (code) => {
             this.logger.info(`frpc exited with code ${code}`);
-            this.status = { running: false, connected: false };
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', {
+                endpoint: this.currentEndpoint(),
+                error: this.status.error ?? (code === 0 ? 'frpc-exited' : `frpc exited with code ${code}`),
+            });
             this.process = null;
             this.managedByUs = false;
         });
         this.process.on('error', (error) => {
-            this.logger.error(`Failed to start frpc: ${error.message}`);
-            this.status = { running: false, connected: false, error: error.message };
+            const described = (0, TunnelLifecycle_1.describeSpawnError)('sakura-frp', this.frpcPath, error);
+            this.logger.error(`Failed to start frpc: ${described}`);
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', { endpoint: this.currentEndpoint(), error: described });
             this.process = null;
             this.managedByUs = false;
         });
         this.currentConfig = actualConfig;
         // 等待连接
-        await this.waitForConnection();
+        await this.waitForConnection(this.connectTimeoutMs);
     }
     checkConnectionStatus(output) {
-        // 检测连接成功的关键字
-        if (output.includes('start proxy success') ||
-            output.includes('login to server success') ||
-            output.includes('tunnel running')) {
-            this.status.connected = true;
-            this.status.lastHeartbeat = new Date();
+        const lower = output.toLowerCase();
+        // The vendor client logs Chinese and the upstream client logs English; both vocabularies
+        // must count, otherwise a healthy official tunnel never leaves control-connected.
+        const proxyReady = lower.includes('start proxy success')
+            || lower.includes('tunnel running')
+            || output.includes('隧道启动成功');
+        const controlConnected = lower.includes('login to server success')
+            || output.includes('连接节点成功');
+        // The official client prints the assigned entry ("使用 >>host:port<< 连接你的隧道"), which
+        // is the only source for nodes whose API record publishes no host.
+        const assigned = /使用\s*>>([^<]+)<<|连接方式[:：]?\s*([\w.-]+:\d+)/u.exec(output);
+        if (assigned && this.autoHttpsEnabled) {
+            const address = (assigned[1] ?? assigned[2]).trim().replace(/^https?:\/\//u, '');
+            this.logEndpoint = `https://${address.replace(/\/+$/u, '')}/`;
+        }
+        // 代理已发布才算就绪
+        if (proxyReady) {
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('proxy-ready', {
+                endpoint: this.currentEndpoint(),
+                lastHeartbeat: new Date(),
+                // The proxy is up, but an entry the platform refuses to serve is not an entry.
+                error: this.discoveryBlockedReason ?? this.status.error,
+            });
             this.logger.info('SakuraFRP tunnel connected');
         }
-        // 检测错误
-        if (output.includes('error') || output.includes('failed')) {
-            this.status.error = output;
+        else if (controlConnected && this.status.stage !== 'proxy-ready') {
+            // 控制连接成功说明凭据可用，但代理还没起来
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('control-connected', {
+                endpoint: this.currentEndpoint(),
+                error: this.status.error,
+            });
+        }
+        // 检测错误：代理启动失败必须撤销"已连接"
+        if (lower.includes('start proxy error') || lower.includes('start error')) {
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', {
+                endpoint: this.currentEndpoint(),
+                error: output,
+            });
+            return;
+        }
+        if (lower.includes('error') || lower.includes('failed')) {
+            this.status = { ...this.status, error: output };
         }
     }
     /**
@@ -135,7 +320,7 @@ class SakuraFrpTunnelProvider {
     async stop() {
         if (!this.managedByUs) {
             this.logger.info('Not managed by us, skipping stop');
-            this.status = { running: false, connected: false };
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('stopped', { endpoint: this.status.endpoint, error: this.status.error });
             return;
         }
         if (this.process) {
@@ -155,14 +340,14 @@ class SakuraFrpTunnelProvider {
             this.process = null;
             this.logger.info('SakuraFRP 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;
     }
     getStatus() {
         return { ...this.status };
     }
     getEndpoint() {
-        return this.currentConfig?.endpoint;
+        return this.currentEndpoint();
     }
     async cleanup(_config) {
         await this.stop();
@@ -198,13 +383,71 @@ class SakuraFrpTunnelProvider {
             }
             await new Promise((r) => setTimeout(r, 500));
         }
-        this.logger.warn('Connection timeout, tunnel may still be connecting...');
+        // Timeout is a visible failure: frpc is running but no proxy was published.
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', {
+            endpoint: this.currentEndpoint(),
+            error: this.status.error ?? 'frpc-connect-timeout',
+        });
+        this.logger.warn('frpc did not publish a proxy before the timeout');
+        throw new Error('SakuraFRP connection timeout');
     }
     isManagedByUs() {
         return this.managedByUs;
     }
 }
 exports.SakuraFrpTunnelProvider = SakuraFrpTunnelProvider;
+/**
+ * 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.
+ */
+async function resolveSakuraAssignedLocalPort(token, options = {}) {
+    const { accessKey, tunnelIds } = parseSakuraCredential(token);
+    if (!accessKey) {
+        return undefined;
+    }
+    const base = (options.apiBaseUrl ?? DEFAULT_SAKURA_API_BASE_URL).replace(/\/+$/u, '');
+    const doFetch = options.fetchImpl ?? fetch;
+    try {
+        const response = await doFetch(`${base}/tunnels`, {
+            headers: { authorization: `Bearer ${accessKey}`, accept: 'application/json' },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            return undefined;
+        }
+        const tunnels = await response.json();
+        if (!Array.isArray(tunnels)) {
+            return undefined;
+        }
+        const selected = tunnelIds.length > 0
+            ? tunnels.find((tunnel) => tunnelIds.includes(String(tunnel?.id ?? '')))
+            : tunnels[0];
+        const port = Number(selected?.local_port);
+        return Number.isInteger(port) && port > 0 && port <= 65535 ? port : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Splits the console's startup parameter into the access key and the tunnel ids. */
+function parseSakuraCredential(value) {
+    const raw = value?.trim();
+    if (!raw) {
+        return { tunnelIds: [] };
+    }
+    const separator = raw.indexOf(':');
+    if (separator < 0) {
+        // Older setups stored the bare access key; the platform then decides the tunnel.
+        return { accessKey: raw, tunnelIds: [] };
+    }
+    return {
+        accessKey: raw.slice(0, separator).trim() || undefined,
+        tunnelIds: raw.slice(separator + 1).split(',').map((id) => id.trim()).filter(Boolean),
+    };
+}
 function normalizePublicEndpoint(value) {
     if (!value?.trim()) {
         return undefined;

package/dist/tunnel/TunnelLifecycle.d.ts

@@ -0,0 +1,14 @@
+import type { TunnelStage, TunnelStatus } from './TunnelProvider';
+/**
+ * Tunnel readiness is a sequence, not a boolean.
+ *
+ * A provider process that started is not a control connection, a control connection is not
+ * a published proxy, and a published proxy is not proof that the Gateway is reachable from
+ * outside. These helpers keep every provider reporting the same four facts so the UI and
+ * the diagnostics never turn "we spawned something" into "the tunnel is up".
+ */
+export declare function createTunnelStatus(stage: TunnelStage, patch?: Partial<TunnelStatus>): TunnelStatus;
+/** Keeps the previous error visible while a provider transitions through a restart. */
+export declare function mergeTunnelError(previous: string | undefined, next: string | undefined): string | undefined;
+/** Recognizes a missing client binary, which is a deployment fact, not a network failure. */
+export declare function describeSpawnError(provider: string, binary: string, error: unknown): string;

package/dist/tunnel/TunnelLifecycle.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTunnelStatus = createTunnelStatus;
+exports.mergeTunnelError = mergeTunnelError;
+exports.describeSpawnError = describeSpawnError;
+/**
+ * Tunnel readiness is a sequence, not a boolean.
+ *
+ * A provider process that started is not a control connection, a control connection is not
+ * a published proxy, and a published proxy is not proof that the Gateway is reachable from
+ * outside. These helpers keep every provider reporting the same four facts so the UI and
+ * the diagnostics never turn "we spawned something" into "the tunnel is up".
+ */
+function createTunnelStatus(stage, patch = {}) {
+    return {
+        running: stage !== 'stopped' && stage !== 'failed',
+        connected: stage === 'proxy-ready',
+        stage,
+        ...patch,
+    };
+}
+/** Keeps the previous error visible while a provider transitions through a restart. */
+function mergeTunnelError(previous, next) {
+    return next ?? previous;
+}
+/** Recognizes a missing client binary, which is a deployment fact, not a network failure. */
+function describeSpawnError(provider, binary, error) {
+    const code = typeof error === 'object' && error && 'code' in error ? String(error.code) : '';
+    if (code === 'ENOENT') {
+        return `binary-missing:${provider}:${binary}`;
+    }
+    return `spawn-failed:${provider}:${error?.message ?? String(error)}`;
+}
+//# sourceMappingURL=TunnelLifecycle.js.map

package/dist/tunnel/TunnelProfiles.d.ts

@@ -1,6 +1,10 @@
+import { TUNNEL_PROVIDER_IDS, isTunnelProviderId, tunnelProfileCredentialEnvKey, tunnelProviderDescriptor, type ActiveTunnelProvider, type TunnelProviderId } from './TunnelProviderCatalog';
+export { TUNNEL_PROVIDER_IDS };
 export declare const TUNNEL_PROVIDER_VALUES: readonly ["ngrok", "cloudflare", "sakura_frp", "frp"];
-export type TunnelProfileProvider = (typeof TUNNEL_PROVIDER_VALUES)[number];
-export type ActiveTunnelProvider = TunnelProfileProvider | 'none';
+export type TunnelProfileProvider = TunnelProviderId;
+export type { ActiveTunnelProvider };
+/** The canonical off value: an explicit "no tunnel" is a decision, not a missing value. */
+export declare const TUNNEL_ACTIVE_PROFILE_NONE = "none";
 export interface TunnelProfile {
     id: string;
     provider: TunnelProfileProvider;
@@ -8,6 +12,14 @@ export interface TunnelProfile {
     publicUrl?: string;
     credentialEnvKey?: string;
     credentialConfigured?: boolean;
+    /**
+     * Provider parameters as stored by the settings API.
+     *
+     * They are carried rather than dropped so the runtime never silently loses a value the
+     * API accepted, and so a provider that can honour one has it available; a parameter no
+     * provider consumes is reported by `unconsumedProfileParameters()` instead of vanishing.
+     */
+    parameters?: Record<string, string>;
 }
 export interface TunnelProfileState {
     profiles: TunnelProfile[];
@@ -15,8 +27,26 @@ export interface TunnelProfileState {
     activeProfile?: TunnelProfile;
     inactiveProfiles: TunnelProfile[];
     activeProvider: ActiveTunnelProvider;
+    /** Why the requested profile is not active; missing when the state is unremarkable. */
+    activationError?: string;
 }
 type EnvLike = Record<string, string | undefined>;
+/**
+ * Resolves the tunnel profile state for a runtime environment.
+ *
+ * Authority rules (they are what stops a closed tunnel from coming back):
+ * - `XPOD_TUNNEL_PROFILES` being **present** is authoritative — an empty list means "no
+ *   profiles", never "fall back to the legacy keys".
+ * - `XPOD_TUNNEL_ACTIVE_PROFILE_ID` being **present** is authoritative — an empty value or
+ *   `none` means "explicitly off" and suppresses the legacy provider and the auto-pick.
+ */
 export declare function resolveTunnelProfileState(env: EnvLike): TunnelProfileState;
 export declare function selectActiveTunnelProfile(inputProfiles: readonly TunnelProfile[], activeProfileId?: string): TunnelProfileState;
-export {};
+/**
+ * Parameters a profile declares that no provider implementation consumes.
+ *
+ * Reporting them is what keeps the settings form from collecting values with no effect:
+ * the fix is either to consume the parameter or to stop declaring the field.
+ */
+export declare function unconsumedProfileParameters(profile: Pick<TunnelProfile, 'parameters'>, consumed?: readonly string[]): string[];
+export { isTunnelProviderId, tunnelProviderDescriptor, tunnelProfileCredentialEnvKey };