@undefineds.co/xpod 0.3.55 → 0.3.57

package/dist/tunnel/NgrokTunnelProvider.d.ts

@@ -0,0 +1,46 @@
+import type { TunnelProvider, TunnelConfig, TunnelSetupOptions, TunnelStatus } from './TunnelProvider';
+export interface NgrokTunnelProviderOptions {
+    /** ngrok authtoken. Prefer local env/config; do not persist it from xpod. */
+    authtoken?: string;
+    /** Fixed ngrok endpoint/custom domain passed to `ngrok http --url`. */
+    url?: string;
+    /** ngrok executable path. */
+    ngrokPath?: string;
+    /** ngrok local Agent API, used to discover generated dev domains. */
+    agentApiUrl?: string;
+    /** Startup wait timeout. */
+    connectTimeoutMs?: number;
+}
+/**
+ * Starts a user-owned ngrok agent for Local SP access.
+ *
+ * This provider does not create ngrok resources or write Xpod DNS. A configured
+ * url can be a fixed ngrok dev domain or a paid custom domain already owned by
+ * the user's ngrok account. When url is omitted, the endpoint is discovered from
+ * the local ngrok Agent API after `ngrok http` starts.
+ */
+export declare class NgrokTunnelProvider implements TunnelProvider {
+    readonly name = "ngrok";
+    private readonly logger;
+    private readonly authtoken?;
+    private readonly configuredUrl?;
+    private readonly ngrokPath;
+    private readonly agentApiUrl;
+    private readonly connectTimeoutMs;
+    private process;
+    private status;
+    private currentConfig;
+    private managedByUs;
+    constructor(options?: NgrokTunnelProviderOptions);
+    setup(options: TunnelSetupOptions): Promise<TunnelConfig>;
+    start(config?: TunnelConfig): Promise<void>;
+    stop(): Promise<void>;
+    getStatus(): TunnelStatus;
+    getEndpoint(): string | undefined;
+    cleanup(_config: TunnelConfig): Promise<void>;
+    isManagedByUs(): boolean;
+    private handleOutput;
+    private markConnected;
+    private waitForConnection;
+    private discoverEndpointFromAgentApi;
+}

package/dist/tunnel/NgrokTunnelProvider.js

