@hienlh/ppm 0.18.12 → 0.18.14

package/src/services/named-tunnel/named-tunnel-setup-confirm.ts

@@ -0,0 +1,98 @@
+/**
+ * Detached confirmation for a named-tunnel setup.
+ *
+ * Once the supervisor reload has been sent, `runSetup` returns to the caller
+ * immediately (a 45s status.json poll must never hold the HTTP response —
+ * see the setup service's own comment) and this module polls status.json in
+ * the background, broadcasting the final outcome over `/ws/global`.
+ *
+ * WHY a generation stamp: `setupInFlight`'s synchronous 409 lock is already
+ * released by the time this runs, and `isConfirmationRunning` only extends
+ * the 409 to a *same-hostname* retry (see the setup service) — a request for
+ * a *different* hostname is allowed straight through and immediately
+ * supersedes whatever confirmation was still polling. Without a generation
+ * check, that superseded confirmer would still broadcast its own result
+ * (`setup_done` or `setup_pending`) 1s-to-45s later, carrying the *old*
+ * hostname and overwriting the correct, newer result in every connected
+ * client. Each confirmation run is stamped with a monotonic generation, and
+ * a confirmer checks it is still the current one immediately before
+ * broadcasting — a superseded confirmer exits silently instead.
+ */
+import { readStatus } from "../supervisor-state.ts";
+import { broadcastGlobalEvent } from "../../server/ws/global.ts";
+
+const CONFIRM_POLL_BUDGET_MS = 45_000;
+const CONFIRM_POLL_INTERVAL_MS = 1_000;
+
+let generation = 0;
+/** The hostname + deadline of the confirmation currently allowed to broadcast. */
+let current: { hostname: string; deadline: number } | null = null;
+
+/**
+ * True while a background confirmation is still running for `hostname`.
+ * Bounded by the same poll budget the confirmer itself uses, so a wedged
+ * confirmation can never lock a hostname out of retry forever. A different
+ * hostname's confirmation immediately closes this window (superseding is
+ * unconditional, not per-hostname), matching "a different hostname proceeds
+ * and takes over" below.
+ */
+export function isConfirmationRunning(hostname: string): boolean {
+  return current !== null && current.hostname === hostname && Date.now() < current.deadline;
+}
+
+async function pollForConfirmation(hostname: string, budgetMs: number, intervalMs: number): Promise<boolean> {
+  const deadline = Date.now() + budgetMs;
+  while (Date.now() < deadline) {
+    const status = readStatus();
+    if (status.tunnelMode === "named" && status.shareUrl === `https://${hostname}`) return true;
+    await Bun.sleep(intervalMs);
+  }
+  return false;
+}
+
+/**
+ * Fire-and-forget: polls status.json and broadcasts the final outcome.
+ * Never throws into the caller. Silently drops its own broadcast if a newer
+ * setup (any hostname) has started since — see the module docstring.
+ * `opts` exists only so tests can shrink the poll budget/interval; production
+ * always uses the real 45s/1s constants.
+ */
+export function confirmReloadInBackground(
+  hostname: string,
+  opts: { pollBudgetMs?: number; pollIntervalMs?: number } = {},
+): void {
+  const budgetMs = opts.pollBudgetMs ?? CONFIRM_POLL_BUDGET_MS;
+  const intervalMs = opts.pollIntervalMs ?? CONFIRM_POLL_INTERVAL_MS;
+  const myGeneration = ++generation;
+  current = { hostname, deadline: Date.now() + budgetMs };
+  const isSuperseded = () => generation !== myGeneration;
+
+  pollForConfirmation(hostname, budgetMs, intervalMs)
+    .then((confirmed) => {
+      if (isSuperseded()) return;
+      if (confirmed) {
+        broadcastGlobalEvent({ type: "tunnel:setup_done", hostname });
+        return;
+      }
+      const latest = readStatus();
+      const warning = typeof latest.tunnelWarning === "string" ? latest.tunnelWarning : null;
+      broadcastGlobalEvent({
+        type: "tunnel:setup_pending",
+        hostname,
+        message: warning ?? "setup saved but the supervisor has not confirmed it yet — check again shortly",
+      });
+    })
+    .catch(() => {
+      if (isSuperseded()) return;
+      broadcastGlobalEvent({
+        type: "tunnel:setup_pending",
+        hostname,
+        message: "confirmation check failed — check status again shortly",
+      });
+    })
+    .finally(() => {
+      // Release the 409 window once this generation settles — but only if
+      // nothing newer has already taken `current` over.
+      if (!isSuperseded() && current) current.deadline = 0;
+    });
+}

