@hienlh/ppm 0.23.24 → 0.23.25

package/src/services/scheduler-view.ts

@@ -0,0 +1,54 @@
+/**
+ * The one shape a schedule leaves the server in. A raw row carries `secrets_enc` (the secrets,
+ * encrypted but still not for a browser) and `state_json` (whatever a script kept, a token
+ * included): every route answers through `toScheduleView`, never with the row.
+ */
+import type { Schedule, ScheduleInputDecl, ScheduleInputValue, ScheduleStatusView, ScheduleView } from "../types/scheduler.ts";
+import { blockedBy, liveScript } from "./schedule-script/instance-guard.ts";
+import { readSecrets } from "./schedule-script/schedule-secrets.ts";
+import { getRuntime } from "./schedule-script/script-runtime-db.ts";
+import { alwaysOnSupervisor, schedulerService } from "./scheduler.service.ts";
+
+export function toScheduleView(s: Schedule): ScheduleView {
+  const { secrets_enc, state_json, inputs_json, input_values_json, ...rest } = s;
+  return {
+    ...rest,
+    inputs: parseOr<ScheduleInputDecl[]>(inputs_json, []),
+    inputValues: parseOr<Record<string, ScheduleInputValue>>(input_values_json, {}),
+    secretsSet: secretKeys(s),
+    status: scheduleStatus(s),
+  };
+}
+
+export function scheduleStatus(s: Schedule): ScheduleStatusView {
+  const idle: ScheduleStatusView = { state: "idle", pid: null, since: null, restartAt: null, restarts: 0, lastError: null };
+  if (s.kind === "prompt") return { ...idle, state: schedulerService.isRunning(s.id) ? "running" : "idle" };
+  const blocker = blockedBy(s.id);
+  if (blocker !== null) {
+    return { ...idle, state: "blocked", pid: blocker, lastError: `Its previous process (pid ${blocker}) is still running and could not be stopped` };
+  }
+  if (s.mode === "always-on") {
+    const live = alwaysOnSupervisor.status(s.id);
+    if (live) return live;
+    return { ...idle, state: s.enabled ? "starting" : "stopped", lastError: getRuntime(s.id)?.last_error ?? null };
+  }
+  const child = liveScript(s.id);
+  return child ? { ...idle, state: "running", pid: child.pid } : idle;
+}
+
+/** Keys of the secrets saved; none when they cannot be read with this PPM's key. */
+export function secretKeys(s: Pick<Schedule, "secrets_enc">): string[] {
+  try {
+    return Object.keys(readSecrets(s));
+  } catch {
+    return [];
+  }
+}
+
+function parseOr<T>(json: string, fallback: T): T {
+  try {
+    return JSON.parse(json) as T;
+  } catch {
+    return fallback;
+  }
+}

package/src/services/scheduler.service.ts

@@ -2,8 +2,16 @@
  * Logic lives in scheduler-core.ts (constructor-injected runner keeps tests mock-free). */
 import { SchedulerService, nextFireAt } from "./scheduler-core.ts";
 import { ensureScheduleSession, runScheduleOnce } from "./scheduler-runner.ts";
+import { AlwaysOnSupervisor } from "./schedule-script/always-on-supervisor.ts";
+import { runScriptTick } from "./schedule-script/tick-runner.ts";
 
 export { nextFireAt };
 
+/** The processes of always-on script schedules. */
+export const alwaysOnSupervisor = new AlwaysOnSupervisor();
+
 /** Singleton scheduler — started from server boot. */
-export const schedulerService = new SchedulerService({ ensureScheduleSession, runScheduleOnce });
+export const schedulerService = new SchedulerService(
+  { ensureScheduleSession, runScheduleOnce, runScriptTick: (schedule) => runScriptTick(schedule) },
+  alwaysOnSupervisor,
+);

package/src/services/share-host/CLAUDE.md

