@linxin666/dsh-remote-web-ui 0.1.1 → 0.1.2

package/lib/types/tunnel.js

@@ -0,0 +1,222 @@
+/**
+ * Auto-tunnel manager: spawns a Cloudflare quick tunnel (`cloudflared
+ * tunnel --url <local>`) through the `cloudflared` npm package — its
+ * postinstall downloads the platform binary, so no user-side tooling is
+ * involved — surfaces the minted `https://xxx.trycloudflare.com` URL, and
+ * restarts the process after unexpected exits with exponential backoff.
+ *
+ * The cloudflared package's Tunnel is a thin spawn wrapper; this manager
+ * owns the lifecycle policy (binary readiness, URL timeout, restart
+ * backoff) around it. All seams — the tunnel factory, binary readiness,
+ * timers — are injectable so the whole lifecycle is unit-testable without
+ * a real binary or network.
+ */
+import { existsSync } from 'node:fs';
+import { bin, install, Tunnel } from 'cloudflared';
+/** Default binary readiness: download the platform binary on first use. */
+async function defaultEnsureBinary() {
+    if (existsSync(bin))
+        return;
+    await install(bin);
+}
+/** Default factory: the cloudflared package's quick tunnel (no account). */
+function defaultFactory(targetUrl) {
+    // `--no-autoupdate`: the binary must never upgrade itself out from under
+    // the manager (a self-updated binary would break the pinned lifecycle).
+    return Tunnel.quick(targetUrl, { '--no-autoupdate': true });
+}
+/** Node timers. */
+const nodeTimer = { setTimeout, clearTimeout };
+/**
+ * Own the lifecycle of one auto-tunnel: start/stop, URL surfacing, and
+ * crash-restart backoff.
+ */
+export class TunnelManager {
+    factory;
+    ensureBinary;
+    urlTimeoutMs;
+    restartBaseMs;
+    restartMaxMs;
+    timer;
+    phase = 'stopped';
+    url;
+    error;
+    targetUrl;
+    handle;
+    urlTimer;
+    restartTimer;
+    attempts = 0;
+    stopping = false;
+    urlListeners = new Set();
+    phaseListeners = new Set();
+    /**
+     * @param options - seams; defaults spawn the real quick tunnel.
+     */
+    constructor(options = {}) {
+        this.factory = options.factory ?? defaultFactory;
+        this.ensureBinary = options.ensureBinary ?? defaultEnsureBinary;
+        this.urlTimeoutMs = options.urlTimeoutMs ?? 30_000;
+        this.restartBaseMs = options.restartBaseMs ?? 5_000;
+        this.restartMaxMs = options.restartMaxMs ?? 60_000;
+        this.timer = options.timer ?? nodeTimer;
+    }
+    /** The current status frame. */
+    get info() {
+        return {
+            phase: this.phase,
+            ...(this.url !== undefined ? { url: this.url } : {}),
+            ...(this.error !== undefined ? { error: this.error } : {}),
+        };
+    }
+    /**
+     * Start (or keep) a quick tunnel toward `targetUrl`. Restarting with a
+     * different target tears the old tunnel down first; restarting with the
+     * same target while running is a no-op.
+     * @param targetUrl - the local URL to expose, e.g. `http://127.0.0.1:3080`.
+     */
+    start(targetUrl) {
+        if (this.targetUrl === targetUrl && (this.phase === 'starting' || this.phase === 'running'))
+            return;
+        this.teardown();
+        this.stopping = false;
+        this.targetUrl = targetUrl;
+        this.attempts = 0;
+        this.attempt();
+    }
+    /** Stop the tunnel for good: no restarts, no state. */
+    stop() {
+        this.teardown();
+        this.stopping = false;
+        this.targetUrl = undefined;
+        this.setPhase('stopped');
+    }
+    /** Alias of {@link stop} for plugin-effect disposal. */
+    dispose() {
+        this.stop();
+    }
+    /** Subscribe to minted tunnel URLs (fire-and-forget duplicates dropped). */
+    onUrl(listener) {
+        this.urlListeners.add(listener);
+        return () => { this.urlListeners.delete(listener); };
+    }
+    /** Subscribe to every phase change. */
+    onPhase(listener) {
+        this.phaseListeners.add(listener);
+        return () => { this.phaseListeners.delete(listener); };
+    }
+    attempt() {
+        if (this.stopping || this.targetUrl === undefined)
+            return;
+        this.setPhase('starting');
+        this.handle = undefined;
+        this.url = undefined;
+        this.error = undefined;
+        void this.ensureBinary().then(() => {
+            if (this.stopping || this.targetUrl === undefined)
+                return;
+            const handle = this.factory(this.targetUrl);
+            this.handle = handle;
+            this.urlTimer = this.timer.setTimeout(() => {
+                // The tunnel never reported a URL: kill it and retry with backoff.
+                this.fail('timed out waiting for the tunnel URL');
+            }, this.urlTimeoutMs);
+            handle.on('url', (value) => {
+                if (this.handle !== handle)
+                    return;
+                this.handleUrl(value);
+            });
+            handle.on('exit', () => {
+                if (this.handle !== handle)
+                    return;
+                this.handleExit();
+            });
+            handle.on('error', (value) => {
+                // Spawn/connection errors usually precede an exit; the exit path owns
+                // restart, this only records diagnostics while the process still lives.
+                if (this.handle !== handle || this.phase !== 'starting')
+                    return;
+                this.error = value instanceof Error ? value.message : String(value);
+            });
+        }).catch((value) => {
+            // Binary install failed (no network, no platform build): report it.
+            if (this.stopping || this.targetUrl === undefined)
+                return;
+            const message = value instanceof Error ? value.message : String(value);
+            this.fail(`could not obtain the cloudflared binary: ${message}`);
+        });
+    }
+    handleUrl(value) {
+        if (this.urlTimer !== undefined) {
+            this.timer.clearTimeout(this.urlTimer);
+            this.urlTimer = undefined;
+        }
+        this.url = value;
+        this.error = undefined;
+        this.attempts = 0;
+        this.setPhase('running');
+        for (const listener of this.urlListeners) {
+            try {
+                listener(value);
+            }
+            catch {
+                // A throwing subscriber must not break the emit loop.
+            }
+        }
+    }
+    handleExit() {
+        // The exit handler is detached during teardown, so reaching this point
+        // means an unexpected death: fail the current phase and schedule a retry.
+        if (this.stopping)
+            return;
+        this.fail('the tunnel process exited unexpectedly');
+    }
+    fail(message) {
+        if (this.stopping)
+            return;
+        this.url = undefined;
+        this.error = message;
+        if (this.handle !== undefined) {
+            this.handle.stop();
+            this.handle = undefined;
+        }
+        if (this.urlTimer !== undefined) {
+            this.timer.clearTimeout(this.urlTimer);
+            this.urlTimer = undefined;
+        }
+        this.setPhase('failed');
+        this.attempts += 1;
+        const delay = Math.min(this.restartBaseMs * 2 ** (this.attempts - 1), this.restartMaxMs);
+        this.restartTimer = this.timer.setTimeout(() => {
+            this.restartTimer = undefined;
+            this.attempt();
+        }, delay);
+    }
+    /** Stop the current process and cancel every pending timer (no phase change). */
+    teardown() {
+        this.stopping = true;
+        if (this.urlTimer !== undefined) {
+            this.timer.clearTimeout(this.urlTimer);
+            this.urlTimer = undefined;
+        }
+        if (this.restartTimer !== undefined) {
+            this.timer.clearTimeout(this.restartTimer);
+            this.restartTimer = undefined;
+        }
+        if (this.handle !== undefined) {
+            this.handle.stop();
+            this.handle = undefined;
+        }
+    }
+    setPhase(phase) {
+        this.phase = phase;
+        const info = this.info;
+        for (const listener of this.phaseListeners) {
+            try {
+                listener(info);
+            }
+            catch {
+                // A throwing subscriber must not break the emit loop.
+            }
+        }
+    }
+}

package/lib/types/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,7 +1,7 @@
 {
   "name": "@linxin666/dsh-remote-web-ui",
   "description": "Mobile remote control for the dsh web GUI: scan-to-pair QR entry beside the settings button, one-time pairing tokens, live device status, and revocable mobile sessions",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
@@ -25,11 +25,10 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/client.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
+    "lib/**/*.js",
+    "lib/**/*.js.map",
+    "lib/**/*.d.ts",
+    "lib/**/*.d.ts.map",
     "src",
     "cordis.patch.yml"
   ],
@@ -96,6 +95,10 @@
     "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.1.8"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zhu1090093659/dsh-web-ui.git"
+  },
   "scripts": {
     "build": "tsc -b && tsdown",
     "test": "vitest run",