@podosoft/podokit 0.16.4 → 0.17.1

package/dist/templates/todo/Dockerfile.dev

@@ -1,6 +1,24 @@
 # Development image for the PodoKit monorepo (web + api).
 # Dependencies and source are baked in; `docker compose watch` syncs your
 # edits into the running container so the native file watchers fire.
+
+# Every workspace manifest, collected rather than listed.
+#
+# Listing them by hand only works for the workspaces this template starts with. A
+# project that adds `packages/*` then has workspace manifests that never reach the
+# image, so npm does not know those names are local and goes looking for them on the
+# public registry — `npm error 404 '@scope/thing' is not in this registry`, from an
+# install that succeeds on the developer's own machine. The production images
+# collect manifests for exactly this reason; this one was the exception until a
+# generated project with shared packages could not start its dev stack at all.
+FROM node:22-bookworm-slim AS manifests
+WORKDIR /src
+COPY . .
+RUN mkdir -p /app \
+    && cp package.json /app/ \
+    && find . -name package.json -not -path "*/node_modules/*" \
+         -exec sh -c 'mkdir -p "/app/$(dirname "$1")" && cp "$1" "/app/$1"' _ {} \;
+
 FROM node:22-bookworm-slim
 
 # git for the toolchain (editors, AI agents); build tools for native modules.
@@ -14,9 +32,7 @@ WORKDIR /app
 # NB: the host package-lock.json is intentionally NOT copied — a lockfile
 # generated on macOS/Windows prunes platform-specific optional deps and can drop
 # packages (e.g. @swc/cli) on linux. Resolving fresh in-container avoids that.
-COPY package.json ./
-COPY apps/api/package.json ./apps/api/package.json
-COPY apps/web/package.json ./apps/web/package.json
+COPY --from=manifests /app ./
 ARG PODOKIT_NPM_REGISTRY=""
 RUN if [ -n "$PODOKIT_NPM_REGISTRY" ]; then npm config set registry "$PODOKIT_NPM_REGISTRY"; fi \
   && npm install
@@ -24,4 +40,19 @@ RUN if [ -n "$PODOKIT_NPM_REGISTRY" ]; then npm config set registry "$PODOKIT_NP
 # Baked source (kept in sync during development by `docker compose watch`).
 COPY . .
 
+# Workspace packages compile before the apps that import them. Apps import them by
+# their published entry point (`dist/index.js`), so without this the API starts and
+# dies on MODULE_NOT_FOUND for a package whose symlink is right there — the link
+# resolves, the built file behind it does not exist. `--if-present` keeps a project
+# with no packages, or one whose packages need no build, working unchanged.
+#
+# `docker compose watch` syncs app source only, so a change under packages/* needs
+# this image rebuilt rather than a container restart.
+RUN if [ -d packages ]; then \
+      for manifest in packages/*/package.json; do \
+        [ -e "$manifest" ] || continue; \
+        npm run build --if-present --workspace "$(dirname "$manifest")"; \
+      done; \
+    fi
+
 EXPOSE 5001 5002

package/dist/templates/todo/apps/api/Dockerfile

@@ -1,27 +1,88 @@
 # syntax=docker/dockerfile:1
+
+# The npm that reads package-lock.json must be the major that wrote it. node:22
+# bundles npm 10, and a lockfile written by npm 11 records platform-specific
+# packages as extraneous with no `optional` flag; npm 10 rejects those with
+# EBADPLATFORM instead of skipping them, so `npm ci` fails inside the image while
+# `npm install` on the developer's machine is fine. Keep this in step with the npm
+# the project is developed with.
+ARG NPM_VERSION=11.17.0
+
+# Every workspace manifest, and nothing else.
+#
+# Listing them by hand only works for the workspaces this template starts with: npm
+# does NOT fail when a workspace's package.json is absent, it silently installs a
+# tree without that package's dependencies. A project that adds packages/* then
+# builds against different versions than it resolves locally, and only inside the
+# image. Collecting them keeps `npm ci` correct whatever the workspace layout is,
+# and the stages below still cache on the manifests' content.
+FROM node:22-alpine AS manifests
+WORKDIR /src
+COPY . .
+RUN mkdir -p /app \
+    && cp package.json package-lock.json /app/ \
+    && find . -name package.json -not -path "*/node_modules/*" \
+         -exec sh -c 'mkdir -p "/app/$(dirname "$1")" && cp "$1" "/app/$1"' _ {} \;
+
 FROM node:22-alpine AS deps
 WORKDIR /app
-COPY package.json package-lock.json ./
-COPY apps/api/package.json ./apps/api/package.json
-COPY apps/web/package.json ./apps/web/package.json
-COPY tests/package.json ./tests/package.json
+COPY --from=manifests /app ./
+ARG NPM_VERSION
+RUN npm i -g "npm@${NPM_VERSION}"
 RUN npm ci --no-audit --no-fund
 
+# Production dependencies only, resolved from the same lockfile. The runtime stage
+# copies node_modules from here and never from deps or build, so the shipped image
+# does not carry the TypeScript compiler, Vite, or the test tooling.
+FROM node:22-alpine AS prod-deps
+WORKDIR /app
+COPY --from=manifests /app ./
+ARG NPM_VERSION
+RUN npm i -g "npm@${NPM_VERSION}"
+# The runtime tree for this image only.
+#
+# Scoping to the one workspace matters: --omit=dev at the root still installs the
+# union of every workspace's production dependencies, so the API image carried Vite
+# and the web image carried Nest. Measured on a generated project, this is 198
+# packages instead of 283. TypeScript stays either way -- typeorm depends on ts-node,
+# which depends on it, so it is a production dependency and not bloat.
+RUN npm ci --omit=dev --no-audit --no-fund --workspace=apps/api --include-workspace-root
+
 FROM node:22-alpine AS build
 WORKDIR /app
-COPY --from=deps /app/node_modules ./node_modules
+# Everything npm ci produced, not just the root node_modules: npm nests any
+# dependency it cannot hoist, and copying only the root directory leaves a workspace
+# package compiling against the wrong version of it.
+COPY --from=deps /app ./
 COPY . .
+# Local workspace packages compile before the app that imports them. Apps import
+# them by their published entry points and .dockerignore excludes dist, so nothing
+# here has compiled output until it is compiled here.
+RUN if [ -d packages ]; then \
+      for manifest in packages/*/package.json; do \
+        [ -e "$manifest" ] || continue; \
+        npm run build --if-present --workspace "$(dirname "$manifest")"; \
+      done; \
+    fi
 RUN npm run build --workspace=apps/api
