@iicp/client 0.7.54 → 0.7.57

package/dist/tunnel.js

@@ -0,0 +1,179 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Quick-Tunnel escalation — #520 rung 5 of the NAT ladder.
+ * TypeScript port of iicp-client-python/tunnel.py (0f97ca1).
+ *
+ * When every NAT variant fails (no direct endpoint, no UPnP pinhole, no IPv6
+ * GUA, no relay-capable peer in the directory), the node can still become
+ * publicly reachable with ZERO account, domain, or router changes: spawn
+ * `cloudflared tunnel --url http://127.0.0.1:<port>` and register the issued
+ * `https://*.trycloudflare.com` URL as the endpoint.
+ *
+ * Lifecycle is fully automatic: setup (binary detection — never auto-installed),
+ * initiation (spawn + URL parse ≤20 s), supervision (bounded respawn; URL
+ * rotates → caller re-registers), teardown (close() idempotent + process-exit
+ * hook so a normal exit never orphans the child).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuickTunnel = exports.INSTALL_HINT = exports.MAX_RESPAWNS = exports.TUNNEL_START_TIMEOUT_MS = void 0;
+exports.cloudflaredPath = cloudflaredPath;
+exports.openQuickTunnel = openQuickTunnel;
+const node_child_process_1 = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+const URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+/** cloudflared usually prints the URL within ~5 s; 20 s covers slow first runs. */
+exports.TUNNEL_START_TIMEOUT_MS = 20_000;
+/** Bounded self-healing: after this many unexpected deaths, stop respawning. */
+exports.MAX_RESPAWNS = 3;
+exports.INSTALL_HINT = "cloudflared not found — install it to become reachable without router " +
+    "changes (zero-account Quick Tunnel): " +
+    "macOS `brew install cloudflared` · Linux: https://pkg.cloudflare.com · " +
+    "Windows `winget install Cloudflare.cloudflared`";
+/** Locate the cloudflared binary on PATH, or null (we never auto-install it). */
+function cloudflaredPath() {
+    const exts = process.platform === "win32" ? [".exe", ".cmd", ""] : [""];
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const candidate = path.join(dir, `cloudflared${ext}`);
+            try {
+                fs.accessSync(candidate, fs.constants.X_OK);
+                return candidate;
+            }
+            catch {
+                /* keep scanning */
+            }
+        }
+    }
+    return null;
+}
+/** A running Quick Tunnel: public `url` → `http://127.0.0.1:<localPort>`. */
+class QuickTunnel {
+    process;
+    url;
+    localPort;
+    _binary;
+    _closed = false;
+    _respawns = 0;
+    _exitHook;
+    constructor(proc, url, localPort, binary) {
+        this.process = proc;
+        this.url = url;
+        this.localPort = localPort;
+        this._binary = binary;
+        this._exitHook = () => this.close();
+        process.on("exit", this._exitHook);
+    }
+    get respawns() {
+        return this._respawns;
+    }
+    /**
+     * Start the watchdog: on unexpected exit, respawn (bounded) and call
+     * `onNewUrl(newUrl)` — Quick Tunnel URLs rotate per process, so the caller
+     * MUST re-register. After MAX_RESPAWNS, `onDead()` fires once.
+     */
+    watch(onNewUrl, onDead) {
+        const arm = (proc) => {
+            proc.once("exit", () => {
+                if (this._closed)
+                    return;
+                void (async () => {
+                    this._respawns += 1;
+                    if (this._respawns > exports.MAX_RESPAWNS) {
+                        console.error(`[quick-tunnel] died ${this._respawns - 1} times — giving up. ` +
+                            "Node is no longer publicly reachable; restart `iicp-node serve` to recover.");
+                        onDead();
+                        return;
+                    }
+                    console.warn(`[quick-tunnel] exited unexpectedly — respawning (${this._respawns}/${exports.MAX_RESPAWNS})…`);
+                    let fresh;
+                    try {
+                        fresh = await openQuickTunnel(this.localPort, exports.TUNNEL_START_TIMEOUT_MS, this._binary);
+                    }
+                    catch (exc) {
+                        console.error(`[quick-tunnel] respawn failed: ${exc instanceof Error ? exc.message : exc}`);
+                        onDead();
+                        return;
+                    }
+                    // Adopt the fresh child; drop its own exit-hook (ours stays armed).
+                    process.removeListener("exit", fresh._exitHook);
+                    this.process = fresh.process;
+                    this.url = fresh.url;
+                    console.log(`[quick-tunnel] back up at ${this.url} — re-registering.`);
+                    arm(this.process);
+                    onNewUrl(this.url);
+                })();
+            });
+        };
+        arm(this.process);
+    }
+    /** Terminate the tunnel child. Idempotent; also runs on process exit. */
+    close() {
+        if (this._closed)
+            return;
+        this._closed = true;
+        process.removeListener("exit", this._exitHook);
+        if (this.process.exitCode === null && !this.process.killed) {
+            this.process.kill("SIGTERM");
+        }
+    }
+}
+exports.QuickTunnel = QuickTunnel;
+/**
+ * Spawn cloudflared and resolve with the running tunnel + its public URL.
+ * Rejects with INSTALL_HINT when the binary is absent, or a timeout error
+ * when no URL appears within `timeoutMs`.
+ */
+function openQuickTunnel(localPort, timeoutMs = exports.TUNNEL_START_TIMEOUT_MS, binary) {
+    return new Promise((resolve, reject) => {
+        const resolved = binary ?? cloudflaredPath();
+        if (!resolved) {
+            reject(new Error(exports.INSTALL_HINT));
+            return;
+        }
+        const proc = (0, node_child_process_1.spawn)(resolved, ["tunnel", "--url", `http://127.0.0.1:${localPort}`], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            proc.kill("SIGTERM");
+            reject(new Error(`cloudflared produced no tunnel URL within ${timeoutMs / 1000}s`));
+        }, timeoutMs);
+        const onChunk = (chunk) => {
+            if (settled)
+                return; // keep draining (streams stay flowing) but ignore
+            const m = URL_RE.exec(chunk.toString());
+            if (m) {
+                settled = true;
+                clearTimeout(timer);
+                console.log(`[quick-tunnel] up: ${m[0]} → http://127.0.0.1:${localPort}`);
+                resolve(new QuickTunnel(proc, m[0], localPort, resolved));
+            }
+        };
+        // cloudflared logs to stderr; read both to be version-proof. Attaching
+        // handlers keeps the pipes flowing so the child never blocks on a full pipe.
+        proc.stdout?.on("data", onChunk);
+        proc.stderr?.on("data", onChunk);
+        proc.once("exit", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(new Error(`cloudflared exited (code=${code}) before printing a tunnel URL`));
+        });
+        proc.once("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+//# sourceMappingURL=tunnel.js.map

package/dist/tunnel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.js","sourceRoot":"","sources":["../src/tunnel.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iicp/client",
-  "version": "0.7.54",
+  "version": "0.7.57",
   "description": "Official TypeScript/JavaScript SDK for the IICP protocol (ADR-016)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",