instar 1.2.35 → 1.2.37

package/dist/tunnel/TunnelManager.d.ts

@@ -1,46 +1,68 @@
 /**
- * Cloudflare Tunnel manager for Instar agents.
+ * TunnelManager — single owner of the tunnel lifecycle.
  *
- * Manages cloudflared tunnel lifecycle — quick tunnels (zero-config,
- * ephemeral) and named tunnels (persistent, custom domain).
+ * Per spec specs/dev-infrastructure/tunnel-failure-resilience.md.
  *
- * Quick tunnels require no Cloudflare account. Named tunnels require
- * a tunnel token from the Cloudflare dashboard.
+ * Rewritten on top of the foundation modules:
+ *   - TunnelProvider — backend abstraction; concrete providers under
+ *     src/tunnel/Cloudflare*Provider.ts.
+ *   - TunnelLifecycle — single-writer CAS-guarded state machine.
+ *   - TunnelNotifier — two-channel routing (group / owner-DM) of
+ *     transition events.
  *
- * The tunnel exposes the agent's local HTTP server to the internet,
- * enabling:
- *   - Private content viewing (auth-gated rendered markdown)
- *   - Remote API access from anywhere
- *   - File serving (logs, reports, exports)
- *   - Webhook endpoints for external integrations
+ * The manager is the SOLE owner of the detect → attempt → fall-back →
+ * notify → self-heal lifecycle. The previous server.ts startup-retry
+ * ladder + background-retry ladder + Lifeline failure message are
+ * retired in favor of routing all retry through here (one backoff
+ * engine, not two).
+ *
+ * Scope of this rewrite (PR 2 of the chain):
+ *   - Tier-1 provider pool (Cloudflare named → quick) with internal
+ *     backoff between retries within an episode.
+ *   - Post-start reachability probe (HTTP /health through the public
+ *     URL) before declaring `active` — prevents broadcasting a "back
+ *     online" link that doesn't actually serve traffic.
+ *   - Backward-compatible public API: start(), stop(), forceStop(),
+ *     enableAutoReconnect(), disableAutoReconnect(), getExternalUrl(),
+ *     url/isRunning/state. Plus the existing events.
+ *   - Notifier sink optional; when telegram adapter is plumbed,
+ *     transition events route to the group topic.
+ *
+ * Out of scope for THIS PR (future PRs in the chain):
+ *   - Tier-2 consent flow + relay providers (PR 4).
+ *   - Owner-DM channel + inline-button consent UX (PR 3).
+ *   - authToken/PIN rotation + boot recovery (PR 5).
+ *   - Self-heal probe with N-consecutive-success stability gate (PR 6).
+ *   - The /tunnel route (PR 7).
+ *
+ * The lifecycle state machine already supports these states; the
+ * manager simply doesn't transition into them yet in PR 2.
  */
 import { EventEmitter } from 'node:events';
