@urateam/cli 0.1.41 → 0.1.43

package/dist/lib/tunnel.js

@@ -0,0 +1,245 @@
+/**
+ * `ura start --tunnel <mode>` runtime: wraps `cloudflared` as a child process.
+ *
+ * Two modes:
+ *   - "cloudflare-quick": `cloudflared tunnel --url http://localhost:<port>`.
+ *     Cloudflare assigns a random `*.trycloudflare.com` URL, which is parsed
+ *     out of cloudflared's stderr.
+ *   - "cloudflare-token": `cloudflared tunnel --token <token> run`. Operator
+ *     has already configured a named tunnel in Cloudflare; the public URL
+ *     is known ahead of time and must be passed via `opts.publicUrl` /
+ *     `URATEAM_PUBLIC_URL`.
+ *
+ * Restart-on-exit: the child is supervised with exponential-backoff retries
+ * (default 1s → 2s → 4s ... capped at 30s, max 10 attempts). On `stop()`
+ * the supervisor cancels any pending retry timer and SIGTERMs the child.
+ *
+ * All I/O is injectable for tests; the real `spawn` is only invoked when the
+ * caller doesn't override `opts.spawn`.
+ */
+import { spawn as realSpawn, } from "node:child_process";
+import { EventEmitter } from "node:events";
+/** Cloudflare quick-tunnel stderr line we parse the URL out of. */
+const QUICK_URL_REGEX = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+/**
+ * Thrown when the `cloudflared` binary isn't installed (ENOENT on spawn).
+ * Carries an install hint so the start command can render an actionable
+ * error.
+ */
+export class CloudflaredMissingError extends Error {
+    constructor() {
+        super("cloudflared binary not found. Install it:\n" +
+            "  macOS:  brew install cloudflared\n" +
+            "  Linux:  https://pkg.cloudflare.com/index.html (apt/yum)\n" +
+            "  Other:  https://github.com/cloudflare/cloudflared/releases");
+        this.name = "CloudflaredMissingError";
+    }
+}
+export class TunnelManager extends EventEmitter {
+    opts;
+    child = null;
+    restartCount = 0;
+    shuttingDown = false;
+    restartTimer = null;
+    publicUrl = null;
+    spawnFn;
+    initialRestartDelayMs;
+    maxRestartDelayMs;
+    maxRestartAttempts;
+    urlDetectTimeoutMs;
+    log;
+    constructor(opts) {
+        super();
+        this.opts = opts;
+        this.spawnFn = opts.spawn ?? realSpawn;
+        this.initialRestartDelayMs = opts.initialRestartDelayMs ?? 1000;
+        this.maxRestartDelayMs = opts.maxRestartDelayMs ?? 30000;
+        this.maxRestartAttempts = opts.maxRestartAttempts ?? 10;
+        this.urlDetectTimeoutMs = opts.urlDetectTimeoutMs ?? 30000;
+        this.log = opts.log ?? ((m) => console.log(m));
+    }
+    /**
+     * Start the tunnel. Resolves with the detected (quick) or pre-configured
+     * (token) public URL. Throws `CloudflaredMissingError` on ENOENT.
+     */
+    async start() {
+        if (this.opts.mode === "cloudflare-token") {
+            if (!this.opts.token) {
+                throw new Error("TunnelManager: cloudflare-token mode requires `token` (or CLOUDFLARE_TUNNEL_TOKEN env var)");
+            }
+            if (!this.opts.publicUrl) {
+                throw new Error("TunnelManager: cloudflare-token mode requires `publicUrl` (or URATEAM_PUBLIC_URL env var)");
+            }
+            this.publicUrl = this.opts.publicUrl;
+        }
+        const url = await this.spawnAndDetectUrl();
+        this.publicUrl = url;
+        return { publicUrl: url, restartCount: this.restartCount };
+    }
+    /**
+     * Stop the tunnel. Cancels any pending restart, SIGTERMs the child, and
+     * awaits the exit. Subsequent restarts (e.g. an exit fired during
+     * shutdown) are skipped.
+     */
+    async stop() {
+        this.shuttingDown = true;
+        if (this.restartTimer) {
+            clearTimeout(this.restartTimer);
+            this.restartTimer = null;
+        }
+        if (this.child && this.child.exitCode === null && !this.child.killed) {
+            const exited = new Promise((resolve) => {
+                this.child.once("exit", () => resolve());
+            });
+            this.child.kill("SIGTERM");
+            await exited;
+        }
+    }
+    buildArgs() {
+        if (this.opts.mode === "cloudflare-quick") {
+            return [
+                "tunnel",
+                "--no-autoupdate",
+                "--url",
+                `http://localhost:${this.opts.localPort}`,
+            ];
+        }
+        return [
+            "tunnel",
+            "--no-autoupdate",
+            "run",
+            "--token",
+            this.opts.token,
+        ];
+    }
+    spawnChild() {
+        const spawnOpts = { stdio: ["ignore", "pipe", "pipe"] };
+        try {
+            return this.spawnFn("cloudflared", this.buildArgs(), spawnOpts);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw new CloudflaredMissingError();
+            }
+            throw err;
+        }
+    }
+    async spawnAndDetectUrl() {
+        return new Promise((resolve, reject) => {
+            let child;
+            try {
+                child = this.spawnChild();
+            }
+            catch (err) {
+                reject(err);
+                return;
+            }
+            // Synchronous ENOENT surfaces as an "error" event on the child, not as
+            // a throw — cover both paths.
+            const onError = (err) => {
+                if (err.code === "ENOENT") {
+                    reject(new CloudflaredMissingError());
+                }
+                else {
+                    reject(err);
+                }
+            };
+            child.once("error", onError);
+            this.child = child;
+            this.wireSupervisor(child);
+            if (this.opts.mode === "cloudflare-token") {
+                // We already have a static publicUrl; the spawn either succeeds or
+                // exits — the supervisor handles both. Resolve immediately.
+                resolve(this.opts.publicUrl);
+                return;
+            }
+            const urlTimer = setTimeout(() => {
+                reject(new Error(`TunnelManager: did not see a *.trycloudflare.com URL within ${this.urlDetectTimeoutMs}ms`));
+            }, this.urlDetectTimeoutMs);
+            const onStderr = (chunk) => {
+                const text = chunk.toString();
+                const match = text.match(QUICK_URL_REGEX);
+                if (match) {
+                    clearTimeout(urlTimer);
+                    child.stderr?.removeListener("data", onStderr);
+                    this.log(`🌐 Public URL: ${match[0]}`);
+                    resolve(match[0]);
+                }
+            };
+            child.stderr?.on("data", onStderr);
+        });
+    }
+    /**
+     * Wire the supervisor: on unexpected exit, schedule a restart with
+     * exponential backoff. Caps at `maxRestartAttempts` then emits "error".
+     */
+    wireSupervisor(child) {
+        child.once("exit", (code, signal) => {
+            this.child = null;
+            this.emit("stopped", {
+                exitCode: code,
+                signal,
+                restartCount: this.restartCount,
+            });
+            if (this.shuttingDown)
+                return;
+            if (this.restartCount >= this.maxRestartAttempts) {
+                this.emit("error", new Error(`TunnelManager: cloudflared exited ${this.restartCount} times in a row; giving up`));
+                return;
+            }
+            const delay = Math.min(this.initialRestartDelayMs * 2 ** this.restartCount, this.maxRestartDelayMs);
+            this.log(`tunnel: cloudflared exited (code=${code}, signal=${signal}); restart #${this.restartCount + 1} in ${delay}ms`);
+            this.restartTimer = setTimeout(() => {
+                this.restartTimer = null;
+                this.restartCount += 1;
+                this.restart().catch((err) => this.emit("error", err));
+            }, delay);
+        });
+    }
+    async restart() {
+        if (this.shuttingDown)
+            return;
+        if (this.opts.mode === "cloudflare-quick") {
+            try {
+                const url = await this.spawnAndDetectUrl();
+                this.publicUrl = url;
+                this.emit("started", {
+                    publicUrl: url,
+                    restartCount: this.restartCount,
+                });
+            }
+            catch (err) {
+                this.emit("error", err);
+            }
+            return;
+        }
+        // token mode: spawn child; publicUrl is already known.
+        try {
+            const child = this.spawnChild();
+            this.child = child;
+            this.wireSupervisor(child);
+            this.emit("started", {
+                publicUrl: this.publicUrl,
+                restartCount: this.restartCount,
+            });
+        }
+        catch (err) {
+            this.emit("error", err);
+        }
+    }
+    /** Currently-known public URL, or null before `start()`. */
+    getPublicUrl() {
+        return this.publicUrl;
+    }
+    /**
+     * Total restart attempts made since `start()`. Never resets within the
+     * lifetime of a single TunnelManager — so even a long stable period
+     * followed by a single new failure still incurs the cap-tier delay.
+     * Operators who care can construct a fresh manager. Used by the
+     * `tunnel.stopped` audit event to attribute flap loops correctly.
+     */
+    getRestartCount() {
+        return this.restartCount;
+    }
+}
+//# sourceMappingURL=tunnel.js.map

package/dist/lib/tunnel.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urateam/cli",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "license": "BUSL-1.1",
   "type": "module",
   "main": "dist/index.js",
@@ -23,8 +23,8 @@
     "commander": "^13.1.0",
     "postgres": "^3.4.0",
     "zod": "^4.3.6",
-    "@urateam/core": "0.1.39",
-    "@urateam/dashboard": "0.1.39"
+    "@urateam/core": "0.1.41",
+    "@urateam/dashboard": "0.1.41"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",