@@ -0,0 +1,12 @@
+# `src/services/share-host/`
+
+## Map
+
+- `share-host-worker.ts` (the `__share_host__` process) + `share-host-gateway.ts` (what it lets through: `/s`, `/s/*`, `/assets/share-*`), `share-host-supervision.ts` (the supervisor's half: worker, connector, what PPM's own connector must carry), `share-host-connector.ts` (one cloudflared with restart and backoff), `share-host-args.ts` (argv and ingress files), `share-host-config.ts` (the `share_host` row and the plan), `share-host-status.ts` (reading `status.json`), `share-host-setup.service.ts` (Settings' setup flow). Docs `docs/architecture/workspace-and-ui.md` → Share links → The review address
+
+## Gotchas
+
+- **Two connectors on one tunnel share its traffic, whatever their routes say**: Cloudflare spreads a hostname's requests over every connector of a tunnel, so a share-host connector routing only the share hostname next to PPM's routing only PPM's would answer half of each with 404s. In `shared` mode exactly one runs: PPM's own (carrying both, via `routesForPpmConnector`) while PPM's public link is on, the share host's (`shared-own`) while it is off. A `retunnel` hands the tunnel over: the supervisor stops one connector as it starts the other.
+- **`--url` answers every hostname pointing at the tunnel, and a review hostname outlives its settings**: a review hostname set up in `shared` mode is a DNS record on PPM's tunnel, and nothing deletes it: not switching the review address off, not going back to a temporary address, not setting up another hostname. So once the `share_host` row names a hostname (`domainSetUp`), PPM's named connector routes by ingress rules (its own hostname, the review route while it carries it, a 404 for anything else) whatever else holds: the worker down, never started, or switched off (`ppmConnectorRoutes`). Falling back to `--url` whenever the worker had no port once served all of PPM on the review hostname.
+- **Bun's `process.ppid` never changes once read, in the main thread too**: `src/services/schedule-script/CLAUDE.md` records it inside a Worker; measured here, a worker whose supervisor died kept reporting the dead pid while `/proc/self/stat` already named the process it had been reparented to. `parentAlive` reads `/proc/self/stat` (falling back to `process.kill(parent, 0)` off Linux), and `share-host-worker-process.test.ts` kills a real parent to pin it.
+- **The supervisor reads PPM's tunnel row only at boot and on `retunnel`, not on `reshare`**: `reshare` re-reads `share_host` alone. The named-tunnel routes send `retunnel` themselves, but a script or test that changes the `tunnel` row and sends only `reshare` gets a plan built on the old PPM tunnel (a `shared` review address reported unavailable, say).

package/src/services/share-host/share-host-args.ts

@@ -0,0 +1,76 @@
+/**
+ * cloudflared argv for the share host's connector, and for PPM's own connector in `shared` mode.
+ *
+ * Each builder writes the files it names, like `named-tunnel-args.ts`, and no token ever appears
+ * in argv: it travels in a 0600 file passed as `--token-file`. Every config is a file of PPM's
+ * own, never `~/.cloudflared/config.yml`, whose ingress rules cloudflared would otherwise apply
+ * (see `getQuickTunnelArgs`).
+ *
+ * A connector that carries more than one hostname routes them with ingress rules instead of
+ * `--url`, and ends with a 404 for everything else: on PPM's tunnel with PPM's link off, that
+ * 404 is what keeps PPM's own hostname from reaching PPM.
+ */
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { getPpmDir } from "../ppm-dir.ts";
+import { getQuickTunnelArgs } from "../cloudflared.service.ts";
+import { writeNamedTunnelToken } from "../named-tunnel/named-tunnel-args.ts";
+
+const shareRunConfigPath = () => resolve(getPpmDir(), "cloudflared-share.yml");
+const shareTokenPath = () => resolve(getPpmDir(), "share-host-tunnel.token");
+const sharedOwnConfigPath = () => resolve(getPpmDir(), "cloudflared-share-ingress.yml");
+const ppmIngressConfigPath = () => resolve(getPpmDir(), "cloudflared-named-ingress.yml");
+
+export interface IngressRule {
+  hostname: string;
+  /** Loopback port the hostname is served from. */
+  port: number;
+}
+
+const HOSTNAME_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/;
+
+/** A cloudflared config routing each hostname to its loopback port, and anything else to a 404. */
+export function ingressConfigYaml(rules: IngressRule[]): string {
+  const lines = ["no-autoupdate: true", "ingress:"];
+  for (const rule of rules) {
+    if (!HOSTNAME_RE.test(rule.hostname)) throw new Error(`invalid ingress hostname: ${rule.hostname}`);
+    if (!Number.isInteger(rule.port) || rule.port <= 0 || rule.port > 65535) throw new Error(`invalid ingress port: ${rule.port}`);
+    lines.push(`  - hostname: ${rule.hostname}`, `    service: http://127.0.0.1:${rule.port}`);
+  }
+  lines.push("  - service: http_status:404", "");
+  return lines.join("\n");
+}
+
+function writePrivate(path: string, content: string): string {
+  if (!existsSync(getPpmDir())) mkdirSync(getPpmDir(), { recursive: true, mode: 0o700 });
+  writeFileSync(path, content, { mode: 0o600 });
+  // POSIX enforces the mode; Windows has no equivalent bit.
+  if (process.platform !== "win32") {
+    try { chmodSync(path, 0o600); } catch {}
+  }
+  return path;
+}
+
+/** A temporary trycloudflare address for the worker: PPM's own quick argv, aimed at it. */
+export function shareQuickArgs(port: number): string[] {
+  return getQuickTunnelArgs(port);
+}
+
+/** The share host's own named tunnel, which carries nothing but the share host. */
+export function shareNamedArgs(token: string, port: number): string[] {
+  const cfg = writePrivate(shareRunConfigPath(), "no-autoupdate: true\n");
+  const tokenPath = writePrivate(shareTokenPath(), token);
+  return ["--config", cfg, "tunnel", "run", "--token-file", tokenPath, "--url", `http://127.0.0.1:${port}`];
+}
+
+/** A connector on PPM's tunnel while PPM's own link is off: the share hostname, and 404s. */
+export function sharedOwnArgs(ppmToken: string, share: IngressRule): string[] {
+  const cfg = writePrivate(sharedOwnConfigPath(), ingressConfigYaml([share]));
+  return ["--config", cfg, "tunnel", "run", "--token-file", writeNamedTunnelToken(ppmToken)];
+}
+
+/** PPM's own connector while it also carries the share hostname. */
+export function ppmIngressRunArgs(ppmToken: string, rules: IngressRule[]): string[] {
+  const cfg = writePrivate(ppmIngressConfigPath(), ingressConfigYaml(rules));
+  return ["--config", cfg, "tunnel", "run", "--token-file", writeNamedTunnelToken(ppmToken)];
+}

package/src/services/share-host/share-host-config.ts

@@ -0,0 +1,128 @@
+/**
+ * The share host's settings (`share_host` config row) and the plan the supervisor runs from them.
+ *
+ * The share host is a public address for design review links that reaches the review pages and
+ * nothing else of PPM (`share-host-gateway.ts`). It gets to Cloudflare in one of three ways:
+ *
+ * - `quick`: its own temporary trycloudflare address, which changes whenever it restarts;
+ * - `named`: its own named tunnel on the user's domain (`ppm-share-<host>`);
+ * - `shared`: a second hostname on PPM's own named tunnel. While PPM's public link is on, PPM's
+ *   connector carries it; while that link is off, the share host runs a connector on the same
+ *   tunnel that routes only its own hostname, so PPM itself stays private.
+ */
+import { hostname as osHostname } from "node:os";
+import { basename, resolve } from "node:path";
+import { getPpmDir, isIsolatedPpmHome } from "../ppm-dir.ts";
+import type { ResolvedTunnelConfig } from "../named-tunnel/named-tunnel-config.ts";
+
+/** Where the worker publishes the port it listens on. Single writer: the worker. */
+export const SHARE_HOST_PORT_FILE = () => resolve(getPpmDir(), ".share-host-port");
+
+export type ShareHostMode = "quick" | "named" | "shared";
+
+export interface ResolvedShareHostConfig {
+  /** Master switch, off until the user turns it on. */
+  enabled: boolean;
+  mode: ShareHostMode;
+  hostname: string | null;
+  /**
+   * `named`: the share host's own tunnel. Kept in the row after switching to another mode, as the
+   * record that this installation created it; `shared` runs on PPM's tunnel, so null here.
+   */
+  tunnelName: string | null;
+  /** `named` only: the share tunnel's run token. Secret, like PPM's own. */
+  token: string | null;
+  zoneID: string | null;
+  accountID: string | null;
+  /**
+   * A hostname on the user's domain was set up for the review address, whatever the mode and the
+   * switch say now. Its DNS record outlives both (switching off, or back to a temporary address,
+   * deletes nothing), and one set up in `shared` mode still points at PPM's tunnel.
+   */
+  domainSetUp: boolean;
+}
+
+const nonEmpty = (v: unknown): v is string => typeof v === "string" && v.length > 0;
+
+/**
+ * The stored row as something to act on. A `named` row missing any part of its identity, or a
+ * `shared` row with no hostname, is `quick`: setup writes those fields only once it has all of
+ * them, so this is a hand-edited row, and a temporary address is what it can still have.
+ */
+export function resolveShareHostConfig(raw: unknown): ResolvedShareHostConfig {
+  let obj: Record<string, unknown> | null = null;
+  if (typeof raw === "string") {
+    try { obj = JSON.parse(raw); } catch { obj = null; }
+  } else if (raw && typeof raw === "object") {
+    obj = raw as Record<string, unknown>;
+  }
+  const enabled = obj?.enabled === true;
+  const domainSetUp = nonEmpty(obj?.hostname);
+  const quick: ResolvedShareHostConfig = {
+    enabled, mode: "quick", hostname: null, tunnelName: null, token: null, zoneID: null, accountID: null, domainSetUp,
+  };
+  if (!obj) return quick;
+  const ids = { zoneID: nonEmpty(obj.zoneID) ? obj.zoneID : null, accountID: nonEmpty(obj.accountID) ? obj.accountID : null };
+  if (obj.mode === "named" && nonEmpty(obj.hostname) && nonEmpty(obj.token) && ids.zoneID && ids.accountID) {
+    return {
+      enabled, mode: "named", hostname: obj.hostname, tunnelName: nonEmpty(obj.tunnelName) ? obj.tunnelName : null,
+      token: obj.token, ...ids, domainSetUp,
+    };
+  }
+  if (obj.mode === "shared" && nonEmpty(obj.hostname)) {
+    return { enabled, mode: "shared", hostname: obj.hostname, tunnelName: null, token: null, ...ids, domainSetUp };
+  }
+  return quick;
+}
+
+/** What the supervisor runs for the share host. */
+export type ShareHostPlan =
+  | { kind: "off" }
+  /** Its own temporary trycloudflare connector. */
+  | { kind: "quick" }
+  /** Its own connector on its own named tunnel. */
+  | { kind: "named"; hostname: string; token: string }
+  /** Its own connector on PPM's named tunnel, routing only the share hostname (PPM's link is off). */
+  | { kind: "shared-own"; hostname: string; token: string }
+  /** PPM's connector carries the share hostname next to PPM's own (PPM's link is on). */
+  | { kind: "shared-ppm"; hostname: string }
+  | { kind: "unavailable"; reason: string };
+
+export const SHARED_NEEDS_NAMED_PPM =
+  "PPM's public link no longer uses your domain, so the review address on its tunnel is down. Set the review address up again.";
+
+/**
+ * `ppmLinkOn` is whether PPM's own connector runs now (its public link switch). The two share
+ * one tunnel in `shared` mode and must never run two connectors on it with different routes,
+ * because Cloudflare spreads every hostname's requests across a tunnel's connectors.
+ */
+export function planShareHost(
+  share: ResolvedShareHostConfig, ppm: ResolvedTunnelConfig | null, ppmLinkOn: boolean,
+): ShareHostPlan {
+  if (!share.enabled) return { kind: "off" };
+  if (share.mode === "named" && share.hostname && share.token) {
+    return { kind: "named", hostname: share.hostname, token: share.token };
+  }
+  if (share.mode === "shared" && share.hostname) {
+    if (!ppm || ppm.mode !== "named" || !ppm.token || !ppm.hostname) {
+      return { kind: "unavailable", reason: SHARED_NEEDS_NAMED_PPM };
+    }
+    if (ppmLinkOn) return { kind: "shared-ppm", hostname: share.hostname };
+    return { kind: "shared-own", hostname: share.hostname, token: ppm.token };
+  }
+  return { kind: "quick" };
+}
+
+/**
+ * Tunnel name for a `named` share host: PPM's own (`tunnelNameForHost`) with `share-` after the
+ * `ppm-` prefix, so the two never collide and the prefix survives the length cap.
+ */
+export function shareTunnelNameForHost(): string {
+  const sanitized = osHostname().toLowerCase().replace(/[^a-z0-9-]/g, "-");
+  let suffix = "";
+  if (isIsolatedPpmHome()) {
+    const dir = basename(getPpmDir()).toLowerCase().replace(/^\.+/, "").replace(/[^a-z0-9-]/g, "-");
+    suffix = dir ? `-${dir}` : "-alt";
+  }
+  return `ppm-share-${sanitized}${suffix}`.slice(0, 32);
+}

package/src/services/share-host/share-host-connector.ts

@@ -0,0 +1,180 @@
+/**
+ * Keeps one cloudflared connector for the share host running: start it, wait until it is ready,
+ * start it again when it exits (backing off), stop it on request.
+ *
+ * Deliberately smaller than the supervisor's own tunnel loop. There is no fallback from a named
+ * tunnel to a quick one, because a review link that was already sent names one address and a
+ * different one helps nobody. There is no public probe, because cloudflared reconnects by itself
+ * and a process that dies is started again here. And there is no adoption across a supervisor
+ * restart: the share host restarts with the supervisor.
+ */
+import { closeSync, existsSync, openSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Subprocess } from "bun";
+import { getPpmDir } from "../ppm-dir.ts";
+import { ensureCloudflared } from "../cloudflared.service.ts";
+import { waitForLogLine } from "../named-tunnel/named-tunnel-readiness.ts";
+import { withoutNotifySocket } from "../sd-notify.ts";
+import { createLogger } from "../logger.ts";
+
+const log = createLogger("share-host");
+
+export const SHARE_CONNECTOR_LOG = () => resolve(getPpmDir(), "cloudflared-share.log");
+export const QUICK_URL_RE = /https:\/\/(?!api\.)[a-z0-9-]+\.trycloudflare\.com/;
+export const NAMED_READY_RE = /Registered tunnel connection/;
+const READY_TIMEOUT_MS = 30_000;
+/** A connector that stayed up this long starts its next backoff from the beginning. */
+const STABLE_MS = 5 * 60_000;
+
+export interface ConnectorPlan {
+  /** What this connector is, for the log (`quick`, `named share.example.com`). */
+  label: string;
+  args: string[];
+  /** A named tunnel's address is known up front; a quick tunnel's is read from its log. */
+  url: string | null;
+}
+
+export interface ConnectorEvents {
+  onReady(info: { pid: number; url: string }): void;
+  onDown(reason: string): void;
+}
+
+export interface ConnectorDeps {
+  cloudflared?: () => Promise<string>;
+  spawn?: (cmd: string[], logFd: number) => Subprocess;
+  /** Serialises spawns with the supervisor's port probes (a probe socket must not be inherited). */
+  gate?: <T>(fn: () => T | Promise<T>) => Promise<T>;
+  logPath?: () => string;
+  readyTimeoutMs?: number;
+  backoffMs?: (failures: number) => number;
+}
+
+function defaultSpawn(cmd: string[], logFd: number): Subprocess {
+  // An explicit env: without one, Bun hands over the environment the supervisor started with.
+  return Bun.spawn(cmd, {
+    stdin: "ignore", stdout: "ignore", stderr: logFd, env: withoutNotifySocket(process.env), windowsHide: true,
+  });
+}
+
+/** 1 s, 2 s, 4 s … up to a minute, plus up to a second of jitter. */
+export function defaultBackoffMs(failures: number): number {
+  return Math.min(60_000, 1000 * 2 ** Math.max(0, failures - 1)) + Math.floor(Math.random() * 1000);
+}
+
+/** The last error cloudflared logged since `offset`, as ` — <message>`, or nothing. */
+function lastError(logPath: string, offset: number): string {
+  try {
+    const lines = readFileSync(logPath).subarray(offset).toString("utf8").split("\n");
+    const line = lines.reverse().find((l) => / ERR /.test(l));
+    return line ? ` — ${line.replace(/^.*? ERR /, "").trim().slice(0, 200)}` : "";
+  } catch {
+    return "";
+  }
+}
+
+export class ShareConnector {
+  private generation = 0;
+  private child: Subprocess | null = null;
+  private current: ConnectorPlan | null = null;
+
+  constructor(private readonly deps: ConnectorDeps = {}) {}
+
+  get pid(): number | null {
+    return this.child?.pid ?? null;
+  }
+
+  /** The plan running now, or null when stopped. */
+  get plan(): ConnectorPlan | null {
+    return this.current;
+  }
+
+  /** Run `plan`, replacing whatever runs now. */
+  start(plan: ConnectorPlan, events: ConnectorEvents): void {
+    this.stop();
+    const generation = ++this.generation;
+    this.current = plan;
+    void this.loop(generation, plan, events);
+  }
+
+  stop(): void {
+    this.generation++;
+    this.current = null;
+    const child = this.child;
+    this.child = null;
+    if (child) {
+      try { child.kill("SIGTERM"); } catch {}
+    }
+  }
+
+  private live(generation: number): boolean {
+    return generation === this.generation;
+  }
+
+  private async loop(generation: number, plan: ConnectorPlan, events: ConnectorEvents): Promise<void> {
+    let failures = 0;
+    while (this.live(generation)) {
+      const startedAt = Date.now();
+      const reason = await this.runOnce(generation, plan, events);
+      if (!this.live(generation)) return;
+      events.onDown(reason);
+      failures = Date.now() - startedAt >= STABLE_MS ? 1 : failures + 1;
+      const delay = (this.deps.backoffMs ?? defaultBackoffMs)(failures);
+      log.warn(`Share host connector (${plan.label}) ${reason} — starting again in ${Math.round(delay / 1000)}s`);
+      await Bun.sleep(delay);
+    }
+  }
+
+  /** One connector process, from spawn to exit. Resolves with why it is gone. */
+  private async runOnce(generation: number, plan: ConnectorPlan, events: ConnectorEvents): Promise<string> {
+    let bin: string;
+    try {
+      bin = await (this.deps.cloudflared ?? ensureCloudflared)();
+    } catch (error) {
+      return `could not get cloudflared (${error})`;
+    }
+    if (!this.live(generation)) return "stopped";
+
+    const logPath = (this.deps.logPath ?? SHARE_CONNECTOR_LOG)();
+    // Best-effort: Windows refuses while a previous connector still holds the file, which is why
+    // readiness is read only from the bytes after `offset`.
+    try { unlinkSync(logPath); } catch {}
+    const offset = existsSync(logPath) ? statSync(logPath).size : 0;
+    const fd = openSync(logPath, "a");
+    let child: Subprocess;
+    try {
+      const spawn = () => (this.deps.spawn ?? defaultSpawn)([bin, ...plan.args], fd);
+      child = await (this.deps.gate ? this.deps.gate(spawn) : spawn());
+    } catch (error) {
+      return `failed to start (${error})`;
+    } finally {
+      try { closeSync(fd); } catch {} // the child keeps its own copy
+    }
+    if (!this.live(generation)) {
+      try { child.kill("SIGTERM"); } catch {}
+      return "stopped";
+    }
+    this.child = child;
+
+    try {
+      const matched = await waitForLogLine(logPath, plan.url ? NAMED_READY_RE : QUICK_URL_RE, {
+        fromByteOffset: offset,
+        timeoutMs: this.deps.readyTimeoutMs ?? READY_TIMEOUT_MS,
+        getExitCode: () => child.exitCode,
+      });
+      if (this.live(generation)) {
+        const url = plan.url ?? matched;
+        log.info(`Share host connector ready: ${url} (${plan.label}, PID ${child.pid})`);
+        events.onReady({ pid: child.pid, url });
+      }
+    } catch (error) {
+      try { child.kill("SIGTERM"); } catch {}
+      await child.exited;
+      if (this.child === child) this.child = null;
+      return `did not connect (${error instanceof Error ? error.message : error})${lastError(logPath, offset)}`;
+    }
+
+    const code = await child.exited;
+    if (this.child === child) this.child = null;
+    return `exited (code ${code})${lastError(logPath, offset)}`;
+  }
+}

package/src/services/share-host/share-host-gateway.ts

@@ -0,0 +1,181 @@
+/**
+ * The share host's request handler: the review pages, and nothing else of PPM.
+ *
+ * A request is forwarded to the PPM server on loopback only when its path is part of the
+ * reviewer surface: `/s` and everything under it (the page, its info, the pinned design's files
+ * and the comment threads, see `design-share-guest*.ts`) and the review page's own build,
+ * `/assets/share-*`. Every other path — the IDE, `/api`, sign-in, WebSockets, the app shell —
+ * is answered here with a 404 and never reaches PPM, so a public share host is not a public
+ * PPM. The decision is made on the parsed URL, whose dot segments are already resolved, and the
+ * same parsed path is what gets forwarded, so PPM cannot route anything other than what was
+ * checked.
+ *
+ * What is forwarded:
+ * - `Host`, untouched: the design files' CSP is built from it, and the rate limiter believes
+ *   `CF-Connecting-IP` only for the public hostnames it knows (`design-share-client-key.ts`).
+ * - Never `Authorization` or `Cookie`: nothing on the reviewer surface reads them, and a
+ *   credential from the internet has no business reaching PPM.
+ * - Bodies as they are, compressed ones included (`decompress: false`), so a `.br` asset is
+ *   not inflated under a `Content-Encoding: br` header.
+ */
+
+/** The reviewer surface's paths, decided on an already-parsed pathname. */
+export function isShareHostPath(pathname: string): boolean {
+  if (pathname === "/s" || pathname.startsWith("/s/")) return true;
+  // The review page's own Vite build (`vite.share.config.ts`): `assets/share-[hash][ext]`.
+  return /^\/assets\/share-[A-Za-z0-9_-]+(?:\.[A-Za-z0-9]+)+$/.test(pathname);
+}
+
+const ASSET_METHODS = new Set(["GET", "HEAD"]);
+/** What the `/s` routes answer to: reads, and the reviewer's comment writes. */
+const SHARE_METHODS = new Set(["GET", "HEAD", "POST", "PATCH", "DELETE"]);
+
+/** Request headers that describe this hop, or carry a credential, and stop here. */
+const DROPPED_REQUEST_HEADERS = new Set([
+  "connection", "keep-alive", "proxy-connection", "proxy-authorization", "te", "trailer",
+  "transfer-encoding", "upgrade", "authorization", "cookie", "content-length", "expect",
+]);
+/** Response headers that describe the hop from PPM, not the one to the browser. */
+const DROPPED_RESPONSE_HEADERS = new Set([
+  "connection", "keep-alive", "proxy-connection", "te", "trailer", "transfer-encoding", "upgrade",
+]);
+
+/** A reviewer write is at most 16 KB (`GUEST_WRITE_MAX_BYTES`); anything near this is not one. */
+export const MAX_FORWARDED_BODY_BYTES = 64 * 1024;
+/** How long a request waits for PPM to come back while it restarts. */
+const CONNECT_WINDOW_MS = 5000;
+const CONNECT_RETRY_MS = 250;
+/** No reviewer request takes this long; a hung one is cut off rather than held open. */
+const UPSTREAM_TIMEOUT_MS = 60_000;
+
+export interface ShareHostGatewayDeps {
+  /** PPM's loopback port now (`.server-port`), or null while it is not up. */
+  targetPort: () => number | null;
+  /** Forget a cached port after a failed connect, so the next try reads it again. */
+  resetTargetPort?: () => void;
+  fetch?: typeof fetch;
+  connectWindowMs?: number;
+  timeoutMs?: number;
+}
+
+const PAGE_HEADERS = {
+  "Content-Type": "text/html; charset=utf-8",
+  "Cache-Control": "no-store",
+  "X-Content-Type-Options": "nosniff",
+  "X-Robots-Tag": "noindex, nofollow",
+  "Referrer-Policy": "no-referrer",
+  "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'",
+};
+
+function page(status: number, title: string, text: string): Response {
+  const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="robots" content="noindex, nofollow"><title>${title}</title><style>body{font:15px/1.5 system-ui,sans-serif;max-width:32rem;margin:15vh auto;padding:0 1.5rem;color:#333}@media (prefers-color-scheme:dark){body{background:#111;color:#ddd}}</style></head><body><h1 style="font-size:1.25rem">${title}</h1><p>${text}</p></body></html>`;
+  return new Response(body, { status, headers: PAGE_HEADERS });
+}
+
+export const notFoundPage = () => page(404, "Not found", "There is nothing at this address.");
+const unavailablePage = () => {
+  const res = page(503, "Temporarily unavailable", "This review page cannot be reached right now. Try again in a moment.");
+  res.headers.set("Retry-After", "5");
+  return res;
+};
+const timeoutPage = () => page(504, "Took too long", "This review page did not answer in time. Try again in a moment.");
+const tooLargePage = () => page(413, "Too large", "That request is larger than a review page accepts.");
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * The request body, or null once it is past `limit`. Read chunk by chunk because a chunked upload
+ * has no Content-Length to refuse up front, and Bun.serve's `maxRequestBodySize` does not stop
+ * one: on Bun 1.3.11 and 1.3.13 a 32 MB chunked body reached the handler whole with it set to 64 KB.
+ */
+async function readBodyUpTo(req: Request, limit: number): Promise<Uint8Array | null> {
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  if (req.body) {
+    const reader = req.body.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > limit) {
+        await reader.cancel().catch(() => {});
+        return null;
+      }
+      chunks.push(value);
+    }
+  }
+  const body = new Uint8Array(size);
+  let at = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, at);
+    at += chunk.byteLength;
+  }
+  return body;
+}
+
+/** True for the error a refused or reset connection raises, as opposed to a timeout. */
+function isConnectFailure(error: unknown): boolean {
+  const code = (error as { code?: unknown })?.code;
+  return code === "ConnectionRefused" || code === "ECONNREFUSED" || code === "ConnectionClosed" || code === "ECONNRESET";
+}
+
+export function createShareHostHandler(deps: ShareHostGatewayDeps): (req: Request) => Promise<Response> {
+  const doFetch = deps.fetch ?? fetch;
+  const connectWindowMs = deps.connectWindowMs ?? CONNECT_WINDOW_MS;
+  const timeoutMs = deps.timeoutMs ?? UPSTREAM_TIMEOUT_MS;
+
+  return async (req: Request): Promise<Response> => {
+    const url = new URL(req.url);
+    if (!isShareHostPath(url.pathname)) return notFoundPage();
+    const isAsset = url.pathname.startsWith("/assets/");
+    if (!(isAsset ? ASSET_METHODS : SHARE_METHODS).has(req.method)) return notFoundPage();
+
+    const headers = new Headers();
+    req.headers.forEach((value, name) => {
+      if (!DROPPED_REQUEST_HEADERS.has(name.toLowerCase())) headers.set(name, value);
+    });
+
+    let body: Uint8Array | undefined;
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      const declared = Number(req.headers.get("content-length") ?? "0");
+      if (declared > MAX_FORWARDED_BODY_BYTES) return tooLargePage();
+      const read = await readBodyUpTo(req, MAX_FORWARDED_BODY_BYTES);
+      if (read === null) return tooLargePage();
+      body = read;
+    }
+
+    const deadline = Date.now() + connectWindowMs;
+    for (;;) {
+      const port = deps.targetPort();
+      if (port !== null) {
+        try {
+          const upstream = await doFetch(`http://127.0.0.1:${port}${url.pathname}${url.search}`, {
+            method: req.method,
+            headers,
+            body,
+            redirect: "manual",
+            decompress: false,
+            signal: AbortSignal.timeout(timeoutMs),
+          } as RequestInit);
+          const out = new Headers();
+          upstream.headers.forEach((value, name) => {
+            if (!DROPPED_RESPONSE_HEADERS.has(name.toLowerCase())) out.append(name, value);
+          });
+          const noBody = req.method === "HEAD" || upstream.status === 204 || upstream.status === 304;
+          return new Response(noBody ? null : upstream.body, {
+            status: upstream.status,
+            statusText: upstream.statusText,
+            headers: out,
+          });
+        } catch (error) {
+          if ((error as { name?: unknown })?.name === "TimeoutError") return timeoutPage();
+          if (!isConnectFailure(error)) return unavailablePage();
+          // PPM is restarting, or moved to another port: read the port again and retry.
+          deps.resetTargetPort?.();
+        }
+      }
+      if (Date.now() >= deadline) return unavailablePage();
+      await sleep(CONNECT_RETRY_MS);
+    }
+  };
+}