+# The runtime needs the real workspace package directories, not just the symlinks
+# npm leaves in node_modules pointing at them. Without this the image boots and
+# dies on "Cannot find module <package>" -- a dangling link, at runtime only.
+# mkdir keeps the COPY valid for a project that has no packages/ at all.
+RUN mkdir -p /app/packages
 
 FROM node:22-alpine AS runtime
 WORKDIR /app
 ENV NODE_ENV=production
 RUN addgroup -S -g 101 app && adduser -S -D -H -u 100 -G app app
-COPY --from=build /app/node_modules ./node_modules
-COPY --from=deps /app/apps/api ./apps/api
+COPY --from=prod-deps /app/node_modules ./node_modules
+COPY --from=manifests /app/apps/api ./apps/api
+COPY --from=build /app/packages ./packages
 COPY --from=build /app/apps/api/dist ./apps/api/dist
 COPY --from=build /app/apps/api/scripts ./apps/api/scripts
 WORKDIR /app/apps/api
 USER 100:101
 EXPOSE 3000
+HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=6 \
+  CMD node -e "fetch('http://127.0.0.1:3000/health/ready').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
 CMD ["node", "dist/main"]

package/dist/templates/todo/apps/web/Dockerfile

@@ -1,26 +1,78 @@
 # syntax=docker/dockerfile:1
+
+# The npm that reads package-lock.json must be the major that wrote it. node:22
+# bundles npm 10, and a lockfile written by npm 11 records platform-specific
+# packages as extraneous with no `optional` flag; npm 10 rejects those with
+# EBADPLATFORM instead of skipping them, so `npm ci` fails inside the image while
+# `npm install` on the developer's machine is fine. Keep this in step with the npm
+# the project is developed with.
+ARG NPM_VERSION=11.17.0
+
+# See apps/api/Dockerfile for why the workspace manifests are collected rather than
+# listed: an absent workspace package.json does not fail `npm ci`, it silently
+# changes the resolved dependency tree inside the image.
+FROM node:22-alpine AS manifests
+WORKDIR /src
+COPY . .
+RUN mkdir -p /app \
+    && cp package.json package-lock.json /app/ \
+    && find . -name package.json -not -path "*/node_modules/*" \
+         -exec sh -c 'mkdir -p "/app/$(dirname "$1")" && cp "$1" "/app/$1"' _ {} \;
+
 FROM node:22-alpine AS deps
 WORKDIR /app