package/src/services/named-tunnel/named-tunnel-setup.service.ts

@@ -0,0 +1,191 @@
+/**
+ * Zone → precheck → create → route → token → persist → confirm.
+ *
+ * The DNS collision precheck runs *before* `tunnel create`, so "is this
+ * record already ours" is answered via the Cloudflare API's own tunnel
+ * lookup-by-name (an idempotent retry has an existing tunnel; a first-time
+ * setup does not) rather than by depending on `create` having already run.
+ */
+import { readOriginCertState } from "./cloudflared-cert.ts";
+import { fetchZoneName } from "./cloudflare-zone-api.ts";
+import { fetchDnsRecords, fetchTunnelIdByName } from "./cloudflare-dns-api.ts";
+import { proposeHostname, validateHostname } from "./hostname-rules.ts";
+import { createTunnelArgs, routeDnsArgs, tunnelTokenArgs, tunnelNameForHost } from "./named-tunnel-args.ts";
+import { runCloudflared } from "./cloudflared-exec.ts";
+import { configService } from "../config.service.ts";
+import { requestTunnelReload, readStatus } from "../supervisor-state.ts";
+import { broadcastGlobalEvent } from "../../server/ws/global.ts";
+import { pinsMatch } from "./cloudflared-login-helpers.ts";
+import { confirmReloadInBackground, isConfirmationRunning } from "./named-tunnel-setup-confirm.ts";
+
+export type CertState = "none" | "invalid" | "ok" | "mismatch";
+
+/** Thrown by the flow below; routes map `.status` straight to the HTTP response. */
+export class SetupError extends Error {
+  status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.status = status;
+  }
+}
+
+// `cloudflared tunnel token` prints one line of standard base64 (with `+`, `/`
+// and `=` padding — a real token is ~180 chars ending in `=`), not URL-safe
+// base64, so the alphabet must include those three or every real token is
+// rejected as "unexpected output".
+const TOKEN_SHAPE = /^[A-Za-z0-9+/=._-]{100,}$/;
+const RELOAD_RETRY_DELAY_MS = 2_000;
+
+/** Module-level in-flight guard — two concurrent setups would race `route dns`. */
+let setupInFlight = false;
+
+/**
+ * Read-mostly cert classification for `/status` — never leaks the token.
+ * `"mismatch"` is a pure pin comparison (no network call): the parsed cert's
+ * zoneID/accountID differ from whatever `tunnel` config already pinned, i.e.
+ * cloudflared logged into a *different* Cloudflare account than the one this
+ * machine's named tunnel was set up under.
+ */
+export function currentCertState(): CertState {
+  const state = readOriginCertState();
+  if (state.kind === "absent") return "none";
+  if (state.kind === "unparseable") return "invalid";
+  return pinsMatch(state.cert) ? "ok" : "mismatch";
+}
+
+export async function readZoneInfo(): Promise<{ zone: string; zoneID: string; accountID: string; proposedHostname: string }> {
+  const certState = readOriginCertState();
+  if (certState.kind !== "parsed") throw new SetupError(400, "Not logged in to Cloudflare");
+  if (!pinsMatch(certState.cert)) {
+    throw new SetupError(400, "cert belongs to a different Cloudflare account — log in again");
+  }
+  const zone = await fetchZoneName(certState.cert.zoneID, certState.cert.apiToken);
+  return { zone, zoneID: certState.cert.zoneID, accountID: certState.cert.accountID, proposedHostname: proposeHostname(zone) };
+}
+
+export async function disableNamedTunnel(): Promise<void> {
+  const current = configService.get("tunnel");
+  configService.set("tunnel", { ...current, mode: "quick" });
+  requestTunnelReload();
+}
+
+export type SetupOutcome =
+  | { ok: true; hostname: string; tunnelName: string }
+  | { ok: "pending"; hostname: string; tunnelName: string; message: string };
+
+/**
+ * The synchronous `setupInFlight` lock only covers the create/route/token
+ * cycle — once the supervisor reload is sent, confirmation continues in the
+ * background (`named-tunnel-setup-confirm.ts`) and this function has already
+ * returned. `isConfirmationRunning` extends the 409 specifically to a retry
+ * for the *same* hostname during that bounded (<=45s) window, so mashing
+ * "Set up" doesn't kick off a second, redundant create/route/token cycle for
+ * a request that is already in flight. A *different* hostname is still let
+ * through immediately and supersedes the earlier confirmer — see the confirm
+ * module for how the stale one is silenced instead of broadcasting late.
+ */
+export async function runSetup(hostname: string): Promise<SetupOutcome> {
+  if (setupInFlight) throw new SetupError(409, "a setup is already running");
+  if (isConfirmationRunning(hostname)) {
+    throw new SetupError(409, "a setup for this hostname is already confirming — check again shortly");
+  }
+  setupInFlight = true;
+  try {
+    return await runSetupInner(hostname);
+  } finally {
+    setupInFlight = false;
+  }
+}
+
+async function runSetupInner(hostname: string): Promise<SetupOutcome> {
+  broadcastGlobalEvent({ type: "tunnel:setup_step", step: "zone", message: "reading Cloudflare zone" });
+  const certState = readOriginCertState();
+  if (certState.kind !== "parsed") throw new SetupError(400, "Not logged in to Cloudflare");
+  const { zoneID, accountID, apiToken } = certState.cert;
+
+  const zone = await fetchZoneName(zoneID, apiToken);
+  const check = validateHostname(hostname, zone);
+  if (!check.ok) throw new SetupError(400, check.reason);
+
+  const tunnelName = tunnelNameForHost();
+
+  broadcastGlobalEvent({ type: "tunnel:setup_step", step: "precheck", message: "checking for a DNS collision" });
+  const existingId = await fetchTunnelIdByName(accountID, apiToken, tunnelName);
+  const records = await fetchDnsRecords(zoneID, apiToken, hostname);
+  let overwrite = false;
+  if (records.length > 0) {
+    const ownTarget = existingId ? `${existingId}.cfargotunnel.com` : null;
+    const isOwn = ownTarget != null && records.some((r) => r.content === ownTarget);
+    if (!isOwn) throw new SetupError(400, "that name already points somewhere else — pick another prefix");
+    overwrite = true;
+  }
+
+  broadcastGlobalEvent({ type: "tunnel:setup_step", step: "create", message: "creating tunnel" });
+  const create = await runCloudflared(createTunnelArgs(tunnelName));
+  if (create.code !== 0 && !/already exists/i.test(create.stderr)) {
+    throw new SetupError(500, `cloudflared tunnel create failed: ${(create.stderr || create.stdout).trim()}`);
+  }
+
+  broadcastGlobalEvent({ type: "tunnel:setup_step", step: "route", message: "routing DNS" });
+  const route = await runCloudflared(routeDnsArgs(tunnelName, hostname, overwrite));
+  if (route.code !== 0) {
+    throw new SetupError(500, `cloudflared tunnel route dns failed: ${(route.stderr || route.stdout).trim()}`);
+  }
+
+  broadcastGlobalEvent({ type: "tunnel:setup_step", step: "token", message: "fetching run token" });
+  const tokenResult = await runCloudflared(tunnelTokenArgs(tunnelName));
+  const token = tokenResult.stdout.trim();
+  if (tokenResult.code !== 0 || !TOKEN_SHAPE.test(token)) {
+    throw new SetupError(500, "unexpected cloudflared output while fetching the run token");
+  }
+
+  broadcastGlobalEvent({ type: "tunnel:setup_step", step: "apply", message: "applying configuration" });
+  configService.set("tunnel", {
+    mode: "named",
+    namedTunnelName: tunnelName,
+    namedTunnelHostname: hostname,
+    namedTunnelToken: token,
+    zoneID,
+    accountID,
+  });
+
+  const pending = (message: string): SetupOutcome => {
+    broadcastGlobalEvent({ type: "tunnel:setup_pending", hostname, message });
+    return { ok: "pending", hostname, tunnelName, message };
+  };
+
+  const status = readStatus();
+  const capabilities = Array.isArray(status.capabilities) ? (status.capabilities as unknown[]) : [];
+  if (!capabilities.includes("retunnel")) {
+    return pending("run `ppm restart` to apply — this PPM version needs a restart to pick up named tunnels");
+  }
+
+  let reload = requestTunnelReload();
+  if (reload === "busy") {
+    await Bun.sleep(RELOAD_RETRY_DELAY_MS);
+    reload = requestTunnelReload();
+  }
+  if (reload === "busy") {
+    return pending("supervisor busy — it will pick up the new setting shortly, or run `ppm restart`");
+  }
+  if (reload === "no-supervisor") {
+    return pending("no supervisor detected — run `ppm restart`");
+  }
+
+  // reload === "sent" — don't block the HTTP response on up to 45s of
+  // polling: a proxy/tunnel in front of PPM with a shorter idle timeout would
+  // time the browser out while setup was actually succeeding. Confirm
+  // detached and let /ws/global carry the final result (setup_done, or a
+  // follow-up setup_pending if confirmation itself times out) — the UI
+  // already listens for both events.
+  confirmReloadInBackground(hostname);
+  return pending("reload sent — waiting for the supervisor to confirm");
+}
+
+/**
+ * Aggregate for callers that need a single patchable seam (the HTTP routes) —
+ * route tests monkey-patch these properties directly rather than reaching for
+ * `mock.module`, which replaces the module for every importer process-wide and
+ * would poison this file's own direct-function unit tests.
+ */
+export const namedTunnelSetupService = { readZoneInfo, runSetup, disableNamedTunnel, currentCertState };

