@openparachute/hub 0.6.1-rc.4 → 0.6.2

package/src/commands/expose-cloudflare.ts

@@ -1,7 +1,19 @@
 import { spawnSync } from "node:child_process";
 import { mkdirSync, openSync } from "node:fs";
 import { dirname } from "node:path";
-import { DEFAULT_TUNNEL_NAME, cloudflaredPathsFor, writeConfig } from "../cloudflare/config.ts";
+import {
+  DEFAULT_TUNNEL_NAME,
+  cloudflaredPathsFor,
+  deriveTunnelName,
+  writeConfig,
+} from "../cloudflare/config.ts";
+import {
+  type ConnectorServiceDeps,
+  type InstallResult,
+  type RemoveResult,
+  installConnectorService,
+  removeConnectorService,
+} from "../cloudflare/connector-service.ts";
 import {
   DEFAULT_CLOUDFLARED_HOME,
   cloudflaredInstallHint,
@@ -10,6 +22,7 @@ import {
 } from "../cloudflare/detect.ts";
 import {
   CLOUDFLARED_STATE_PATH,
+  type CloudflaredState,
   type CloudflaredTunnelRecord,
   clearCloudflaredState,
   findTunnelRecord,
@@ -249,6 +262,27 @@ export interface ExposeCloudflareOpts {
    * `defaultConnectorPids` (a filtered `pgrep -fl cloudflared`).
    */
   connectorPids?: ConnectorPidsFn;
+  /**
+   * Install/remove the reboot-persistent connector OS service (launchd on
+   * macOS, systemd on Linux). Injectable so tests drive the install/remove
+   * without touching real launchctl/systemctl or `~/Library/LaunchAgents`.
+   * Defaults: the up-path installs (falls back to a transient `proc.unref()`
+   * connector when the tool is absent); the off / legacy-sweep paths remove.
+   * Tests inject fakes to assert the generated service file + command sequence.
+   */
+  installService?: (args: {
+    tunnelName: string;
+    configPath: string;
+    logPath: string;
+  }) => InstallResult;
+  removeService?: (args: { tunnelName: string }) => RemoveResult;
+  /**
+   * Override the side-effect deps the default install/remove implementations
+   * use (platform, getuid, fs, run). Only consulted when `installService` /
+   * `removeService` aren't injected directly. Lets a test pin `platform` /
+   * `getuid` while still exercising the real install/remove logic.
+   */
+  connectorServiceDeps?: ConnectorServiceDeps;
   /**
    * Resolve a hostname to its addresses, for the post-route DNS self-diagnosis
    * (hub#487). Returns the resolved IPs (empty when NXDOMAIN / not yet live).
@@ -269,9 +303,12 @@ export interface ExposeCloudflareOpts {
    */
   exposeStatePath?: string;
   /**
-   * Tunnel name targeted by this invocation. Defaults to `parachute` —
-   * the canonical single-tunnel name. Override to run multiple tunnels on
-   * one box (#32).
+   * Tunnel name targeted by this invocation. The up-path defaults to a
+   * per-hostname derived name (`deriveTunnelName(hostname)`) so each machine
+   * gets its own tunnel and account-wide tunnels don't collide across boxes
+   * (#491). Override to pin a specific name (e.g. multiple tunnels on one
+   * box, #32). The off-path resolves the name from `cloudflared-state.json`
+   * when omitted (it has no hostname to derive from).
    */
   tunnelName?: string;
   /**
@@ -346,6 +383,12 @@ interface Resolved {
   alive: AliveFn;
   kill: KillFn;
   connectorPids: ConnectorPidsFn;
+  installService: (args: {
+    tunnelName: string;
+    configPath: string;
+    logPath: string;
+  }) => InstallResult;
+  removeService: (args: { tunnelName: string }) => RemoveResult;
   resolveHost: ResolveHostFn;
   log: (line: string) => void;
   manifestPath: string;
@@ -366,8 +409,20 @@ interface Resolved {
   restartService: (short: string) => Promise<number>;
 }
 
-function resolve(opts: ExposeCloudflareOpts): Resolved {
-  const tunnelName = opts.tunnelName ?? DEFAULT_TUNNEL_NAME;
+/**
+ * Resolve options into the fully-defaulted `Resolved` shape.
+ *
+ * `tunnelNameDefault` is the fallback tunnel name when the caller didn't pass
+ * an explicit `opts.tunnelName`. The up-path passes `deriveTunnelName(hostname)`
+ * so each machine/hostname gets its OWN dedicated tunnel (#491) — sharing one
+ * account-wide tunnel across boxes collides their connectors. An explicit
+ * `--tunnel-name` always wins (operators can override). The off-path has no
+ * hostname to derive from, so it resolves the name from state before calling
+ * in (see `exposeCloudflareOff`) and only relies on this default as a last
+ * resort.
+ */
+function resolve(opts: ExposeCloudflareOpts, tunnelNameDefault: string): Resolved {
+  const tunnelName = opts.tunnelName ?? tunnelNameDefault;
   const configDir = opts.configDir ?? CONFIG_DIR;
   // Derive per-tunnel config/log paths from the *resolved* configDir, not the
   // real `CONFIG_DIR`. When a test threads a tmp `configDir` but omits explicit
@@ -387,6 +442,39 @@ function resolve(opts: ExposeCloudflareOpts): Resolved {
     // gets the real `pgrep` sweep + DNS diagnosis.
     connectorPids:
       opts.connectorPids ?? (opts.spawner === undefined ? defaultConnectorPids : () => []),
+    // Reboot-persistent connector seam. Defaulting policy mirrors
+    // `connectorPids`/`resolveHost`: when a test injects a stub `spawner` (and
+    // no explicit service seam), default to an inert "fallback" so existing
+    // stub-spawner suites keep exercising the transient-spawn path without
+    // touching real launchctl/systemctl. Production (no spawner override) gets
+    // the real install/remove. An explicit `installService`/`removeService`
+    // always wins; `connectorServiceDeps` lets a test pin platform/getuid
+    // while running the real install/remove logic.
+    installService:
+      opts.installService ??
+      (opts.spawner === undefined || opts.connectorServiceDeps !== undefined
+        ? (args) =>
+            installConnectorService({
+              ...args,
+              ...(opts.connectorServiceDeps !== undefined
+                ? { deps: opts.connectorServiceDeps }
+                : {}),
+            })
+        : () => ({
+            outcome: "fallback",
+            messages: [],
+          })),
+    removeService:
+      opts.removeService ??
+      (opts.spawner === undefined || opts.connectorServiceDeps !== undefined
+        ? (args) =>
+            removeConnectorService({
+              ...args,
+              ...(opts.connectorServiceDeps !== undefined
+                ? { deps: opts.connectorServiceDeps }
+                : {}),
+            })
+        : () => ({ removed: false, messages: [] })),
     resolveHost:
       opts.resolveHost ??
       (opts.spawner === undefined ? defaultResolveHost : async () => ["104.16.0.1"]),
@@ -489,7 +577,12 @@ export async function exposeCloudflareUp(
   hostname: string,
   opts: ExposeCloudflareOpts = {},
 ): Promise<number> {
-  const r = resolve(opts);
+  // Default to a per-hostname dedicated tunnel (#491). An explicit
+  // `--tunnel-name` still wins (handled inside `resolve`). Deriving from the
+  // hostname keeps re-expose idempotent (same hostname → same name → reuse the
+  // tunnel created last time) and stops two machines from colliding on the
+  // single account-wide `"parachute"` tunnel.
+  const r = resolve(opts, deriveTunnelName(hostname));
 
   if (!isValidTunnelName(r.tunnelName)) {
     r.log(
@@ -591,6 +684,9 @@ export async function exposeCloudflareUp(
       return reportCloudflaredError(err, r.log);
     }
     r.log(`✓ Created tunnel ${tunnel.id}`);
+    r.log(
+      "  Each machine gets its own dedicated tunnel — you don't need to run `cloudflared tunnel create` separately; expose does it.",
+    );
   } else {
     r.log(`✓ Reusing existing tunnel "${r.tunnelName}" (${tunnel.id})`);
   }
@@ -672,10 +768,88 @@ export async function exposeCloudflareUp(
     }
   }
 
-  const pid = r.spawner.spawn(
-    ["cloudflared", "tunnel", "--config", r.configPath, "run"],
-    r.logPath,
-  );
+  // Legacy shared-tunnel migration sweep (#491). Aaron's running boxes were
+  // exposed under the old single account-wide `"parachute"` tunnel; the bug
+  // was that a second box reusing that name collided connectors. Now that the
+  // default is per-hostname, a box upgrading and re-exposing will create/route
+  // a NEW dedicated tunnel — but the OLD `"parachute"` connector is still
+  // running, still registered on the shared tunnel, still able to pick up
+  // load-balanced requests for OTHER hosts. Kill it + drop its state record so
+  // the box self-heals immediately on this expose instead of at the next
+  // reboot. Only fires when (a) we actually migrated AWAY from "parachute"
+  // (the new derived name differs) and (b) a live legacy record exists.
+  // `routeDns` above already used `--overwrite-dns`, so this hostname's CNAME
+  // has been repointed to the new tunnel — the legacy connector can't serve it
+  // anymore regardless; this just stops it from serving anyone else's.
+  let migratedState = stateBefore;
+  if (r.tunnelName !== DEFAULT_TUNNEL_NAME) {
+    const legacy = findTunnelRecord(stateBefore, DEFAULT_TUNNEL_NAME);
+    if (legacy) {
+      // Remove any boot service for the legacy shared tunnel before killing its
+      // connector, so a service doesn't restart the connector we're migrating
+      // away from. Best-effort + idempotent (no-op when no service file exists,
+      // which is the common pre-0.6.2 case).
+      const legacyRemoval = r.removeService({ tunnelName: DEFAULT_TUNNEL_NAME });
+      for (const line of legacyRemoval.messages) r.log(line);
+      if (r.alive(legacy.pid)) {
+        try {
+          r.kill(legacy.pid, "SIGTERM");
+        } catch {
+          // Already gone between read and kill — fine; we drop the record below.
+        }
+        r.log(
+          `Stopped legacy shared-tunnel connector (migrated ${hostname} to dedicated tunnel ${r.tunnelName}).`,
+        );
+      }
+      // Drop the legacy shared-tunnel record whether or not its connector was
+      // still alive. A dead record would otherwise linger across re-exposes
+      // until the next `off`; clearing it here keeps state tidy (#491 review).
+      migratedState = withoutTunnelRecord(stateBefore, DEFAULT_TUNNEL_NAME);
+    }
+  }
+
+  // Install the reboot-persistent connector OS service (launchd / systemd) so
+  // the connector survives a reboot — replacing the bare `proc.unref()` spawn
+  // that died on restart (0.6.2). When the service installs successfully it
+  // *becomes* the connector: it spawns + supervises `cloudflared tunnel run`,
+  // so we do NOT also leave a duplicate transient connector — exactly one
+  // process serves the config we wrote. We then discover the service-spawned
+  // connector's pid (by UUID/config match) to record in state so the next
+  // up-path's orphan sweep + the off-path's kill target the right process.
+  //
+  // Graceful fallback: if the service tool is missing / the install fails, we
+  // fall back to the prior transient `proc.unref()` spawn and warn it won't
+  // survive a reboot. The expose never hard-fails because the service didn't
+  // take.
+  const installResult = r.installService({
+    tunnelName: r.tunnelName,
+    configPath: r.configPath,
+    logPath: r.logPath,
+  });
+  for (const line of installResult.messages) r.log(line);
+
+  let pid: number;
+  let serviceManaged = false;
+  if (installResult.outcome === "installed") {
+    serviceManaged = true;
+    // The service (`enable --now` / `bootstrap` with RunAtLoad) already started
+    // the connector; discover its pid for the state record so the next up-path's
+    // orphan sweep + the off-path's kill target the right process. In practice
+    // the connector is up by the time we look here.
+    const managedPids = r.connectorPids(tunnel.id, r.configPath).filter((p) => r.alive(p));
+    if (managedPids.length > 0) {
+      pid = managedPids[0]!;
+    } else {
+      // Service is enabled (survives reboot) but we couldn't see its connector
+      // yet. Spawn a transient one so state carries a live pid + connectivity
+      // is immediate; the service takes over on the next reboot regardless.
+      pid = r.spawner.spawn(["cloudflared", "tunnel", "--config", r.configPath, "run"], r.logPath);
+    }
+  } else {
+    // Fallback: no boot service. Spawn the transient connector (won't survive
+    // a reboot — warned below).
+    pid = r.spawner.spawn(["cloudflared", "tunnel", "--config", r.configPath, "run"], r.logPath);
+  }
 
   const record: CloudflaredTunnelRecord = {
     pid,
@@ -684,8 +858,11 @@ export async function exposeCloudflareUp(
     hostname,
     startedAt: r.now().toISOString(),
     configPath: r.configPath,
+    // Only serialize the flag when true — keep the state JSON clean for the
+    // common (transient-fallback) case; absent reads as unmanaged.
+    ...(serviceManaged ? { serviceManaged: true } : {}),
   };
-  writeCloudflaredState(withTunnelRecord(stateBefore, record), r.statePath);
+  writeCloudflaredState(withTunnelRecord(migratedState, record), r.statePath);
 
   // Persist the shared cross-provider expose record. Without this, the
   // Tailscale path was the only one writing expose-state.json — so after a
@@ -763,12 +940,29 @@ export async function exposeCloudflareUp(
 
   r.log("");
   r.log(`✓ Cloudflare tunnel up (pid ${pid}).`);
+  r.log(`  Tunnel:  ${r.tunnelName} (dedicated to this machine)`);
   r.log(`  Open:    ${baseUrl}/`);
   r.log(`  Admin:   ${baseUrl}/admin/`);
   r.log(`  Vault:   ${vaultUrl}`);
   r.log(`  OAuth:   ${hubOrigin}`);
   r.log(`  Logs:    ${r.logPath}`);
   r.log("");
+  if (serviceManaged) {
+    // The connector is now an OS service (launchd LaunchAgent on macOS, systemd
+    // unit on Linux), so it starts on boot — no need to re-run expose after a
+    // reboot. `parachute expose public --cloudflare off` stops + removes it.
+    r.log("The connector runs on boot (via launchd/systemd) — it survives reboots. Re-running");
+    r.log("the same command is still idempotent (same hostname → same dedicated tunnel).");
+  } else {
+    // Honest reboot caveat for the fallback path: the boot service couldn't be
+    // installed (tool missing / unsupported platform / install failed — see the
+    // warning printed above), so the connector is a detached background process
+    // that does NOT survive a reboot. Re-running the same command brings it back.
+    r.log("Note: a boot service couldn't be installed (see above), so the connector runs in the");
+    r.log("background but does NOT survive a reboot. After a reboot, re-run:");
+    r.log(`  parachute expose public --cloudflare --domain ${hostname}`);
+  }
+  r.log("");
   r.log("Point a claude.ai / ChatGPT connector at:");
   r.log(`  ${vaultUrl}`);
   printAuthGuidance(r.log, vaultUrl);
@@ -784,30 +978,37 @@ export async function exposeCloudflareUp(
   return 0;
 }
 
-export async function exposeCloudflareOff(opts: ExposeCloudflareOpts = {}): Promise<number> {
-  const r = resolve(opts);
-  const stateBefore = readCloudflaredState(r.statePath);
-  const record = findTunnelRecord(stateBefore, r.tunnelName);
-  if (!record) {
-    if (stateBefore && Object.keys(stateBefore.tunnels).length > 0) {
-      const others = listTunnelRecords(stateBefore)
-        .map((t) => t.tunnelName)
-        .join(", ");
-      r.log(
-        `No Cloudflare exposure recorded for tunnel "${r.tunnelName}". Other tunnels: ${others}.`,
-      );
-    } else {
-      r.log("No Cloudflare exposure recorded. Nothing to tear down.");
-    }
-    return 0;
-  }
+/**
+ * Tear down ONE tunnel record: SIGTERM its connector, sweep any orphan
+ * connectors for it (hub#487), drop its state record, and emit the
+ * reuse-hint copy. Pure-ish over `r` + the current state: returns the state
+ * with the record removed (or undefined when that empties it) plus an exit
+ * code, so the caller commits the disk write once after tearing down one or
+ * many tunnels. The connector kill is non-fatal-on-already-gone, fatal only
+ * when SIGTERM itself errors on a live pid.
+ */
+function teardownOne(
+  r: Resolved,
+  state: CloudflaredState | undefined,
+  record: CloudflaredTunnelRecord,
+): { state: CloudflaredState | undefined; code: number } {
+  // Remove the reboot-persistent connector service FIRST (when one owns this
+  // tunnel) so a still-enabled launchd/systemd service doesn't immediately
+  // restart the connector we SIGTERM below. `removeConnectorService` is
+  // idempotent + best-effort: a missing service file is a no-op (covers
+  // transient-fallback tunnels and pre-0.6.2 records, which carry no service).
+  // We always attempt it — even when `serviceManaged` is unset — so a record
+  // written before this field existed, or an out-of-band service file, still
+  // gets swept. The removal stops the service, after which the SIGTERM is final.
+  const removal = r.removeService({ tunnelName: record.tunnelName });
+  for (const line of removal.messages) r.log(line);
   if (r.alive(record.pid)) {
     try {
       r.kill(record.pid, "SIGTERM");
-      r.log(`✓ Stopped cloudflared (pid ${record.pid}).`);
+      r.log(`✓ Stopped cloudflared (pid ${record.pid}, tunnel "${record.tunnelName}").`);
     } catch (err) {
       r.log(`✗ Failed to stop cloudflared: ${err instanceof Error ? err.message : String(err)}`);
-      return 1;
+      return { state, code: 1 };
     }
   } else {
     r.log(`cloudflared (pid ${record.pid}) wasn't running; clearing stale state.`);
@@ -824,9 +1025,80 @@ export async function exposeCloudflareOff(opts: ExposeCloudflareOpts = {}): Prom
       // Already gone between probe and kill — fine.
     }
   }
-  const stateAfter = withoutTunnelRecord(stateBefore, r.tunnelName);
-  if (stateAfter) {
-    writeCloudflaredState(stateAfter, r.statePath);
+  r.log(`  ${record.hostname} is no longer reachable through this machine.`);
+  r.log(
+    `  Tunnel "${record.tunnelName}" (${record.tunnelUuid}) remains defined in Cloudflare; re-running`,
+  );
+  // Only suggest `--tunnel-name` for a custom name. The auto-derived name
+  // (and the legacy shared "parachute" name) need no flag — re-running with
+  // just --domain re-derives the per-hostname name (and migrates a legacy
+  // record off the shared tunnel), which is exactly what we want.
+  const isAutoName =
+    record.tunnelName === deriveTunnelName(record.hostname) ||
+    record.tunnelName === DEFAULT_TUNNEL_NAME;
+  r.log(
+    `  \`parachute expose public --cloudflare --domain ${record.hostname}${isAutoName ? "" : ` --tunnel-name ${record.tunnelName}`}\` reuses it.`,
+  );
+  return { state: withoutTunnelRecord(state, record.tunnelName), code: 0 };
+}
+
+export async function exposeCloudflareOff(opts: ExposeCloudflareOpts = {}): Promise<number> {
+  // The off-path has no hostname to derive a name from. When `--tunnel-name`
+  // is set we use it; otherwise we resolve from cloudflared-state.json (below).
+  // `DEFAULT_TUNNEL_NAME` is only the inert `resolve` fallback here — the
+  // state-driven branch never relies on it.
+  const r = resolve(opts, DEFAULT_TUNNEL_NAME);
+  const stateBefore = readCloudflaredState(r.statePath);
+  const records = listTunnelRecords(stateBefore);
+
+  // Decide which records to tear down.
+  //   - explicit `--tunnel-name` → exactly that one (or a not-found message).
+  //   - no flag, 0 tunnels        → nothing to do.
+  //   - no flag, exactly 1        → that one.
+  //   - no flag, ≥2               → ALL of them. A bare `expose public
+  //     --cloudflare off` means "stop all public Cloudflare exposure on this
+  //     machine"; tearing down only one would leave the box half-exposed with
+  //     no obvious signal which tunnel survived.
+  let targets: CloudflaredTunnelRecord[];
+  if (opts.tunnelName !== undefined) {
+    const record = findTunnelRecord(stateBefore, r.tunnelName);
+    if (!record) {
+      if (records.length > 0) {
+        const others = records.map((t) => t.tunnelName).join(", ");
+        r.log(
+          `No Cloudflare exposure recorded for tunnel "${r.tunnelName}". Other tunnels: ${others}.`,
+        );
+      } else {
+        r.log("No Cloudflare exposure recorded. Nothing to tear down.");
+      }
+      return 0;
+    }
+    targets = [record];
+  } else {
+    if (records.length === 0) {
+      r.log("No Cloudflare exposure recorded. Nothing to tear down.");
+      return 0;
+    }
+    if (records.length > 1) {
+      r.log(
+        `Tearing down all ${records.length} recorded Cloudflare tunnels: ${records
+          .map((t) => t.tunnelName)
+          .join(", ")}.`,
+      );
+    }
+    targets = records;
+  }
+
+  let state = stateBefore;
+  let failed = false;
+  for (const record of targets) {
+    const result = teardownOne(r, state, record);
+    state = result.state;
+    if (result.code !== 0) failed = true;
+  }
+
+  if (state) {
+    writeCloudflaredState(state, r.statePath);
   } else {
     clearCloudflaredState(r.statePath);
   }
@@ -834,17 +1106,10 @@ export async function exposeCloudflareOff(opts: ExposeCloudflareOpts = {}): Prom
   // downstream consumers stop resolving the now-dead public URL (mirrors the
   // up-path write above + the Tailscale off-path's expose-state teardown). When
   // other tunnels survive we leave it — a later off for the last one clears it.
-  if (!stateAfter) {
+  if (!state) {
     clearExposeState(r.exposeStatePath);
   }
-  r.log(`  ${record.hostname} is no longer reachable through this machine.`);
-  r.log(
-    `  Tunnel "${record.tunnelName}" (${record.tunnelUuid}) remains defined in Cloudflare; re-running`,
-  );
-  r.log(
-    `  \`parachute expose public --cloudflare --domain ${record.hostname}${record.tunnelName === DEFAULT_TUNNEL_NAME ? "" : ` --tunnel-name ${record.tunnelName}`}\` reuses it.`,
-  );
-  return 0;
+  return failed ? 1 : 0;
 }
 
 function reportCloudflaredError(err: unknown, log: (line: string) => void): number {

package/src/help.ts

@@ -369,8 +369,13 @@ Flags:
   --domain <hostname>     fully-qualified hostname to route through the tunnel
                           (e.g. vault.example.com). The apex must be a zone on
                           your Cloudflare account.
-  --tunnel-name <name>    Cloudflare tunnel name (default: \`parachute\`).
-                          Use to coexist multiple named tunnels on one box.
+  --tunnel-name <name>    Cloudflare tunnel name. Defaults to a per-hostname
+                          name (e.g. vault.example.com → parachute-vault-example-com)
+                          so each machine gets its OWN dedicated tunnel —
+                          Cloudflare tunnels are account-wide, and sharing one
+                          across machines collides their connectors. You don't
+                          need to create the tunnel yourself; expose does it.
+                          Override only to pin a specific name.
   --skip-provider-check   bypass non-TTY auto-detect, default to Tailscale
                           Funnel as before. Intended for CI / scripts whose
                           environment is already pre-flighted.