-COPY package.json package-lock.json ./
-COPY apps/api/package.json ./apps/api/package.json
-COPY apps/web/package.json ./apps/web/package.json
-COPY tests/package.json ./tests/package.json
+COPY --from=manifests /app ./
+ARG NPM_VERSION
+RUN npm i -g "npm@${NPM_VERSION}"
 RUN npm ci --no-audit --no-fund
 
+FROM node:22-alpine AS prod-deps
+WORKDIR /app
+COPY --from=manifests /app ./
+ARG NPM_VERSION
+RUN npm i -g "npm@${NPM_VERSION}"
+# The runtime tree for this image only.
+#
+# Scoping to the one workspace matters: --omit=dev at the root still installs the
+# union of every workspace's production dependencies, so the API image carried Vite
+# and the web image carried Nest. Measured on a generated project, this is 198
+# packages instead of 283. TypeScript stays either way -- typeorm depends on ts-node,
+# which depends on it, so it is a production dependency and not bloat.
+RUN npm ci --omit=dev --no-audit --no-fund --workspace=apps/web --include-workspace-root
+
 FROM node:22-alpine AS build
 WORKDIR /app
-COPY --from=deps /app/node_modules ./node_modules
+COPY --from=deps /app ./
 COPY . .
+RUN if [ -d packages ]; then \
+      for manifest in packages/*/package.json; do \
+        [ -e "$manifest" ] || continue; \
+        npm run build --if-present --workspace "$(dirname "$manifest")"; \
+      done; \
+    fi
 RUN npm run build --workspace=apps/web
+# The runtime needs the real workspace package directories, not just the symlinks
+# npm leaves in node_modules pointing at them. Without this the image boots and
+# dies on "Cannot find module <package>" -- a dangling link, at runtime only.
+# mkdir keeps the COPY valid for a project that has no packages/ at all.
+RUN mkdir -p /app/packages
 
 FROM node:22-alpine AS runtime
 WORKDIR /app
 ENV NODE_ENV=production
 RUN addgroup -S -g 101 app && adduser -S -D -H -u 100 -G app app
-COPY --from=build /app/node_modules ./node_modules
-COPY --from=deps /app/apps/web ./apps/web
+COPY --from=prod-deps /app/node_modules ./node_modules
+COPY --from=manifests /app/apps/web ./apps/web
+COPY --from=build /app/packages ./packages
 COPY --from=build /app/apps/web/build ./apps/web/build
+# The entry and the modules it imports run OUTSIDE the bundle, so they ship as
+# source. Without them the image falls back to an entry that cannot answer a
+# WebSocket upgrade.
+COPY --from=build /app/apps/web/server.js ./apps/web/server.js
+COPY --from=build /app/apps/web/src/lib/server ./apps/web/src/lib/server
 WORKDIR /app/apps/web
 USER 100:101
 EXPOSE 3000
-CMD ["node", "build"]
+HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=6 \
+  CMD node -e "fetch('http://127.0.0.1:3000/').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
+CMD ["node", "server.js"]

package/dist/templates/todo/apps/web/server.js

@@ -0,0 +1,31 @@
+/**
+ * The production entry point: adapter-node's server plus WebSocket upgrades.
+ *
+ * `node build` — adapter-node's own entry — serves HTTP perfectly well and drops
+ * every WebSocket upgrade into SvelteKit, which cannot answer one. This entry keeps
+ * adapter-node in charge of listening, graceful shutdown, and the PORT/HOST/
+ * IDLE_TIMEOUT contract, and adds the one thing it cannot do.
+ *
+ * Nothing is proxied unless `WS_PROXY_PATHS` names a path, so a deployment that has
+ * no WebSocket behaves exactly as `node build` did.
+ *
+ * ⚠ Not type-checked: it imports `./build/`, which only exists after `npm run build`,
+ * and lint must not depend on a build. Everything with a decision in it lives in
+ * `src/lib/server/ws-upgrade.js`, which is unit-tested; this is wiring.
+ */
+import { server } from "./build/index.js";
+import { createUpgradeProxy, relayPaths } from "./src/lib/server/ws-upgrade.js";
+
+const allowed = relayPaths();
+if (allowed.size > 0) {
+  // polka exposes the http.Server it was handed. If a future adapter stops doing so,
+  // fail at boot: serving silently without upgrades is the bug this entry exists for.
+  const httpServer = server.server;
+  if (!httpServer || typeof httpServer.on !== "function") {
+    throw new Error(
+      "adapter-node did not expose its HTTP server; the WebSocket upgrade proxy cannot be mounted",
+    );
+  }
+  httpServer.on("upgrade", createUpgradeProxy({ allowed }));
+  console.log(`Mounted WebSocket upgrade proxy for ${[...allowed].join(", ")}`);
+}