package/src/services/supervisor-state.ts

@@ -71,7 +71,10 @@ export function writeStatus(data: Record<string, unknown>) {
 }
 
 // ─── Command file protocol ─────────────────────────────────────────────
-export type CmdAction = "soft_stop" | "resume" | "restart";
+// "upgrade" is written directly by upgrade.service.ts (bypasses writeCmd, same
+// as restart.ts/stop.ts) and read by supervisor.ts's Windows poll loop — listed
+// here so the type matches what's actually read/written on disk.
+export type CmdAction = "soft_stop" | "resume" | "restart" | "retunnel" | "upgrade";
 
 /** Atomically claim + read command file (rename to .claimed, read, delete) */
 export function readAndDeleteCmd(): { action: CmdAction } | null {
@@ -88,8 +91,70 @@ export function readAndDeleteCmd(): { action: CmdAction } | null {
   }
 }
 
-export function writeCmd(action: CmdAction) {
+/**
+ * `retunnel` is the only low-priority action — it always yields to whatever
+ * is already pending, since a named-tunnel reload can wait behind a genuine
+ * lifecycle transition. The other three outrank it: a `resume` stuck behind
+ * an unclaimed `retunnel` would otherwise leave the server looking stopped
+ * (win32's poll loop is 1s; POSIX has a write/SIGUSR2 gap) for no reason.
+ */
+const LIFECYCLE_ACTIONS: readonly CmdAction[] = ["resume", "soft_stop", "restart", "upgrade"];
+
+/**
+ * Write `.supervisor-cmd`, but never clobber a *different* action that's still
+ * unclaimed — with one exception: a lifecycle action (`resume`/`soft_stop`/
+ * `restart`/`upgrade`) always overwrites a pending `retunnel`. Any other
+ * collision (two different lifecycle actions, or a `retunnel` behind a
+ * pending lifecycle action) returns `false` without writing so the caller can
+ * report "busy" instead of silently discarding someone else's request; a
+ * warning is logged either way so a dropped command is never silent. Note:
+ * `restart.ts`/`stop.ts` write this file directly and bypass this peek
+ * entirely, so the supervisor's dispatcher must still treat a stale/racing
+ * action defensively regardless of who wrote it — this is a best-effort
+ * single-slot guard, not a full queue.
+ */
+export function writeCmd(action: CmdAction): boolean {
+  try {
+    const existing = JSON.parse(readFileSync(CMD_FILE(), "utf-8")) as { action?: string };
+    if (existing?.action && existing.action !== action) {
+      const lifecycleOverridesRetunnel = LIFECYCLE_ACTIONS.includes(action) && existing.action === "retunnel";
+      if (!lifecycleOverridesRetunnel) {
+        try { process.stderr.write(`[writeCmd] dropped "${action}" — "${existing.action}" is already pending\n`); } catch {}
+        return false;
+      }
+    }
+  } catch {
+    // Missing file, unreadable, or invalid JSON — nothing unclaimed to protect.
+  }
   writeFileSync(CMD_FILE(), JSON.stringify({ action }));
+  return true;
+}
+
+/**
+ * Ask the running supervisor to reload the tunnel (e.g. after a named-tunnel
+ * setup/disable). POSIX confirms the supervisor is alive via a zero-signal
+ * probe before writing; win32 has no equivalent probe here, so it relies on
+ * the supervisor's existing 1s command-file poll loop to pick up the request.
+ */
+export function requestTunnelReload(): "sent" | "busy" | "no-supervisor" {
+  const status = readStatus();
+  const pid = status.supervisorPid as number | undefined;
+  if (!pid) return "no-supervisor";
+
+  if (process.platform !== "win32") {
+    try {
+      process.kill(pid, 0);
+    } catch {
+      return "no-supervisor";
+    }
+  }
+
+  if (!writeCmd("retunnel")) return "busy";
+
+  if (process.platform !== "win32") {
+    try { process.kill(pid, "SIGUSR2"); } catch { /* best-effort; poll loop is the fallback path */ }
+  }
+  return "sent";
 }
 
 // ─── Lockfile ──────────────────────────────────────────────────────────