+import { type PersistedTunnelState } from './TunnelLifecycle.js';
+import type { TunnelProvider, ProviderFailureReason } from './TunnelProvider.js';
+import type { NotifierSink } from './TunnelNotifier.js';
 export interface TunnelConfig {
-    /** Whether tunnel is enabled */
+    /** Whether tunnel is enabled. */
     enabled: boolean;
-    /** Tunnel type: 'quick' (ephemeral, no account) or 'named' (persistent, requires token) */
+    /** Tunnel type: 'quick' (ephemeral, no account) or 'named' (persistent, requires token). */
     type: 'quick' | 'named';
-    /** Cloudflare tunnel token (required for named tunnels using token auth) */
+    /** Cloudflare tunnel token (named, token-auth). */
     token?: string;
-    /** Config file path for named tunnels using credentials file auth */
+    /** Config file path (named, config-file-auth). */
     configFile?: string;
-    /** Public hostname for named tunnels (e.g., echo.dawn-tunnel.dev) */
+    /** Public hostname for named tunnels. */
     hostname?: string;
-    /** Local port to tunnel to */
+    /** Local port to tunnel to. */
     port: number;
-    /** State directory for persisting tunnel info */
+    /** State directory for persisting tunnel.json. */
     stateDir: string;
 }
 export interface TunnelState {
-    /** Current tunnel URL (null if not connected) */
     url: string | null;
-    /** Tunnel type */
     type: 'quick' | 'named';
-    /** When the tunnel was started */
     startedAt: string | null;
-    /** Connection info from cloudflared */
     connectionId?: string;
-    /** Connection location */
     connectionLocation?: string;
 }
 export interface TunnelEvents {
@@ -54,60 +76,75 @@ export interface TunnelEvents {
     error: (error: Error) => void;
     stopped: () => void;
 }
+/** Optional injections for testability. */
+export interface TunnelManagerInjections {
+    providers?: TunnelProvider[];
+    notifierSink?: NotifierSink;
+    fetch?: typeof fetch;
+}
 export declare class TunnelManager extends EventEmitter {
-    private config;
-    private tunnel;
-    private stateFile;
-    private _state;
-    private _stopped;
+    private readonly config;
+    private readonly stateFile;
+    private readonly lifecycle;
+    private readonly providers;
+    private readonly notifier;
+    private readonly fetcher;
+    private currentHandle;
+    private currentProviderName;
+    private _legacyState;
     private _autoReconnect;
-    private _reconnectTimer;
-    private _reconnectAttempt;
+    private _stopped;
     private _startPromise;
-    private static readonly MAX_RECONNECT_ATTEMPTS;
-    private static readonly BASE_RECONNECT_DELAY_MS;
-    private static readonly MAX_RECONNECT_DELAY_MS;
-    constructor(config: TunnelConfig);
-    /** Current tunnel URL, or null if not connected */
+    private _backoffAttempt;
+    private _backoffTimer;
+    private _postExhaustedTimer;
+    constructor(config: TunnelConfig, injections?: TunnelManagerInjections);
     get url(): string | null;
-    /** Whether the tunnel is currently running */
     get isRunning(): boolean;
-    /** Current tunnel state */
     get state(): TunnelState;
+    /** Additive new accessor — lifecycle snapshot. */
+    get lifecycleState(): PersistedTunnelState;
     /**
-     * Start the tunnel. Ensures the cloudflared binary is installed,
-     * then starts the appropriate tunnel type.
+     * Start the tunnel. Drives the full Tier-1 ladder internally — the
+     * caller does NOT wrap with its own retry loop (the old server.ts
+     * startup ladder is RETIRED).
+     *
+     * Resolves with the URL of the first provider that reaches `active`.
+     * Rejects when all Tier-1 providers fail and backoff is exhausted.
      */
     start(): Promise<string>;
-    /**
-     * Stop the tunnel gracefully. Intentional stops disable auto-reconnect.
-     */
     stop(): Promise<void>;
-    /**
-     * Force-stop the tunnel with a timeout. If cloudflared doesn't respond to
-     * SIGINT within `timeoutMs`, escalate to SIGKILL. Essential for sleep/wake
-     * recovery where cloudflared may be a zombie process.
-     */
-    forceStop(timeoutMs?: number): Promise<void>;
-    /**
-     * Enable automatic reconnection when the tunnel disconnects unexpectedly.
-     * Uses exponential backoff: 5s, 10s, 20s, ... up to 5 minutes, max 10 attempts.
-     */
+    /** Force-stop with escalation. Providers internally do SIGINT → SIGKILL. */
+    forceStop(_timeoutMs?: number): Promise<void>;
     enableAutoReconnect(): void;
     disableAutoReconnect(): void;
+    getExternalUrl(localPath: string): string | null;
+    private buildDefaultPool;
+    private doStart;
+    private driveTier1;
+    private exhaustedOrBackoff;
     /**
-     * Attempt to reconnect the tunnel with exponential backoff.
+     * Background retry — runs the bounded exponential ladder off the
+     * start() promise so initial start() resolves/rejects fast. After
+     * the ladder exhausts, hands off to the indefinite post-exhausted
+     * placeholder (the PR 2 self-heal; PR 6 replaces with the spec's
+     * N-consecutive-success probe).
      */
-    private attemptReconnect;
+    private scheduleBackgroundRetry;
+    private clearBackoffTimer;
+    private clearPostExhaustedTimer;
     /**
-     * Get the full external URL for a local path.
-     * Returns null if tunnel is not connected.
+     * Minimum-viable post-exhausted retry (PR 2 self-heal placeholder).
+     * Schedules a single low-frequency probe; on completion (success or
+     * failure) it re-arms itself, so the agent keeps trying to recover
+     * even after the bounded startup-reconnect ladder gives up. PR 6
+     * replaces this with the spec's N-consecutive-success stability gate.
      */
-    getExternalUrl(localPath: string): string | null;
-    private ensureBinary;
-    private startQuickTunnel;
-    private startNamedTunnel;
-    private startConfigFileTunnel;
-    private saveState;
+    private schedulePostExhaustedRetry;
+    /** HTTP probe through the public URL — confirms the link actually serves. */
+    private probeReachability;
+    private persist;
+    private restorePersisted;
 }
+export type { ProviderFailureReason };
 //# sourceMappingURL=TunnelManager.d.ts.map

package/dist/tunnel/TunnelManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TunnelManager.d.ts","sourceRoot":"","sources":["../../src/tunnel/TunnelManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQ3C,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,2FAA2F;IAC3F,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACxB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,kBAAkB;IAClB,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACxB,kCAAkC;IAClC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,SAAS,EAAE,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACxE,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAID,qBAAa,aAAc,SAAQ,YAAY;IAC7C,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,eAAe,CAA8C;IACrE,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAM;IACpD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IACxD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAc;gBAEhD,MAAM,EAAE,YAAY;IAWhC,mDAAmD;IACnD,IAAI,GAAG,IAAI,MAAM,GAAG,IAAI,CAEvB;IAED,8CAA8C;IAC9C,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,2BAA2B;IAC3B,IAAI,KAAK,IAAI,WAAW,CAEvB;IAED;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAyC9B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B;;;;OAIG;IACG,SAAS,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAuDhD;;;OAGG;IACH,mBAAmB,IAAI,IAAI;IAI3B,oBAAoB,IAAI,IAAI;IAS5B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA+BxB;;;OAGG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;YASlC,YAAY;IAM1B,OAAO,CAAC,gBAAgB;IA2ExB,OAAO,CAAC,gBAAgB;IAuExB,OAAO,CAAC,qBAAqB;IAyF7B,OAAO,CAAC,SAAS;CAWlB"}
+{"version":3,"file":"TunnelManager.d.ts","sourceRoot":"","sources":["../../src/tunnel/TunnelManager.ts"],"names":[],"mappings":"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"}