package/dist/templates/todo/apps/web/src/lib/server/backend-proxy.test.ts

@@ -55,4 +55,25 @@ describe("backend proxy client address handling", () => {
     expect(response.status).toBe(204);
     expect(upstreamHeaders?.get("x-forwarded-for")).toBe("203.0.113.9");
   });
+
+  // Not forwarding this does not leave the header unset: fetch substitutes its own
+  // default, so the API records "node" for every session and the account page shows
+  // that as the device for all of them.
+  it("forwards the browser's user agent so sessions record the real device", async () => {
+    let upstreamHeaders: Headers | undefined;
+    vi.stubGlobal("fetch", async (_input: RequestInfo | URL, init?: RequestInit) => {
+      upstreamHeaders = new Headers(init?.headers);
+      return new Response(null, { status: 204 });
+    });
+
+    const agent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/141.0.0.0 Safari/537.36";
+    const request = new Request("http://app.localhost/api/auth/sign-in/email", {
+      method: "POST",
+      headers: { "user-agent": agent },
+    });
+    const response = await proxyRequest(request, "http://api:5002/auth/sign-in/email");
+
+    expect(response.status).toBe(204);
+    expect(upstreamHeaders?.get("user-agent")).toBe(agent);
+  });
 });

package/dist/templates/todo/apps/web/src/lib/server/backend-proxy.ts

@@ -1,7 +1,21 @@
 // Server-side proxy boundary. The browser never talks to the API directly:
 // requests go through SvelteKit server routes, which forward an allowlist of
 // headers to BACKEND_INTERNAL_URL and relay the response (including Set-Cookie).
