@desplega.ai/qa-use 2.14.1 → 2.15.1

package/dist/lib/tunnel/index.js

@@ -3,6 +3,7 @@ import https from 'node:https';
 import { URL } from 'node:url';
 import localtunnel from '@desplega.ai/localtunnel';
 import { getEnv } from '../env/index.js';
+import { classifyTunnelFailure, TunnelError } from './errors.js';
 export class TunnelManager {
     session = null;
     defaultRegion = 'auto';
@@ -42,22 +43,36 @@ export class TunnelManager {
         if (!subdomain && options.apiKey !== undefined && options.sessionIndex !== undefined) {
             // Use deterministic subdomain based on API key and session index
             subdomain = TunnelManager.generateDeterministicSubdomain(options.apiKey, options.sessionIndex);
-            console.log(`Using deterministic subdomain: ${subdomain}`);
+            console.error(`Using deterministic subdomain: ${subdomain}`);
         }
         else if (!subdomain) {
             // Fallback to timestamp-based random subdomain
             subdomain = `qa-use-${Date.now().toString().slice(-6)}`;
-            console.log(`Using random subdomain: ${subdomain}`);
+            console.error(`Using random subdomain: ${subdomain}`);
         }
-        console.log(`Starting tunnel on port ${port} with host ${host} in region ${region}`);
-        const tunnel = await localtunnel({
-            port,
-            host,
-            subdomain,
-            local_host: options.localHost || 'localhost',
-            auth: true,
-        });
-        console.log(`Tunnel started at ${tunnel.url}`);
+        console.error(`Starting tunnel on port ${port} with host ${host} in region ${region}`);
+        let tunnel;
+        try {
+            tunnel = await localtunnel({
+                port,
+                host,
+                subdomain,
+                local_host: options.localHost || 'localhost',
+                auth: true,
+            });
+        }
+        catch (err) {
+            // Classify provider errors into structured TunnelError subclasses so
+            // the CLI can render a triage-hint message. Zero retries here —
+            // surface the failure immediately.
+            const classified = err instanceof TunnelError
+                ? err
+                : classifyTunnelFailure(err, {
+                    target: `${options.localHost || 'localhost'}:${port}`,
+                });
+            throw classified;
+        }
+        console.error(`Tunnel started at ${tunnel.url}`);
         this.session = {
             tunnel,
             publicUrl: tunnel.url,

package/dist/lib/tunnel/index.js.map

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

package/dist/lib/tunnel/registry.d.ts

@@ -0,0 +1,182 @@
+/**
+ * TunnelRegistry — a shared, refcount-managed layer over `TunnelManager`.
+ *
+ * Goals:
+ *   - Two CLI commands targeting the same localhost base URL share one
+ *     remote tunnel (one public URL, one provider connection).
+ *   - State is visible and editable across sibling processes via
+ *     `~/.qa-use/tunnels/<hash>.json`, so a SECOND process targeting the
+ *     same localhost picks up the FIRST process's public URL rather than
+ *     spinning up its own tunnel.
+ *   - Last-releaser (in the OWNER process) keeps the tunnel alive for
+ *     `GRACE_MS` (30 s default) so rapid-fire invocations do not thrash
+ *     the provider.
+ *
+ * Cross-process coordination model:
+ *   - The process that first acquires a given target becomes the OWNER
+ *     and runs the in-process `TunnelManager`. Its PID is recorded in
+ *     the registry file.
+ *   - Later acquirers in OTHER processes read the file, see an alive
+ *     owner PID, increment refcount under a lockfile, and return an
+ *     "attach" handle (`isCrossProcessAttach: true`) with the owner's
+ *     `publicUrl`. They do NOT construct a `TunnelManager`.
+ *   - Read-modify-write of the record is guarded by a lockfile
+ *     (`<hash>.lock`, `O_EXCL | O_CREAT`) with bounded retry.
+ *
+ * TTL grace limitation:
+ *   - The grace window is bounded by the OWNER process's lifetime. Since
+ *     `TunnelManager` is a per-process localtunnel client, the remote
+ *     tunnel dies when the owner exits. For long-lived owners
+ *     (`tunnel start --hold`, a running `test run`, a detached
+ *     `browser create` from Phase 4) grace works as designed: a new
+ *     acquirer within `GRACE_MS` cancels tear-down. For short-lived
+ *     commands that release-and-exit immediately, grace collapses to
+ *     zero (the owner process is gone, so there is no tunnel to keep
+ *     alive anyway).
+ *
+ * Non-goals (this phase):
+ *   - Daemonised tunnel hosts. Phase 4 adds detach so short-lived
+ *     commands can leave a long-lived owner behind.
+ *   - Retries on provider failure. Zero retries, consistent with Phase 2.
+ */
+import { TunnelManager, type TunnelOptions } from './index.js';
+/**
+ * How long (ms) to keep a tunnel alive after its refcount hits zero.
+ * A new `acquire()` within this window reuses the existing tunnel.
+ * Overridable via `QA_USE_TUNNEL_GRACE_MS` env var (primarily a
+ * test-friendly knob; production callers should stick with the default).
+ */
+export declare const GRACE_MS = 30000;
+/**
+ * Max concurrent tunnels per API key. Mirrors the sessionIndex clamp at
+ * `lib/tunnel/index.ts:41` so we surface a clear error instead of silently
+ * colliding on subdomains.
+ */
+export declare const MAX_CONCURRENT_TUNNELS = 10;
+/** On-disk schema for a registry entry. */
+export interface TunnelRecord {
+    id: string;
+    target: string;
+    publicUrl: string;
+    pid: number;
+    refcount: number;
+    ttlExpiresAt: number | null;
+    startedAt: number;
+}
+/**
+ * Handle returned by `acquire()` / kept in memory by consumers.
+ *
+ * Consumers must call `registry.release(handle)` exactly once per
+ * `acquire()` call.
+ */
+export interface TunnelHandle extends TunnelRecord {
+    /**
+     * True when this handle was acquired from a foreign process's tunnel
+     * (the registry file's `pid` !== `process.pid`). The caller MUST NOT
+     * attempt to retrieve a `TunnelManager` via `getLiveManager(target)` —
+     * there isn't one in this process. Use `handle.publicUrl` directly.
+     */
+    isCrossProcessAttach: boolean;
+    /**
+     * Internal marker used to guard double-release. Not persisted.
+     */
+    _released?: boolean;
+}
+/**
+ * Canonical target key — used both as the map key and to derive the
+ * filename hash. We lowercase the hostname and drop any path/query so
+ * `http://Localhost:3000/foo` and `http://localhost:3000/` dedupe.
+ */
+export declare function canonicalTarget(target: string): string;
+/** Filename hash for a target. First 10 hex chars of sha256. */
+export declare function targetHash(target: string): string;
+/**
+ * Hook used by tests to inject a fake `TunnelManager` without booting a
+ * real tunnel. When unset (the default) the registry constructs a real
+ * `TunnelManager`.
+ */
+export type TunnelManagerFactory = () => TunnelManager;
+export interface TunnelRegistryOptions {
+    /** Override factory (tests). */
+    managerFactory?: TunnelManagerFactory;
+    /** Override grace window (tests). */
+    graceMs?: number;
+    /** Override concurrency cap (tests). */
+    maxConcurrent?: number;
+    /** Options threaded into `TunnelManager.startTunnel(...)`. */
+    tunnelOptions?: TunnelOptions;
+}
+/**
+ * Acquire / release / list API for tunnels.
+ *
+ * A singleton is exported as `tunnelRegistry` below for convenience;
+ * callers that need isolation (tests) construct their own instance.
+ */
+export declare class TunnelRegistry {
+    private readonly live;
+    private readonly graceMs;
+    private readonly maxConcurrent;
+    private readonly managerFactory;
+    constructor(opts?: TunnelRegistryOptions);
+    /**
+     * Start a tunnel for `target` (or reuse an existing one — in-process
+     * OR in a sibling process), returning a handle. Caller must pair each
+     * acquire with exactly one `release(handle)`.
+     */
+    acquire(target: string, opts?: TunnelOptions): Promise<TunnelHandle>;
+    /**
+     * Release a handle. Decrements refcount (under lock). When the
+     * refcount hits zero AND we are the owner, schedule a tear-down
+     * `graceMs` later. A subsequent `acquire()` within the grace window
+     * cancels the tear-down.
+     *
+     * Grace window is bounded by owner process lifetime — short-lived
+     * commands exit before grace expires and will tear down immediately.
+     */
+    release(handle: TunnelHandle): Promise<void>;
+    /**
+     * Force teardown of a tunnel regardless of refcount. Used by
+     * `qa-use tunnel close`. Safe to call when no such tunnel exists.
+     *
+     * If the owner is this process, tears down the in-memory manager.
+     * Otherwise just removes the registry file (and leaves the orphan
+     * remote tunnel to die with its owner).
+     */
+    forceClose(target: string): Promise<void>;
+    /**
+     * Look up a single entry by canonical target. Scans the on-disk
+     * registry; returns `null` if no record exists or the owning pid is
+     * dead.
+     */
+    get(target: string): TunnelRecord | null;
+    /**
+     * List all live entries. Reconciles against owning PID; stale entries
+     * are removed as a side-effect.
+     */
+    list(): TunnelRecord[];
+    /**
+     * Returns the live `TunnelManager` instance for `target` IF this process
+     * currently owns it. Used by callers that need health-check / WS-URL
+     * helpers on the underlying manager. Returns `null` for targets owned
+     * by a different process (file visible via `list()` / `get()` but not
+     * live in-memory here).
+     */
+    getLiveManager(target: string): TunnelManager | null;
+    /**
+     * Look up by filename hash (e.g. output of `tunnel ls`).
+     */
+    getByHash(hash: string): TunnelRecord | null;
+    private writeRecord;
+    /**
+     * Timer callback: re-check under lock whether we should tear down. A
+     * concurrent acquire may have bumped refcount back above zero.
+     */
+    private maybeTeardown;
+    /**
+     * Unconditional tear-down. Callers must hold the per-target lock.
+     */
+    private teardown;
+}
+/** Module-level singleton for CLI use. */
+export declare const tunnelRegistry: TunnelRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/lib/tunnel/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../lib/tunnel/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AASH,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,QAAS,CAAC;AAU/B;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD;;;;;OAKG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD;AA+GD;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,aAAa,CAAC;AAEvD,MAAM,WAAW,qBAAqB;IACpC,gCAAgC;IAChC,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgC;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuB;gBAE1C,IAAI,GAAE,qBAA0B;IAM5C;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAsH9E;;;;;;;;OAQG;IACG,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAsDlD;;;;;;;OAOG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C;;;;OAIG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAaxC;;;OAGG;IACH,IAAI,IAAI,YAAY,EAAE;IA2BtB;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAMpD;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAe5C,OAAO,CAAC,WAAW;IAKnB;;;OAGG;YACW,aAAa;IA0D3B;;OAEG;YACW,QAAQ;CAoBvB;AAED,0CAA0C;AAC1C,eAAO,MAAM,cAAc,gBAAuB,CAAC"}