@undefineds.co/xpod 0.4.14 → 0.4.16

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;
+    /** Environment used to resolve the client binary; injectable for tests. */
+    env?: Record<string, string | undefined>;
     /** 等待代理发布的毫秒数；超时后状态为 failed，而不是"仍在连接" */
     connectTimeoutMs?: number;
 }
@@ -96,6 +98,11 @@ export declare class LocalTunnelProvider implements TunnelProvider {
  *
  * 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.
+ *
+ * cloudflared logs the configuration it fetched as an escaped JSON string inside one log line
+ * (`config="{\"ingress\":[{\"service\":\"http://localhost:5737\"}]}"`), so the quotes around
+ * the JSON keys arrive backslash-escaped. Unescaping first is what makes this read-back work
+ * against a real connector; a line where the JSON is not escaped is still accepted.
  */
 export declare function readDashboardOrigin(output: string): {
     scheme: string;

package/dist/tunnel/LocalTunnelProvider.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocalTunnelProvider = void 0;
 exports.readDashboardOrigin = readDashboardOrigin;
+const TunnelClientResolver_1 = require("./TunnelClientResolver");
 const node_child_process_1 = require("node:child_process");
 const global_logger_factory_1 = require("global-logger-factory");
 const TunnelLifecycle_1 = require("./TunnelLifecycle");
@@ -32,7 +33,8 @@ class LocalTunnelProvider {
         this.managedByUs = false;
         this.tunnelToken = options.tunnelToken;
         this.publicUrl = normalizePublicEndpoint(options.publicUrl);
-        this.cloudflaredPath = options.cloudflaredPath ?? 'cloudflared';
+        this.cloudflaredPath = options.cloudflaredPath
+            ?? (0, TunnelClientResolver_1.resolveTunnelClient)('cloudflare', { env: options.env }).command;
         this.connectTimeoutMs = options.connectTimeoutMs ?? 30_000;
     }
     /**
@@ -345,10 +347,16 @@ function normalizePublicEndpoint(value) {
  *
  * 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.
+ *
+ * cloudflared logs the configuration it fetched as an escaped JSON string inside one log line
+ * (`config="{\"ingress\":[{\"service\":\"http://localhost:5737\"}]}"`), so the quotes around
+ * the JSON keys arrive backslash-escaped. Unescaping first is what makes this read-back work
+ * against a real connector; a line where the JSON is not escaped is still accepted.
  */
 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);
+    const unescaped = output.includes('\\"') ? output.replace(/\\"/gu, '"') : output;
+    const match = /"service"\s*:\s*"(https?):\/\/(?:localhost|127\.0\.0\.1):(\d+)/iu.exec(unescaped)
+        ?? /ingress[^\n]*service["']?\s*[:=]\s*["']?(https?):\/\/(?:localhost|127\.0\.0\.1):(\d+)/iu.exec(unescaped);
     if (!match) {
         return undefined;
     }

package/dist/tunnel/LocalTunnelProvider.jsonld

@@ -44,6 +44,30 @@
           },
           "comment": "cloudflared 可执行文件路径 (默认 'cloudflared')"
         },
+        {
+          "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env",
+          "range": {
+            "@type": "ParameterRangeCollectEntries",
+            "parameterRangeCollectEntriesParameters": [
+              {
+                "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env_key"
+              },
+              {
+                "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env_value",
+                "range": {
+                  "@type": "ParameterRangeUnion",
+                  "parameterRangeElements": [
+                    "xsd:string",
+                    {
+                      "@type": "ParameterRangeUndefined"
+                    }
+                  ]
+                }
+              }
+            ]
+          },
+          "comment": "Environment used to resolve the client binary; injectable for tests."
+        },
         {
           "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_connectTimeoutMs",
           "range": {
@@ -178,6 +202,21 @@
                 "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_cloudflaredPath"
               }
             },
+            {
+              "keyRaw": "env",
+              "value": {
+                "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env__constructorArgument",
+                "fields": [
+                  {
+                    "collectEntries": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env",
+                    "key": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env_key",
+                    "value": {
+                      "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env_value"
+                    }
+                  }
+                ]
+              }
+            },
             {
               "keyRaw": "connectTimeoutMs",
               "value": {

package/dist/tunnel/NgrokTunnelProvider.d.ts

@@ -6,6 +6,8 @@ export interface NgrokTunnelProviderOptions {
     url?: string;
     /** ngrok executable path. */
     ngrokPath?: string;
+    /** Environment used to resolve the client binary; injectable for tests. */
+    env?: Record<string, string | undefined>;
     /** ngrok local Agent API, used to discover generated dev domains. */
     agentApiUrl?: string;
     /** Startup wait timeout. */

package/dist/tunnel/NgrokTunnelProvider.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NgrokTunnelProvider = void 0;
 exports.isLocalAgentUrl = isLocalAgentUrl;
+const TunnelClientResolver_1 = require("./TunnelClientResolver");
 const node_child_process_1 = require("node:child_process");
 const global_logger_factory_1 = require("global-logger-factory");
 const TunnelLifecycle_1 = require("./TunnelLifecycle");
@@ -26,7 +27,8 @@ class NgrokTunnelProvider {
         this.managedByUs = false;
         this.authtoken = options.authtoken;
         this.configuredUrl = normalizeEndpointForCli(options.url);
-        this.ngrokPath = options.ngrokPath ?? 'ngrok';
+        this.ngrokPath = options.ngrokPath
+            ?? (0, TunnelClientResolver_1.resolveTunnelClient)('ngrok', { env: options.env }).command;
         this.agentApiUrl = options.agentApiUrl ?? 'http://127.0.0.1:4040';
         this.connectTimeoutMs = options.connectTimeoutMs ?? 30_000;
     }

package/dist/tunnel/NgrokTunnelProvider.jsonld

@@ -52,6 +52,30 @@
           },
           "comment": "ngrok executable path."
         },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env",
+          "range": {
+            "@type": "ParameterRangeCollectEntries",
+            "parameterRangeCollectEntriesParameters": [
+              {
+                "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env_key"
+              },
+              {
+                "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env_value",
+                "range": {
+                  "@type": "ParameterRangeUnion",
+                  "parameterRangeElements": [
+                    "xsd:string",
+                    {
+                      "@type": "ParameterRangeUndefined"
+                    }
+                  ]
+                }
+              }
+            ]
+          },
+          "comment": "Environment used to resolve the client binary; injectable for tests."
+        },
         {
           "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_agentApiUrl",
           "range": {
@@ -199,6 +223,21 @@
                 "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_ngrokPath"
               }
             },
+            {
+              "keyRaw": "env",
+              "value": {
+                "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env__constructorArgument",
+                "fields": [
+                  {
+                    "collectEntries": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env",
+                    "key": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env_key",
+                    "value": {
+                      "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env_value"
+                    }
+                  }
+                ]
+              }
+            },
             {
               "keyRaw": "agentApiUrl",
               "value": {

package/dist/tunnel/SakuraFrpTunnelProvider.d.ts

@@ -20,6 +20,8 @@ export interface SakuraFrpTunnelProviderOptions {
     publicUrl?: string;
     /** frpc 可执行文件路径 (默认 'frpc') */
     frpcPath?: string;
+    /** Environment used to resolve the client binary; injectable for tests. */
+    env?: Record<string, string | undefined>;
     /** 等待代理发布的毫秒数；超时后状态为 failed */
     connectTimeoutMs?: number;
     /** SakuraFRP 服务端地址 (如果需要自定义) */
@@ -35,7 +37,7 @@ export interface SakuraFrpTunnelProviderOptions {
  * 通过 frpc 客户端连接 SakuraFRP 服务
  */
 export declare class SakuraFrpTunnelProvider implements TunnelProvider {
-    readonly name = "sakura-frp";
+    readonly name = "sakura_frp";
     private readonly logger;
     private readonly token;
     private readonly publicUrl?;

package/dist/tunnel/SakuraFrpTunnelProvider.js

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SakuraFrpTunnelProvider = void 0;
 exports.resolveSakuraAssignedLocalPort = resolveSakuraAssignedLocalPort;
 exports.parseSakuraCredential = parseSakuraCredential;
+const TunnelClientResolver_1 = require("./TunnelClientResolver");
 const node_child_process_1 = require("node:child_process");
 const global_logger_factory_1 = require("global-logger-factory");
 const TunnelLifecycle_1 = require("./TunnelLifecycle");
@@ -26,7 +27,9 @@ const DEFAULT_SAKURA_API_BASE_URL = 'https://api.natfrp.com/v4';
  */
 class SakuraFrpTunnelProvider {
     constructor(options) {
-        this.name = 'sakura-frp';
+        // The catalog id, not a hyphenated implementation name: the provider vocabulary has exactly
+        // one spelling, and this one is also what failure details embed.
+        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;
@@ -39,7 +42,8 @@ class SakuraFrpTunnelProvider {
         this.managedByUs = false;
         this.token = options.token;
         this.publicUrl = normalizePublicEndpoint(options.publicUrl);
-        this.frpcPath = options.frpcPath ?? 'frpc';
+        this.frpcPath = options.frpcPath
+            ?? (0, TunnelClientResolver_1.resolveTunnelClient)('sakura_frp', { env: options.env }).command;
         this.connectTimeoutMs = options.connectTimeoutMs ?? 30_000;
         this.serverAddr = options.serverAddr;
         this.apiBaseUrl = (options.apiBaseUrl ?? DEFAULT_SAKURA_API_BASE_URL).replace(/\/+$/u, '');
@@ -259,7 +263,7 @@ class SakuraFrpTunnelProvider {
             this.managedByUs = false;
         });
         this.process.on('error', (error) => {
-            const described = (0, TunnelLifecycle_1.describeSpawnError)('sakura-frp', this.frpcPath, error);
+            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;

package/dist/tunnel/TunnelClientManager.d.ts

@@ -0,0 +1,73 @@
+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>;
+}