-const FORWARDED_HEADERS = ["authorization", "cookie", "content-type", "accept", "origin", "referer"];
+//
+// `user-agent` is on the list for the same reason the client IP is forwarded
+// below: better-auth records it on the session and the account page shows it as
+// the device. Leaving it off does not produce an empty column -- fetch supplies
+// its own default, so every session in the database reads "node", and the list
+// of "your devices" becomes a list of identical rows that identify nothing.
+const FORWARDED_HEADERS = [
+  "authorization",
+  "cookie",
+  "content-type",
+  "accept",
+  "origin",
+  "referer",
+  "user-agent",
+];
 const RELAYED_RESPONSE_HEADERS = ["content-type", "location", "cache-control"];
 
 export function backendBaseUrl(): string {

package/dist/templates/todo/apps/web/src/lib/server/ws-upgrade.js

@@ -0,0 +1,267 @@
+/**
+ * WebSocket upgrades, proxied by the web server itself.
+ *
+ * WHY THIS EXISTS: a SvelteKit server route cannot serve a WebSocket upgrade.
+ * `+server.ts` handlers answer HTTP requests and never see an `upgrade` event, and
+ * the `/api/*` proxy is HTTP-only for the same reason — `fetch` cannot carry a 101.
+ * Meanwhile a deployment routes all public traffic to the web app, so an API
+ * WebSocket gateway has no path to reach at all. Development hides this, because
+ * Vite proxies upgrades; the feature then dies silently once deployed.
+ *
+ * ⚠ NOTHING IS FORWARDED BY DEFAULT. `WS_PROXY_PATHS` names the exact paths that may
+ * upgrade, comma-separated, and anything else is destroyed rather than proxied. A
+ * relay that forwards any path is an open tunnel to every private route on the API,
+ * reachable from the public origin without a session. Adding a path is a security
+ * decision, not a routing tweak — the API must authorise that socket at handshake
+ * time, from the session cookie or its own credential.
+ *
+ * This file is plain JavaScript on purpose: `server.js` imports `./build/`, which
+ * only exists after a build, so the entry point cannot be type-checked. Everything
+ * with a decision in it lives here, where it is unit-tested.
+ */
+import http from "node:http";
+import https from "node:https";
+
+/** @typedef {Record<string, string | string[] | undefined>} Headers */
+/** @typedef {{ kind: "proxy", path: string } | { kind: "reject", reason: string }} UpgradeDecision */
+
+/**
+ * The upgrade paths this deployment allows, matched whole — never as a prefix, a
+ * wildcard, or a pattern.
+ *
+ * @returns {ReadonlySet<string>}
+ */
+export function relayPaths() {
+  return new Set(
+    (process.env.WS_PROXY_PATHS ?? "")
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.startsWith("/")),
+  );
+}
+
+/** Where upgrades are sent. Same target the HTTP proxy uses. */
+export function backendBaseUrl() {
+  return process.env.BACKEND_INTERNAL_URL ?? "http://localhost:5002";
+}
+
+/**
+ * Normalize a client address for the forwarded header: map loopback to a clean IPv4
+ * value and unwrap IPv4-mapped addresses.
+ *
+ * @param {string | undefined} address
+ * @returns {string | undefined}
+ */
+export function normalizeClientIp(address) {
+  if (!address) return undefined;
+  if (address === "::1" || address === "::") return "127.0.0.1";
+  if (address.startsWith("::ffff:")) return address.slice("::ffff:".length);
+  return address;
+}
+
+/**
+ * Should this upgrade be forwarded, and under which normalized path?
+ *
+ * The path is re-serialised from `URL` rather than echoed, so a target that only
+ * looks like an allowed path after resolving `..` cannot reach anything else. A
+ * request target carrying its own authority is refused outright.
+ *
+ * @param {string | undefined} url `req.url`, an origin-form request target
+ * @param {Headers} headers
+ * @param {ReadonlySet<string>} [allowed]
+ * @returns {UpgradeDecision}
+ */
+export function decideUpgrade(url, headers, allowed = relayPaths()) {
+  const upgrade = String(headers.upgrade ?? "").toLowerCase();
+  if (upgrade !== "websocket") return { kind: "reject", reason: "not a websocket upgrade" };
+  if (!url || !url.startsWith("/") || url.startsWith("//")) {
+    return { kind: "reject", reason: "not an origin-form request target" };
+  }
+  let parsed;
+  try {
+    parsed = new URL(url, "http://upgrade.invalid");
+  } catch {
+    return { kind: "reject", reason: "unparsable request target" };
+  }
+  if (!allowed.has(parsed.pathname)) return { kind: "reject", reason: "not an allowed upgrade path" };
+  return { kind: "proxy", path: `${parsed.pathname}${parsed.search}` };
+}
+
+/**
+ * What the API is told about the request.
+ *
+ * Handshake headers and the session cookie pass through untouched — the API
+ * authorises the socket from them, so dropping either turns every connection into a
+ * 401. The `x-forwarded-*` trio is appended rather than replaced: behind another
+ * proxy this server is one hop in a chain, and overwriting it reports the wrong
+ * client upstream.
+ *
+ * @param {Headers} headers
+ * @param {{ remoteAddress?: string, encrypted?: boolean }} socket
+ * @returns {Headers}
+ */
+export function upstreamHeaders(headers, socket) {
+  /** @type {Headers} */
+  const forwarded = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (value === undefined) continue;
+    if (name === "x-forwarded-for" || name === "x-forwarded-proto" || name === "x-forwarded-host") {
+      continue;
+    }
+    forwarded[name] = value;
+  }
+
+  const client = normalizeClientIp(socket.remoteAddress);
+  const chain = [headers["x-forwarded-for"], client]
+    .flat()
+    .filter((entry) => typeof entry === "string" && entry.length > 0);
+  if (chain.length > 0) forwarded["x-forwarded-for"] = chain.join(", ");
+
+  forwarded["x-forwarded-proto"] = headers["x-forwarded-proto"] ?? (socket.encrypted ? "https" : "http");
+  const host = headers["x-forwarded-host"] ?? headers.host;
+  if (host !== undefined) forwarded["x-forwarded-host"] = host;
+
+  return forwarded;
+}
+
+/**
+ * @param {string} path
+ * @param {Headers} headers
+ */
+export function upstreamOptions(path, headers) {
+  const base = new URL(backendBaseUrl());
+  return {
+    protocol: base.protocol,
+    hostname: base.hostname,
+    port: base.port || (base.protocol === "https:" ? "443" : "80"),
+    path,
+    headers,
+  };
+}
+
+/**
+ * @param {string} statusLine
+ * @param {Headers} headers
+ * @returns {string}
+ */
+function rawHead(statusLine, headers) {
+  const lines = [statusLine];
+  for (const [name, value] of Object.entries(headers)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) for (const item of value) lines.push(`${name}: ${item}`);
+    else lines.push(`${name}: ${value}`);
+  }
+  return `${lines.join("\r\n")}\r\n\r\n`;
+}
+
+/**
+ * Streaming sockets carry many small frames, so Nagle's algorithm adds latency to
+ * every one, and the default timeout would cut an idle-but-attached connection.
+ *
+ * @param {{ setTimeout?: Function, setNoDelay?: Function, setKeepAlive?: Function }} socket
+ */
+function tune(socket) {
+  socket.setTimeout?.(0);
+  socket.setNoDelay?.(true);
+  socket.setKeepAlive?.(true, 0);
+}
+
+/** The real transport: one upstream HTTP request carrying the upgrade. */
+const nodeConnect = (options, hooks) => {
+  const transport = options.protocol === "https:" ? https : http;
+  const upstream = transport.request({
+    protocol: options.protocol,
+    hostname: options.hostname,
+    port: options.port,
+    path: options.path,
+    method: "GET",
+    headers: options.headers,
+  });
+  upstream.on("upgrade", (response, socket, head) => {
+    hooks.onUpgrade(response.statusCode ?? 101, response.headers, socket, head);
+  });
+  upstream.on("response", (response) => {
+    hooks.onResponse(response.statusCode ?? 502, response.statusMessage ?? "", response.headers);
+    response.resume(); // Drain, or the socket is never released.
+  });
+  upstream.on("error", (error) => hooks.onError(error.message));
+  upstream.end();
+  return { abort: () => upstream.destroy() };
+};
+
+/**
+ * @typedef {object} UpstreamHooks
+ * @property {(status: number, headers: Headers, socket: any, head: Uint8Array | null) => void} onUpgrade
+ * @property {(status: number, statusMessage: string, headers: Headers) => void} onResponse
+ * @property {(reason: string) => void} onError
+ */
+
+/** @typedef {(options: ReturnType<typeof upstreamOptions>, hooks: UpstreamHooks) => { abort: () => void }} Connect */
+
+/**
+ * Build the `upgrade` listener the built server mounts.
+ *
+ * The transport is injected so the decisions here are testable without a socket.
+ *
+ * @param {{ connect?: Connect, allowed?: ReadonlySet<string> }} [options]
+ */
+export function createUpgradeProxy(options = {}) {
+  const connect = options.connect ?? nodeConnect;
+  const allowed = options.allowed ?? relayPaths();
+
+  return function onUpgrade(request, socket, head) {
+    const decision = decideUpgrade(request.url, request.headers, allowed);
+    if (decision.kind === "reject") {
+      socket.destroy();
+      return;
+    }
+
+    tune(socket);
+    // Bytes the client already sent belong to the stream: push them back so the pipe
+    // below carries them upstream in order.
+    if (head && head.length > 0) socket.unshift(head);
+
+    let clientGone = false;
+    const upstream = connect(
+      upstreamOptions(decision.path, upstreamHeaders(request.headers, socket)),
+      {
+        onUpgrade(status, headers, upstreamSocket, upstreamHead) {
+          if (clientGone) {
+            upstreamSocket.destroy();
+            return;
+          }
+          if (upstreamHead && upstreamHead.length > 0) upstreamSocket.unshift(upstreamHead);
+          tune(upstreamSocket);
+          socket.write(rawHead(`HTTP/1.1 ${status} Switching Protocols`, headers));
+          // A client that hangs forever is worse than one told it lost the relay, so
+          // either end closing takes the other down.
+          upstreamSocket.on("error", () => socket.destroy());
+          upstreamSocket.on("close", () => socket.end());
+          upstreamSocket.pipe(socket);
+          socket.pipe(upstreamSocket);
+        },
+        onResponse(status, statusMessage, headers) {
+          // The API refused the handshake. Relaying ITS answer is what turns "the
+          // socket vanished" into a diagnosable failure in the browser.
+          socket.write(
+            rawHead(`HTTP/1.1 ${status} ${statusMessage}`.trim(), {
+              ...headers,
+              connection: "close",
+            }),
+          );
+          socket.end();
+        },
+        onError() {
+          socket.write(rawHead("HTTP/1.1 502 Bad Gateway", { connection: "close" }));
+          socket.end();
+        },
+      },
+    );
+
+    socket.on("error", () => upstream.abort());
+    socket.on("close", () => {
+      clientGone = true;
+      upstream.abort();
+    });
+  };
+}