@@ -0,0 +1,344 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NgrokTunnelProvider = void 0;
+const node_child_process_1 = require("node:child_process");
+const global_logger_factory_1 = require("global-logger-factory");
+/**
+ * Starts a user-owned ngrok agent for Local SP access.
+ *
+ * This provider does not create ngrok resources or write Xpod DNS. A configured
+ * url can be a fixed ngrok dev domain or a paid custom domain already owned by
+ * the user's ngrok account. When url is omitted, the endpoint is discovered from
+ * the local ngrok Agent API after `ngrok http` starts.
+ */
+class NgrokTunnelProvider {
+    constructor(options = {}) {
+        this.name = 'ngrok';
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        this.process = null;
+        this.status = {
+            running: false,
+            connected: false,
+        };
+        this.currentConfig = null;
+        this.managedByUs = false;
+        this.authtoken = options.authtoken;
+        this.configuredUrl = normalizeEndpointForCli(options.url);
+        this.ngrokPath = options.ngrokPath ?? 'ngrok';
+        this.agentApiUrl = options.agentApiUrl ?? 'http://127.0.0.1:4040';
+        this.connectTimeoutMs = options.connectTimeoutMs ?? 30_000;
+    }
+    async setup(options) {
+        const localProtocol = options.localProtocol ?? 'http';
+        const originUrl = `${localProtocol}://127.0.0.1:${options.localPort}`;
+        const config = {
+            subdomain: options.subdomain,
+            provider: 'ngrok',
+            endpoint: normalizeEndpointForConfig(this.configuredUrl) ?? '',
+            originUrl,
+        };
+        this.currentConfig = config;
+        return config;
+    }
+    async start(config) {
+        const actualConfig = config ?? this.currentConfig;
+        if (!actualConfig?.originUrl) {
+            throw new Error('ngrok originUrl is required');
+        }
+        if (this.process) {
+            this.logger.info('ngrok already running (managed by us)');
+            return;
+        }
+        const endpointForCli = normalizeEndpointForCli(actualConfig.endpoint) ?? this.configuredUrl;
+        const args = [
+            'http',
+            '--log', 'stdout',
+            '--log-format', 'json',
+        ];
+        if (endpointForCli) {
+            args.push('--url', endpointForCli);
+        }
+        args.push(actualConfig.originUrl);
+        this.status = {
+            running: true,
+            connected: false,
+            endpoint: normalizeEndpointForConfig(endpointForCli),
+        };
+        this.currentConfig = {
+            ...actualConfig,
+            endpoint: this.status.endpoint ?? actualConfig.endpoint,
+        };
+        this.managedByUs = true;
+        const env = {
+            ...process.env,
+            ...(this.authtoken ? { NGROK_AUTHTOKEN: this.authtoken } : {}),
+        };
+        this.process = (0, node_child_process_1.spawn)(this.ngrokPath, args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env,
+        });
+        this.process.stdout?.on('data', (data) => this.handleOutput(data.toString()));
+        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,
+                endpoint: this.status.endpoint,
+                error: this.status.error ?? (code === 0 ? undefined : `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,
+                endpoint: this.status.endpoint,
+                error: error.message,
+            };
+            this.process = null;
+            this.managedByUs = false;
+        });
+        await this.waitForConnection();
+    }
+    async stop() {
+        if (!this.managedByUs) {
+            this.status = { running: false, connected: false, endpoint: this.status.endpoint };
+            return;
+        }
+        if (this.process) {
+            this.process.kill('SIGTERM');
+            await new Promise((resolve) => {
+                const timeout = setTimeout(() => {
+                    this.process?.kill('SIGKILL');
+                    resolve();
+                }, 5_000);
+                this.process?.on('exit', () => {
+                    clearTimeout(timeout);
+                    resolve();
+                });
+            });
+            this.process = null;
+        }
+        this.status = { running: false, connected: false, endpoint: this.status.endpoint };
+        this.managedByUs = false;
+    }
+    getStatus() {
+        return { ...this.status };
+    }
+    getEndpoint() {
+        return this.currentConfig?.endpoint || this.status.endpoint;
+    }
+    async cleanup(_config) {
+        await this.stop();
+        this.currentConfig = null;
+    }
+    isManagedByUs() {
+        return this.managedByUs;
+    }
+    handleOutput(raw) {
+        for (const line of raw.split('\n')) {
+            const output = line.trim();
+            if (!output) {
+                continue;
+            }
+            const endpoint = extractEndpoint(output);
+            if (endpoint) {
+                this.markConnected(endpoint);
+            }
+            else if (this.status.endpoint && isConnectionLine(output)) {
+                this.markConnected(this.status.endpoint);
+            }
+            const error = extractError(output);
+            if (error) {
+                this.status.error = mergeError(this.status.error, error);
+            }
+        }
+    }
+    markConnected(endpoint) {
+        const normalized = normalizeEndpointForConfig(endpoint);
+        if (!normalized) {
+            return;
+        }
+        this.status.connected = true;
+        this.status.endpoint = normalized;
+        this.status.lastHeartbeat = new Date();
+        this.currentConfig = {
+            ...(this.currentConfig ?? { subdomain: 'local', provider: 'ngrok', endpoint: normalized }),
+            provider: 'ngrok',
+            endpoint: normalized,
+        };
+    }
+    async waitForConnection() {
+        const startedAt = Date.now();
+        while (Date.now() - startedAt < this.connectTimeoutMs) {
+            if (this.status.connected) {
+                return;
+            }
+            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;
+            }
+            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');
+    }
+    async discoverEndpointFromAgentApi() {
+        const base = this.agentApiUrl.replace(/\/+$/u, '');
+        return await readNgrokAgentEndpoint(`${base}/api/tunnels`)
+            ?? await readNgrokAgentEndpoint(`${base}/api/endpoints`);
+    }
+}
+exports.NgrokTunnelProvider = NgrokTunnelProvider;
+async function readNgrokAgentEndpoint(url) {
+    try {
+        const response = await fetch(url);
+        if (!response.ok) {
+            return undefined;
+        }
+        const body = await response.json();
+        return extractEndpointFromAgentBody(body);
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractEndpointFromAgentBody(body) {
+    if (!body || typeof body !== 'object') {
+        return undefined;
+    }
+    const record = body;
+    const lists = [record.tunnels, record.endpoints].filter(Array.isArray);
+    for (const list of lists) {
+        for (const item of list) {
+            if (!item || typeof item !== 'object') {
+                continue;
+            }
+            const value = item;
+            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;
+            }
+        }
+    }
+    return undefined;
+}
+function extractEndpoint(output) {
+    try {
+        const parsed = JSON.parse(output);
+        const direct = typeof parsed.url === 'string' ? parsed.url : undefined;
+        const publicUrl = typeof parsed.public_url === 'string' ? parsed.public_url : undefined;
+        const msg = typeof parsed.msg === 'string' ? parsed.msg : undefined;
+        const endpoint = normalizeEndpointForConfig(direct ?? publicUrl) ?? (msg ? extractEndpointFromText(msg) : undefined);
+        if (endpoint) {
+            return endpoint;
+        }
+    }
+    catch {
+        // Fall through to text parsing.
+    }
+    return extractEndpointFromText(output);
+}
+function extractEndpointFromText(value) {
+    const match = value.match(/https:\/\/[^\s"'<>]+/u);
+    return normalizeEndpointForConfig(match?.[0]);
+}
+function isConnectionLine(output) {
+    const lower = output.toLowerCase();
+    return lower.includes('started tunnel')
+        || lower.includes('tunnel started')
+        || lower.includes('client session established')
+        || lower.includes('started');
+}
+function extractError(output) {
+    try {
+        const parsed = JSON.parse(output);
+        if (typeof parsed.err === 'string') {
+            const error = normalizeNgrokError(parsed.err);
+            if (error) {
+                return error;
+            }
+        }
+        const level = typeof parsed.lvl === 'string' ? parsed.lvl.toLowerCase() : '';
+        const message = typeof parsed.msg === 'string' ? parsed.msg.trim() : '';
+        if ((level === 'eror' || level === 'crit') && message) {
+            return message;
+        }
+        return undefined;
+    }
+    catch {
+        // Fall through to text parsing.
+    }
+    const lower = output.toLowerCase();
+    if (lower.includes('error') || lower.includes('failed') || lower.includes('err ') || lower.includes('err_')) {
+        return output;
+    }
+    return undefined;
+}
+function normalizeNgrokError(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    const lower = trimmed.toLowerCase();
+    if (lower === '<nil>' || lower === 'nil' || lower === 'null' || lower === 'undefined') {
+        return undefined;
+    }
+    return trimmed;
+}
+function mergeError(previous, next) {
+    if (!previous) {
+        return next;
+    }
+    if (/ERR_[A-Z0-9_]+/u.test(previous) && !/ERR_[A-Z0-9_]+/u.test(next)) {
+        return previous;
+    }
+    if (next.trim() === 'ERROR:' && previous.trim().length > next.trim().length) {
+        return previous;
+    }
+    return next.length > previous.length ? next : previous;
+}
+function normalizeEndpointForConfig(value) {
+    if (!value?.trim()) {
+        return undefined;
+    }
+    try {
+        const url = new URL(value.trim());
+        if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+            return undefined;
+        }
+        if (isNgrokNonTunnelUrl(url)) {
+            return undefined;
+        }
+        return url.toString().replace(/\/+$/u, '') + '/';
+    }
+    catch {
+        return undefined;
+    }
+}
+function isNgrokNonTunnelUrl(url) {
+    return (url.hostname === 'ngrok.com' && url.pathname.startsWith('/docs/errors/'))
+        || url.hostname === 'dashboard.ngrok.com'
+        || url.hostname.endsWith('.ngrok-agent.com');
+}
+function normalizeEndpointForCli(value) {
+    const normalized = normalizeEndpointForConfig(value);
+    return normalized ? normalized.replace(/\/+$/u, '') : undefined;
+}
+//# sourceMappingURL=NgrokTunnelProvider.js.map

package/dist/tunnel/NgrokTunnelProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NgrokTunnelProvider.js","sourceRoot":"","sources":["../../src/tunnel/NgrokTunnelProvider.ts"],"names":[],"mappings":";;;AAAA,2DAA8D;AAC9D,iEAAqD;AAyBrD;;;;;;;GAOG;AACH,MAAa,mBAAmB;IAkB9B,YAAmB,UAAsC,EAAE;QAjB3C,SAAI,GAAG,OAAO,CAAC;QACd,WAAM,GAAG,IAAA,oCAAY,EAAC,IAAI,CAAC,CAAC;QAQrC,YAAO,GAAwB,IAAI,CAAC;QACpC,WAAM,GAAiB;YAC7B,OAAO,EAAE,KAAK;YACd,SAAS,EAAE,KAAK;SACjB,CAAC;QACM,kBAAa,GAAwB,IAAI,CAAC;QAC1C,gBAAW,GAAG,KAAK,CAAC;QAG1B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,aAAa,GAAG,uBAAuB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1D,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC;QAC9C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,uBAAuB,CAAC;QAClE,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,MAAM,CAAC;IAC7D,CAAC;IAEM,KAAK,CAAC,KAAK,CAAC,OAA2B;QAC5C,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,MAAM,CAAC;QACtD,MAAM,SAAS,GAAG,GAAG,aAAa,gBAAgB,OAAO,CAAC,SAAS,EAAE,CAAC;QACtE,MAAM,MAAM,GAAiB;YAC3B,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,QAAQ,EAAE,OAAO;YACjB,QAAQ,EAAE,0BAA0B,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE;YAC9D,SAAS;SACV,CAAC;QAEF,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;IAEM,KAAK,CAAC,KAAK,CAAC,MAAqB;QACtC,MAAM,YAAY,GAAG,MAAM,IAAI,IAAI,CAAC,aAAa,CAAC;QAClD,IAAI,CAAC,YAAY,EAAE,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QACjD,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;YAC1D,OAAO;QACT,CAAC;QAED,MAAM,cAAc,GAAG,uBAAuB,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC;QAC5F,MAAM,IAAI,GAAG;YACX,MAAM;YACN,OAAO,EAAE,QAAQ;YACjB,cAAc,EAAE,MAAM;SACvB,CAAC;QACF,IAAI,cAAc,EAAE,CAAC;YACnB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;QACrC,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;QAElC,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,KAAK;YAChB,QAAQ,EAAE,0BAA0B,CAAC,cAAc,CAAC;SACrD,CAAC;QACF,IAAI,CAAC,aAAa,GAAG;YACnB,GAAG,YAAY;YACf,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,YAAY,CAAC,QAAQ;SACxD,CAAC;QACF,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QAExB,MAAM,GAAG,GAAG;YACV,GAAG,OAAO,CAAC,GAAG;YACd,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/D,CAAC;QAEF,IAAI,CAAC,OAAO,GAAG,IAAA,0BAAK,EAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE;YACzC,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;YACjC,GAAG;SACJ,CAAC,CAAC;QAEH,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;QACtF,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;QAEtF,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YAC/B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,0BAA0B,IAAI,EAAE,CAAC,CAAC;YACnD,IAAI,CAAC,MAAM,GAAG;gBACZ,OAAO,EAAE,KAAK;gBACd,SAAS,EAAE,KAAK;gBAChB,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;gBAC9B,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,0BAA0B,IAAI,EAAE,CAAC;aACxF,CAAC;YACF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QAC3B,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YACjC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAC7D,IAAI,CAAC,MAAM,GAAG;gBACZ,OAAO,EAAE,KAAK;gBACd,SAAS,EAAE,KAAK;gBAChB,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;gBAC9B,KAAK,EAAE,KAAK,CAAC,OAAO;aACrB,CAAC;YACF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QAC3B,CAAC,CAAC,CAAC;QAEH,MAAM,IAAI,CAAC,iBAAiB,EAAE,CAAC;IACjC,CAAC;IAEM,KAAK,CAAC,IAAI;QACf,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACnF,OAAO;QACT,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC7B,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBAClC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE;oBAC9B,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;oBAC9B,OAAO,EAAE,CAAC;gBACZ,CAAC,EAAE,KAAK,CAAC,CAAC;gBACV,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;oBAC5B,YAAY,CAAC,OAAO,CAAC,CAAC;oBACtB,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACtB,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACnF,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;IAC3B,CAAC;IAEM,SAAS;QACd,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAEM,WAAW;QAChB,OAAO,IAAI,CAAC,aAAa,EAAE,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC9D,CAAC;IAEM,KAAK,CAAC,OAAO,CAAC,OAAqB;QACxC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;IAC5B,CAAC;IAEM,aAAa;QAClB,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAEO,YAAY,CAAC,GAAW;QAC9B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC3B,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,SAAS;YACX,CAAC;YAED,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;YACzC,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;YAC/B,CAAC;iBAAM,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5D,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC3C,CAAC;YAED,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;YACnC,IAAI,KAAK,EAAE,CAAC;gBACV,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;IACH,CAAC;IAEO,aAAa,CAAC,QAAgB;QACpC,MAAM,UAAU,GAAG,0BAA0B,CAAC,QAAQ,CAAC,CAAC;QACxD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC;QAC7B,IAAI,CAAC,MAAM,CAAC,QAAQ,GAAG,UAAU,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,aAAa,GAAG,IAAI,IAAI,EAAE,CAAC;QACvC,IAAI,CAAC,aAAa,GAAG;YACnB,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAgB,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;YACnG,QAAQ,EAAE,OAAO;YACjB,QAAQ,EAAE,UAAU;SACrB,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,iBAAiB;QAC7B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACtD,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;gBAC1B,OAAO;YACT,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;gBAC9C,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;YACjE,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,4BAA4B,EAAE,CAAC;YAC3D,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;gBAC7B,OAAO;YACT,CAAC;YAED,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1G,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAC9C,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QACjE,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,6FAA6F,CAAC,CAAC;YAChH,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC;YAC9B,OAAO;QACT,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC9C,CAAC;IAEO,KAAK,CAAC,4BAA4B;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACnD,OAAO,MAAM,sBAAsB,CAAC,GAAG,IAAI,cAAc,CAAC;eACrD,MAAM,sBAAsB,CAAC,GAAG,IAAI,gBAAgB,CAAC,CAAC;IAC7D,CAAC;CACF;AApOD,kDAoOC;AAED,KAAK,UAAU,sBAAsB,CAAC,GAAW;IAC/C,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAa,CAAC;QAC9C,OAAO,4BAA4B,CAAC,IAAI,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,4BAA4B,CAAC,IAAa;IACjD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,MAAM,GAAG,IAA+B,CAAC;IAC/C,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAgB,CAAC;IACtF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;YACxB,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACtC,SAAS;YACX,CAAC;YACD,MAAM,KAAK,GAAG,IAA+B,CAAC;YAC9C,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;YACtF,MAAM,GAAG,GAAG,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;YAClE,MAAM,QAAQ,GAAG,0BAA0B,CAAC,SAAS,IAAI,GAAG,CAAC,CAAC;YAC9D,IAAI,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;gBACrC,OAAO,QAAQ,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,eAAe,CAAC,MAAc;IACrC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAA4B,CAAC;QAC7D,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QACvE,MAAM,SAAS,GAAG,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;QACxF,MAAM,GAAG,GAAG,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QACpE,MAAM,QAAQ,GAAG,0BAA0B,CAAC,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,uBAAuB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACrH,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gCAAgC;IAClC,CAAC;IACD,OAAO,uBAAuB,CAAC,MAAM,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,uBAAuB,CAAC,KAAa;IAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;IACnD,OAAO,0BAA0B,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAc;IACtC,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACnC,OAAO,KAAK,CAAC,QAAQ,CAAC,gBAAgB,CAAC;WAClC,KAAK,CAAC,QAAQ,CAAC,gBAAgB,CAAC;WAChC,KAAK,CAAC,QAAQ,CAAC,4BAA4B,CAAC;WAC5C,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,YAAY,CAAC,MAAc;IAClC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAA4B,CAAC;QAC7D,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;YACnC,MAAM,KAAK,GAAG,mBAAmB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC9C,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,MAAM,OAAO,GAAG,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,IAAI,CAAC,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACtD,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,gCAAgC;IAClC,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACnC,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5G,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAa;IACxC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACpC,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,WAAW,EAAE,CAAC;QACtF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,UAAU,CAAC,QAA4B,EAAE,IAAY;IAC5D,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC;QAC5E,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;AACzD,CAAC;AAED,SAAS,0BAA0B,CAAC,KAAyB;IAC3D,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC;QACnB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QAClC,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YAC1D,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAGD,SAAS,mBAAmB,CAAC,GAAQ;IACnC,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,WAAW,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;WAC5E,GAAG,CAAC,QAAQ,KAAK,qBAAqB;WACtC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,uBAAuB,CAAC,KAAyB;IACxD,MAAM,UAAU,GAAG,0BAA0B,CAAC,KAAK,CAAC,CAAC;IACrD,OAAO,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC","sourcesContent":["import { spawn, type ChildProcess } from 'node:child_process';\nimport { getLoggerFor } from 'global-logger-factory';\nimport type {\n  TunnelProvider,\n  TunnelConfig,\n  TunnelSetupOptions,\n  TunnelStatus,\n} from './TunnelProvider';\n\nexport interface NgrokTunnelProviderOptions {\n  /** ngrok authtoken. Prefer local env/config; do not persist it from xpod. */\n  authtoken?: string;\n\n  /** Fixed ngrok endpoint/custom domain passed to `ngrok http --url`. */\n  url?: string;\n\n  /** ngrok executable path. */\n  ngrokPath?: string;\n\n  /** ngrok local Agent API, used to discover generated dev domains. */\n  agentApiUrl?: string;\n\n  /** Startup wait timeout. */\n  connectTimeoutMs?: number;\n}\n\n/**\n * Starts a user-owned ngrok agent for Local SP access.\n *\n * This provider does not create ngrok resources or write Xpod DNS. A configured\n * url can be a fixed ngrok dev domain or a paid custom domain already owned by\n * the user's ngrok account. When url is omitted, the endpoint is discovered from\n * the local ngrok Agent API after `ngrok http` starts.\n */\nexport class NgrokTunnelProvider implements TunnelProvider {\n  public readonly name = 'ngrok';\n  private readonly logger = getLoggerFor(this);\n\n  private readonly authtoken?: string;\n  private readonly configuredUrl?: string;\n  private readonly ngrokPath: string;\n  private readonly agentApiUrl: string;\n  private readonly connectTimeoutMs: number;\n\n  private process: ChildProcess | null = null;\n  private status: TunnelStatus = {\n    running: false,\n    connected: false,\n  };\n  private currentConfig: TunnelConfig | null = null;\n  private managedByUs = false;\n\n  public constructor(options: NgrokTunnelProviderOptions = {}) {\n    this.authtoken = options.authtoken;\n    this.configuredUrl = normalizeEndpointForCli(options.url);\n    this.ngrokPath = options.ngrokPath ?? 'ngrok';\n    this.agentApiUrl = options.agentApiUrl ?? 'http://127.0.0.1:4040';\n    this.connectTimeoutMs = options.connectTimeoutMs ?? 30_000;\n  }\n\n  public async setup(options: TunnelSetupOptions): Promise<TunnelConfig> {\n    const localProtocol = options.localProtocol ?? 'http';\n    const originUrl = `${localProtocol}://127.0.0.1:${options.localPort}`;\n    const config: TunnelConfig = {\n      subdomain: options.subdomain,\n      provider: 'ngrok',\n      endpoint: normalizeEndpointForConfig(this.configuredUrl) ?? '',\n      originUrl,\n    };\n\n    this.currentConfig = config;\n    return config;\n  }\n\n  public async start(config?: TunnelConfig): Promise<void> {\n    const actualConfig = config ?? this.currentConfig;\n    if (!actualConfig?.originUrl) {\n      throw new Error('ngrok originUrl is required');\n    }\n\n    if (this.process) {\n      this.logger.info('ngrok already running (managed by us)');\n      return;\n    }\n\n    const endpointForCli = normalizeEndpointForCli(actualConfig.endpoint) ?? this.configuredUrl;\n    const args = [\n      'http',\n      '--log', 'stdout',\n      '--log-format', 'json',\n    ];\n    if (endpointForCli) {\n      args.push('--url', endpointForCli);\n    }\n    args.push(actualConfig.originUrl);\n\n    this.status = {\n      running: true,\n      connected: false,\n      endpoint: normalizeEndpointForConfig(endpointForCli),\n    };\n    this.currentConfig = {\n      ...actualConfig,\n      endpoint: this.status.endpoint ?? actualConfig.endpoint,\n    };\n    this.managedByUs = true;\n\n    const env = {\n      ...process.env,\n      ...(this.authtoken ? { NGROK_AUTHTOKEN: this.authtoken } : {}),\n    };\n\n    this.process = spawn(this.ngrokPath, args, {\n      stdio: ['ignore', 'pipe', 'pipe'],\n      env,\n    });\n\n    this.process.stdout?.on('data', (data: Buffer) => this.handleOutput(data.toString()));\n    this.process.stderr?.on('data', (data: Buffer) => this.handleOutput(data.toString()));\n\n    this.process.on('exit', (code) => {\n      this.logger.info(`ngrok exited with code ${code}`);\n      this.status = {\n        running: false,\n        connected: false,\n        endpoint: this.status.endpoint,\n        error: this.status.error ?? (code === 0 ? undefined : `ngrok exited with code ${code}`),\n      };\n      this.process = null;\n      this.managedByUs = false;\n    });\n\n    this.process.on('error', (error) => {\n      this.logger.error(`Failed to start ngrok: ${error.message}`);\n      this.status = {\n        running: false,\n        connected: false,\n        endpoint: this.status.endpoint,\n        error: error.message,\n      };\n      this.process = null;\n      this.managedByUs = false;\n    });\n\n    await this.waitForConnection();\n  }\n\n  public async stop(): Promise<void> {\n    if (!this.managedByUs) {\n      this.status = { running: false, connected: false, endpoint: this.status.endpoint };\n      return;\n    }\n\n    if (this.process) {\n      this.process.kill('SIGTERM');\n      await new Promise<void>((resolve) => {\n        const timeout = setTimeout(() => {\n          this.process?.kill('SIGKILL');\n          resolve();\n        }, 5_000);\n        this.process?.on('exit', () => {\n          clearTimeout(timeout);\n          resolve();\n        });\n      });\n      this.process = null;\n    }\n\n    this.status = { running: false, connected: false, endpoint: this.status.endpoint };\n    this.managedByUs = false;\n  }\n\n  public getStatus(): TunnelStatus {\n    return { ...this.status };\n  }\n\n  public getEndpoint(): string | undefined {\n    return this.currentConfig?.endpoint || this.status.endpoint;\n  }\n\n  public async cleanup(_config: TunnelConfig): Promise<void> {\n    await this.stop();\n    this.currentConfig = null;\n  }\n\n  public isManagedByUs(): boolean {\n    return this.managedByUs;\n  }\n\n  private handleOutput(raw: string): void {\n    for (const line of raw.split('\\n')) {\n      const output = line.trim();\n      if (!output) {\n        continue;\n      }\n\n      const endpoint = extractEndpoint(output);\n      if (endpoint) {\n        this.markConnected(endpoint);\n      } else if (this.status.endpoint && isConnectionLine(output)) {\n        this.markConnected(this.status.endpoint);\n      }\n\n      const error = extractError(output);\n      if (error) {\n        this.status.error = mergeError(this.status.error, error);\n      }\n    }\n  }\n\n  private markConnected(endpoint: string): void {\n    const normalized = normalizeEndpointForConfig(endpoint);\n    if (!normalized) {\n      return;\n    }\n    this.status.connected = true;\n    this.status.endpoint = normalized;\n    this.status.lastHeartbeat = new Date();\n    this.currentConfig = {\n      ...(this.currentConfig ?? { subdomain: 'local', provider: 'ngrok' as const, endpoint: normalized }),\n      provider: 'ngrok',\n      endpoint: normalized,\n    };\n  }\n\n  private async waitForConnection(): Promise<void> {\n    const startedAt = Date.now();\n    while (Date.now() - startedAt < this.connectTimeoutMs) {\n      if (this.status.connected) {\n        return;\n      }\n      if (!this.status.running && this.status.error) {\n        throw new Error(`ngrok failed to start: ${this.status.error}`);\n      }\n\n      const endpoint = await this.discoverEndpointFromAgentApi();\n      if (endpoint) {\n        this.markConnected(endpoint);\n        return;\n      }\n\n      await new Promise((resolve) => setTimeout(resolve, Math.min(250, Math.max(25, this.connectTimeoutMs))));\n    }\n\n    if (!this.status.running && this.status.error) {\n      throw new Error(`ngrok failed to start: ${this.status.error}`);\n    }\n\n    if (this.status.endpoint) {\n      this.logger.warn('ngrok connection was not confirmed before timeout; keeping configured endpoint as degraded.');\n      this.status.connected = false;\n      return;\n    }\n\n    throw new Error('ngrok connection timeout');\n  }\n\n  private async discoverEndpointFromAgentApi(): Promise<string | undefined> {\n    const base = this.agentApiUrl.replace(/\\/+$/u, '');\n    return await readNgrokAgentEndpoint(`${base}/api/tunnels`)\n      ?? await readNgrokAgentEndpoint(`${base}/api/endpoints`);\n  }\n}\n\nasync function readNgrokAgentEndpoint(url: string): Promise<string | undefined> {\n  try {\n    const response = await fetch(url);\n    if (!response.ok) {\n      return undefined;\n    }\n    const body = await response.json() as unknown;\n    return extractEndpointFromAgentBody(body);\n  } catch {\n    return undefined;\n  }\n}\n\nfunction extractEndpointFromAgentBody(body: unknown): string | undefined {\n  if (!body || typeof body !== 'object') {\n    return undefined;\n  }\n  const record = body as Record<string, unknown>;\n  const lists = [record.tunnels, record.endpoints].filter(Array.isArray) as unknown[][];\n  for (const list of lists) {\n    for (const item of list) {\n      if (!item || typeof item !== 'object') {\n        continue;\n      }\n      const value = item as Record<string, unknown>;\n      const publicUrl = typeof value.public_url === 'string' ? value.public_url : undefined;\n      const url = typeof value.url === 'string' ? value.url : undefined;\n      const endpoint = normalizeEndpointForConfig(publicUrl ?? url);\n      if (endpoint?.startsWith('https://')) {\n        return endpoint;\n      }\n    }\n  }\n  return undefined;\n}\n\nfunction extractEndpoint(output: string): string | undefined {\n  try {\n    const parsed = JSON.parse(output) as Record<string, unknown>;\n    const direct = typeof parsed.url === 'string' ? parsed.url : undefined;\n    const publicUrl = typeof parsed.public_url === 'string' ? parsed.public_url : undefined;\n    const msg = typeof parsed.msg === 'string' ? parsed.msg : undefined;\n    const endpoint = normalizeEndpointForConfig(direct ?? publicUrl) ?? (msg ? extractEndpointFromText(msg) : undefined);\n    if (endpoint) {\n      return endpoint;\n    }\n  } catch {\n    // Fall through to text parsing.\n  }\n  return extractEndpointFromText(output);\n}\n\nfunction extractEndpointFromText(value: string): string | undefined {\n  const match = value.match(/https:\\/\\/[^\\s\"'<>]+/u);\n  return normalizeEndpointForConfig(match?.[0]);\n}\n\nfunction isConnectionLine(output: string): boolean {\n  const lower = output.toLowerCase();\n  return lower.includes('started tunnel')\n    || lower.includes('tunnel started')\n    || lower.includes('client session established')\n    || lower.includes('started');\n}\n\nfunction extractError(output: string): string | undefined {\n  try {\n    const parsed = JSON.parse(output) as Record<string, unknown>;\n    if (typeof parsed.err === 'string') {\n      const error = normalizeNgrokError(parsed.err);\n      if (error) {\n        return error;\n      }\n    }\n    const level = typeof parsed.lvl === 'string' ? parsed.lvl.toLowerCase() : '';\n    const message = typeof parsed.msg === 'string' ? parsed.msg.trim() : '';\n    if ((level === 'eror' || level === 'crit') && message) {\n      return message;\n    }\n    return undefined;\n  } catch {\n    // Fall through to text parsing.\n  }\n\n  const lower = output.toLowerCase();\n  if (lower.includes('error') || lower.includes('failed') || lower.includes('err ') || lower.includes('err_')) {\n    return output;\n  }\n  return undefined;\n}\n\nfunction normalizeNgrokError(value: string): string | undefined {\n  const trimmed = value.trim();\n  if (!trimmed) {\n    return undefined;\n  }\n  const lower = trimmed.toLowerCase();\n  if (lower === '<nil>' || lower === 'nil' || lower === 'null' || lower === 'undefined') {\n    return undefined;\n  }\n  return trimmed;\n}\n\nfunction mergeError(previous: string | undefined, next: string): string {\n  if (!previous) {\n    return next;\n  }\n  if (/ERR_[A-Z0-9_]+/u.test(previous) && !/ERR_[A-Z0-9_]+/u.test(next)) {\n    return previous;\n  }\n  if (next.trim() === 'ERROR:' && previous.trim().length > next.trim().length) {\n    return previous;\n  }\n  return next.length > previous.length ? next : previous;\n}\n\nfunction normalizeEndpointForConfig(value: string | undefined): string | undefined {\n  if (!value?.trim()) {\n    return undefined;\n  }\n  try {\n    const url = new URL(value.trim());\n    if (url.protocol !== 'https:' && url.protocol !== 'http:') {\n      return undefined;\n    }\n    if (isNgrokNonTunnelUrl(url)) {\n      return undefined;\n    }\n    return url.toString().replace(/\\/+$/u, '') + '/';\n  } catch {\n    return undefined;\n  }\n}\n\n\nfunction isNgrokNonTunnelUrl(url: URL): boolean {\n  return (url.hostname === 'ngrok.com' && url.pathname.startsWith('/docs/errors/'))\n    || url.hostname === 'dashboard.ngrok.com'\n    || url.hostname.endsWith('.ngrok-agent.com');\n}\n\nfunction normalizeEndpointForCli(value: string | undefined): string | undefined {\n  const normalized = normalizeEndpointForConfig(value);\n  return normalized ? normalized.replace(/\\/+$/u, '') : undefined;\n}\n"]}

package/dist/tunnel/NgrokTunnelProvider.jsonld

@@ -0,0 +1,215 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider",
+      "@type": "Class",
+      "requireElement": "NgrokTunnelProvider",
+      "extends": [
+        "undefineds:dist/tunnel/TunnelProvider.jsonld#TunnelProvider"
+      ],
+      "comment": "Starts a user-owned ngrok agent for Local SP access.  This provider does not create ngrok resources or write Xpod DNS. A configured url can be a fixed ngrok dev domain or a paid custom domain already owned by the user's ngrok account. When url is omitted, the endpoint is discovered from the local ngrok Agent API after `ngrok http` starts.",
+      "parameters": [
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_authtoken",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:string",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "ngrok authtoken. Prefer local env/config; do not persist it from xpod."
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_url",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:string",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "Fixed ngrok endpoint/custom domain passed to `ngrok http --url`."
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_ngrokPath",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:string",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "ngrok executable path."
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_agentApiUrl",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:string",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "ngrok local Agent API, used to discover generated dev domains."
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_connectTimeoutMs",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:number",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "Startup wait timeout."
+        }
+      ],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_name",
+          "memberFieldName": "name"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_logger",
+          "memberFieldName": "logger"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_authtoken",
+          "memberFieldName": "authtoken"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_configuredUrl",
+          "memberFieldName": "configuredUrl"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_ngrokPath",
+          "memberFieldName": "ngrokPath"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_agentApiUrl",
+          "memberFieldName": "agentApiUrl"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_connectTimeoutMs",
+          "memberFieldName": "connectTimeoutMs"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_process",
+          "memberFieldName": "process"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_status",
+          "memberFieldName": "status"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_currentConfig",
+          "memberFieldName": "currentConfig"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_managedByUs",
+          "memberFieldName": "managedByUs"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_constructor",
+          "memberFieldName": "constructor"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_setup",
+          "memberFieldName": "setup"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_start",
+          "memberFieldName": "start"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_stop",
+          "memberFieldName": "stop"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_getStatus",
+          "memberFieldName": "getStatus"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_getEndpoint",
+          "memberFieldName": "getEndpoint"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_cleanup",
+          "memberFieldName": "cleanup"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_isManagedByUs",
+          "memberFieldName": "isManagedByUs"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_handleOutput",
+          "memberFieldName": "handleOutput"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_markConnected",
+          "memberFieldName": "markConnected"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_waitForConnection",
+          "memberFieldName": "waitForConnection"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_discoverEndpointFromAgentApi",
+          "memberFieldName": "discoverEndpointFromAgentApi"
+        }
+      ],
+      "constructorArguments": [
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options__constructorArgument",
+          "fields": [
+            {
+              "keyRaw": "authtoken",
+              "value": {
+                "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_authtoken"
+              }
+            },
+            {
+              "keyRaw": "url",
+              "value": {
+                "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_url"
+              }
+            },
+            {
+              "keyRaw": "ngrokPath",
+              "value": {
+                "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_ngrokPath"
+              }
+            },
+            {
+              "keyRaw": "agentApiUrl",
+              "value": {
+                "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_agentApiUrl"
+              }
+            },
+            {
+              "keyRaw": "connectTimeoutMs",
+              "value": {
+                "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_connectTimeoutMs"
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/dist/tunnel/TunnelProvider.d.ts

@@ -12,12 +12,12 @@ export interface TunnelConfig {
     /** 子域名 (如 mynode，完整域名为 mynode.pods.undefieds.co) */
     subdomain: string;
     /** 隧道类型 */
-    provider: 'cloudflare' | 'frp' | 'sakura-frp';
+    provider: 'cloudflare' | 'frp' | 'sakura-frp' | 'ngrok';
     /** 公网访问端点 (如 https://mynode.pods.undefieds.co) */
     endpoint: string;
     /** 本地 origin 地址 (如 http://localhost:5737)，供隧道客户端转发 */
     originUrl?: string;
-    /** Cloudflare Tunnel Token (cloudflare 专用) */
+    /** Provider token when the provider exposes a launch token (Cloudflare/SakuraFRP); ngrok authtoken is kept in local options, not persisted here. */
     tunnelToken?: string;
     /** Cloudflare Tunnel ID (cloudflare 专用) */
     tunnelId?: string;