@moondeck/station 0.0.0-stage → 1.0.0

package/lib/preview-sidecar.ts

@@ -0,0 +1,331 @@
+/**
+ * ADR-043: per-(task, preview) node-proxy sidecar for ad-hoc preview ports.
+ *
+ * Ad-hoc preview ports aren't Docker-published, and the app container's bridge
+ * IP isn't host-routable on macOS/OrbStack (EHOSTUNREACH). So proxy through a
+ * tiny sidecar: a container on the task's compose network that PUBLISHES a
+ * `127.0.0.1` host port (reachable on every backend) and forwards to
+ * `<app-container>:<containerPort>`. The sidecar runs the task's OWN image
+ * (always local — no registry pull) under `node` with a ~5-line `net` TCP proxy;
+ * node streams give backpressure + handle WebSockets (Metro/HMR).
+ *
+ * The cache deduplicates creation, but every tunnel open re-proves the exact
+ * sidecar container and its current Docker mapping. A process-lifetime cached
+ * localhost port is unsafe across an unnoticed daemon restart: another process
+ * can inherit that port before the bridge reconnects and triggers recovery.
+ */
+import net from "node:net";
+
+import { dockerCli } from "./docker-exec";
+import { inspectTunnelContainer } from "./tunnel-runtime";
+
+/** Port the proxy listens on inside the sidecar (published to a random host port). */
+const INNER_PORT = 9000;
+/**
+ * Exported for every "which container is the task's APP" scan: sidecars can
+ * legitimately wear the task's compose project/service labels (teardown
+ * finds them by project), so any container carrying THIS label must be
+ * excluded before counting app containers. Live 2026-08-18: one browser
+ * sidecar with compose labels made legacy adoption count two app containers
+ * and fail the whole runtime selection closed — every task on the host read
+ * as "still starting".
+ */
+export const PREVIEW_SIDECAR_TASK_LABEL = "io.moondeck.preview-sidecar.task";
+const LABEL = PREVIEW_SIDECAR_TASK_LABEL;
+const TARGET_LABEL = "io.moondeck.preview-sidecar.target";
+
+/** (taskId,name,containerPort) -> published 127.0.0.1 host port of a live sidecar. */
+const cache = new Map<string, number>();
+/** In-flight creates, so concurrent requests for the same key share one sidecar. */
+const inflight = new Map<string, Promise<number | null>>();
+
+function cacheKey(taskId: string, name: string, containerPort: number): string {
+  return `${taskId} ${name} ${containerPort}`;
+}
+
+function sidecarName(taskId: string, name: string): string {
+  return `uai-preview-${taskId}-${name}`;
+}
+
+function proxyScript(appContainer: string, containerPort: number): string {
+  // Bidirectional TCP pipe: 0.0.0.0:INNER_PORT <-> appContainer:containerPort.
+  return (
+    `const net=require('net');` +
+    `net.createServer(c=>{` +
+    `const u=net.connect(${containerPort},${JSON.stringify(appContainer)});` +
+    `c.on('error',()=>u.destroy());u.on('error',()=>c.destroy());` +
+    `c.pipe(u);u.pipe(c);` +
+    `}).listen(${INNER_PORT},'0.0.0.0');`
+  );
+}
+
+/** How long to wait for a new sidecar's proxy to start accepting. */
+const READY_TIMEOUT_MS = 10_000;
+const READY_POLL_MS = 100;
+/** A connection that survives this long AFTER connecting has a live upstream. */
+const PROBE_SETTLE_MS = 150;
+/** A handshake that hasn't completed by now isn't going to. */
+const PROBE_CONNECT_MS = 1_000;
+
+/** The bit of `net.Socket` the probe uses — so a test can supply its own. */
+interface SocketLike {
+  on: (event: string, fn: () => void) => unknown;
+  destroy: () => void;
+}
+
+/**
+ * Whether the whole chain behind `hostPort` is live: the proxy is listening AND
+ * its upstream connect succeeded.
+ *
+ * A plain "did the TCP connect succeed" check proves nothing here, which is the
+ * trap this exists for. Docker publishes the port when the CONTAINER starts,
+ * not when the process inside binds — so `docker-proxy` accepts the connection
+ * either way and then closes it, and an HTTP client reports that as
+ * `socket hang up`. The sidecar's proxy behaves identically when it is up but
+ * its own upstream connect fails (`u.on('error',()=>c.destroy())`).
+ *
+ * So the signal is the connection SURVIVING briefly, not opening. Both failure
+ * modes close it immediately; a healthy pipe just sits there waiting for a
+ * request, which is the one thing neither of them does.
+ */
+function probeSidecar(
+  hostPort: number,
+  /** Seam for tests: a socket that never connects can't be produced locally. */
+  connect: (port: number) => SocketLike = (port) =>
+    net.connect(port, "127.0.0.1"),
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = connect(hostPort);
+    let settled = false;
+    let settleTimer: ReturnType<typeof setTimeout> | undefined;
+    const done = (ok: boolean): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(settleTimer);
+      clearTimeout(connectTimer);
+      socket.destroy();
+      resolve(ok);
+    };
+    // The settle window starts at `connect`, NOT at the call. Starting it here
+    // would count a connection still stuck in the handshake as healthy — the
+    // one state that is neither of the two we can distinguish, and the one a
+    // wedged host is most likely to be in.
+    //
+    // The connect deadline is disarmed at the same moment, or the two overlap:
+    // a connection established at 900ms would be failed at 1000ms, 50ms into a
+    // 150ms settle window it was on course to pass. The deadlines are
+    // sequential — first "did it connect", then "did it stay" — so only one may
+    // be running.
+    socket.on("connect", () => {
+      clearTimeout(connectTimer);
+      settleTimer = setTimeout(() => done(true), PROBE_SETTLE_MS);
+    });
+    const connectTimer = setTimeout(() => done(false), PROBE_CONNECT_MS);
+    socket.on("error", () => done(false));
+    socket.on("close", () => done(false));
+  });
+}
+
+/** Test seam: the probe with an injectable socket. Not used in production. */
+export const probeForTest = probeSidecar;
+
+/** Poll `probeSidecar` until the chain answers, or give up. */
+async function waitUntilReady(hostPort: number): Promise<boolean> {
+  const deadline = Date.now() + READY_TIMEOUT_MS;
+  for (;;) {
+    if (await probeSidecar(hostPort)) return true;
+    if (Date.now() >= deadline) return false;
+    await new Promise((r) => setTimeout(r, READY_POLL_MS));
+  }
+}
+
+async function imageOf(appContainer: string): Promise<string | null> {
+  const r = await dockerCli(
+    ["inspect", "-f", "{{.Config.Image}}", appContainer],
+    { timeoutMs: 5_000 },
+  );
+  return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : null;
+}
+
+/** Live Docker proof -> the published 127.0.0.1 host port and labels, or null. */
+async function publishedSidecar(
+  name: string,
+): Promise<{ port: number; labels: Record<string, string> } | null> {
+  const proof = await inspectTunnelContainer(name, INNER_PORT);
+  return proof.kind === "running" && proof.published?.host === "127.0.0.1"
+    ? { port: proof.published.port, labels: proof.labels }
+    : null;
+}
+
+async function publishedPort(name: string): Promise<number | null> {
+  return (await publishedSidecar(name))?.port ?? null;
+}
+
+async function createSidecar(args: {
+  taskId: string;
+  composeProject: string;
+  name: string;
+  containerPort: number;
+}): Promise<number | null> {
+  const name = sidecarName(args.taskId, args.name);
+  const appContainer = `${args.composeProject}-app-1`;
+  const target = `${appContainer}:${args.containerPort}`;
+
+  // Reuse a still-running sidecar from a previous host process (--rm keeps it up
+  // across a host restart; the in-memory cache was cleared). `docker port` is an
+  // exact-name lookup, so no name-filter regex pitfalls.
+  //
+  // PROBED, not just found. A sidecar outlives the app container it proxies to,
+  // so one left over from a previous container generation is still running and
+  // still publishing its port while its route is dead. Reused blind, that
+  // sidecar serves `socket hang up` forever: the recovery path invalidates the
+  // CACHE on a failed connect, then lands right back here and returns the same
+  // corpse. Nothing could break the cycle short of removing it by hand.
+  const existing = await publishedSidecar(name);
+  if (existing !== null) {
+    // The Docker name is stable per (task, preview name), while a task-scoped
+    // preview may later point that name at another container port. The
+    // process-local cache key carries the port, but it vanishes on host
+    // restart; without a durable target label a healthy old proxy would be
+    // reused and silently route the authenticated request to the wrong port.
+    // Legacy unlabeled sidecars rebuild once.
+    if (
+      existing.labels[TARGET_LABEL] === target &&
+      (await probeSidecar(existing.port))
+    ) {
+      return existing.port;
+    }
+    await dockerCli(["rm", "-f", name], { timeoutMs: 10_000 });
+  }
+
+  const image = await imageOf(appContainer);
+  if (!image) return null;
+
+  await dockerCli(["rm", "-f", name], { timeoutMs: 10_000 });
+  const run = await dockerCli(
+    [
+      "run", "-d", "--rm",
+      "--name", name,
+      "--network", `${args.composeProject}_default`,
+      "--label", `${LABEL}=${args.taskId}`,
+      "--label", `${TARGET_LABEL}=${target}`,
+      "-p", `127.0.0.1::${INNER_PORT}`,
+      "--entrypoint", "node",
+      image,
+      "-e", proxyScript(appContainer, args.containerPort),
+    ],
+    { timeoutMs: 20_000 },
+  );
+  if (run.status !== 0) return null;
+
+  const hostPort = await publishedPort(name);
+  if (hostPort === null) {
+    await dockerCli(["rm", "-f", name], { timeoutMs: 10_000 });
+    return null;
+  }
+
+  // Do not hand back a port that isn't answering yet. `docker run -d` returns
+  // when the CONTAINER starts and the mapping exists from that instant, but the
+  // node proxy inside has not called `listen` — so every request arriving in
+  // that window is accepted by docker-proxy and dropped.
+  //
+  // A browser makes that window very expensive. It fetches the document, then
+  // fires every sub-resource at once: one page load put ~20 requests into a
+  // ~3s gap and lost all of them, which renders as an unstyled page with broken
+  // images rather than as anything resembling "not ready yet".
+  if (!(await waitUntilReady(hostPort))) {
+    await dockerCli(["rm", "-f", name], { timeoutMs: 10_000 });
+    return null;
+  }
+  return hostPort;
+}
+
+/**
+ * Ensure a sidecar is proxying `<app>:<containerPort>` for (taskId, name);
+ * returns the `127.0.0.1` host port it publishes, or null on failure. Cache-only
+ * on the hot path; a cache miss creates the sidecar (deduped across concurrent
+ * callers).
+ */
+export async function ensurePreviewSidecar(args: {
+  taskId: string;
+  composeProject: string;
+  name: string;
+  containerPort: number;
+}): Promise<number | null> {
+  const key = cacheKey(args.taskId, args.name, args.containerPort);
+  const cached = cache.get(key);
+  if (cached !== undefined) {
+    const current = await publishedSidecar(sidecarName(args.taskId, args.name));
+    const expectedTarget =
+      `${args.composeProject}-app-1:${args.containerPort}`;
+    const app =
+      current?.port === cached &&
+      current.labels[TARGET_LABEL] === expectedTarget
+        ? await inspectTunnelContainer(
+            `${args.composeProject}-app-1`,
+            args.containerPort,
+          )
+        : null;
+    // The sidecar's PID is the proxy itself, and it resolves the app by stable
+    // Compose DNS name for each connection. Proving both exact containers are
+    // running avoids the old 150ms socket-settle penalty on every browser asset
+    // while still rejecting a localhost port inherited after daemon restart.
+    if (
+      current?.port === cached &&
+      current.labels[TARGET_LABEL] === expectedTarget &&
+      app?.kind === "running"
+    ) {
+      return cached;
+    }
+    cache.delete(key);
+  }
+
+  let pending = inflight.get(key);
+  if (!pending) {
+    pending = createSidecar(args)
+      .then((port) => {
+        if (port !== null) cache.set(key, port);
+        return port;
+      })
+      .finally(() => inflight.delete(key));
+    inflight.set(key, pending);
+  }
+  return pending;
+}
+
+/**
+ * Drop the cached port for a sidecar whose route just failed. No-op for
+ * published-declared / container-IP targets, which aren't in this cache.
+ *
+ * CACHE-ONLY, deliberately. This fires from the host's `upstream.on("error")`,
+ * which cannot tell a dead sidecar from a client that hit stop mid-download or
+ * a request that tripped the tunnel's ack deadline — both destroy the socket
+ * with ECONNRESET. Removing the container here would let one abandoned asset
+ * kill a sidecar that is serving twenty other requests fine, which is a worse
+ * failure than the one being recovered from.
+ *
+ * Forgetting the port is enough now: the next `createSidecar` finds the
+ * container by name and PROBES it, so a genuinely dead one is removed there,
+ * where the evidence is direct rather than inferred. That is the escape hatch
+ * this used to lack — invalidation alone kept landing back on the same corpse.
+ */
+export function invalidatePreviewSidecar(hostPort: number): void {
+  for (const [key, port] of cache) {
+    if (port === hostPort) cache.delete(key);
+  }
+}
+
+/** Stop + remove all preview sidecars for a task (called on task-down). */
+export async function stopPreviewSidecars(taskId: string): Promise<void> {
+  for (const key of [...cache.keys()]) {
+    if (key.startsWith(`${taskId} `)) cache.delete(key);
+  }
+  const r = await dockerCli(
+    ["ps", "-aq", "--filter", `label=${LABEL}=${taskId}`],
+    { timeoutMs: 5_000 },
+  );
+  if (r.status !== 0) return;
+  for (const id of r.stdout.split("\n").map((s) => s.trim()).filter(Boolean)) {
+    await dockerCli(["rm", "-f", id], { timeoutMs: 10_000 });
+  }
+}