@sproutboat/toolchain 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @sproutboat/toolchain
+
+## 0.3.0
+
+### Minor Changes
+
+- New package: `@sproutboat/toolchain` — the single home for the Porffor pin
+  (`pin.ts`), the source patches (`patch.ts`: `ensurePorfforPatched` plus the
+  `$PORT`, request-body-limit, status-line, console-sink and remote-address
+  passes), and `ensurePorffor()` (fetch, verify sha256, extract, patch, cache in
+  `~/.cache/sproutboat`).
+  
+  `sproutboat-cli` and the `sproutboat` monorepo both depend on it instead of
+  carrying their own copies, so the pin and the patch set can no longer drift —
+  which they had (the monorepo was on `alpha-4` and applied 1 of the ~13 patches).

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@sproutboat/toolchain",
+  "version": "0.3.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./pin": "./src/pin.ts",
+    "./patch": "./src/patch.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "bun test ./"
+  }
+}

package/src/acquire.test.ts

@@ -0,0 +1,145 @@
+import { afterEach, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import { mkdtemp, mkdir, readFile, readdir, rm, utimes, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { ensurePorffor, PORFFOR_COMMIT_FULL, PorfforToolchainError } from "./index";
+
+const temporary: string[] = [];
+afterEach(async () => {
+  await Promise.all(temporary.splice(0).map((path) => rm(path, { recursive: true, force: true })));
+});
+
+async function fixture(): Promise<{ archive: string; sha256: string }> {
+  const root = await mkdtemp(join(tmpdir(), "sb-porffor-fixture-"));
+  temporary.push(root);
+  const source = join(root, `porffor-${PORFFOR_COMMIT_FULL}`);
+  const files = {
+    "runtime/index.js": "fixture:runtime/index.js\n",
+    "compiler/render.js":
+      "void porf_native_fetch_runtime_init(void) {\n  signal(SIGPIPE, SIG_IGN);\n  porf_init(0, NULL);\n}\n" +
+      "f64 porf_native_fetch_get_port(void) {\nfixture:compiler/render.js\n",
+    "compiler/index.js": "          '-xc', '-', '-c',\n          uSocketsArchive,\n          '-lm'\n",
+    "compiler/uwebsockets.js":
+      "static const size_t REQUEST_BODY_MAX_BYTES = 1024u * 1024u;\n" +
+      "static std::string_view lookup_status_line(i32 status) {\n" +
+      '  switch (status) {\n    case 302: return "302 Found";\n    default: return {};\n  }\n}\n' +
+      "static i32 collect_headers(uWS::HttpRequest* req) {\n" +
+      "  i32 header_capacity = 0;\n" +
+      "  const i32 header_bytes = 16 + header_capacity * 8;\n" +
+      "  i32 slot = 0;\n  for (auto [key, value] : *req) {\n    slot++;\n  }\n" +
+      "  *((i32*)(porf_mem + headers_ptr)) = slot;\n\n  return headers_ptr;\n}\n" +
+      "static void on_request(uWS::HttpResponse<false>* res, uWS::HttpRequest* req) {\n" +
+      "  const i32 headers_ptr = collect_headers(req);\n}\n",
+  };
+  for (const [file, contents] of Object.entries(files)) {
+    const path = join(source, file);
+    await mkdir(join(path, ".."), { recursive: true });
+    await writeFile(path, contents);
+  }
+  const archive = join(root, "porffor.tar.gz");
+  const tar = Bun.spawn(["tar", "-czf", archive, "-C", root, basename(source)], { stderr: "pipe" });
+  const [code, stderr] = await Promise.all([tar.exited, new Response(tar.stderr).text()]);
+  if (code !== 0) throw new Error(`could not create fixture: ${stderr}`);
+  const sha256 = createHash("sha256")
+    .update(await readFile(archive))
+    .digest("hex");
+  return { archive, sha256 };
+}
+
+test("Porffor acquisition is atomic, shared concurrently, and warm-cache offline", async () => {
+  const { archive, sha256 } = await fixture();
+  const cacheRoot = await mkdtemp(join(tmpdir(), "sb-porffor-cache-"));
+  temporary.push(cacheRoot);
+  let requests = 0;
+  const fetcher = async () => {
+    requests += 1;
+    await Bun.sleep(5);
+    return new Response(Bun.file(archive));
+  };
+  const options = { cacheRoot, url: "fixture", expectedSha256: sha256, fetcher };
+  const roots = await Promise.all(Array.from({ length: 8 }, () => ensurePorffor(options)));
+  expect(new Set(roots).size).toBe(1);
+  expect(requests).toBe(1);
+  expect((await readdir(cacheRoot)).filter((name) => name.startsWith(".porffor-"))).toEqual([]);
+  const offline = await ensurePorffor({
+    ...options,
+    fetcher: async () => {
+      throw new Error("offline fetch must not run");
+    },
+  });
+  expect(offline).toBe(roots[0]);
+});
+
+test("integrity failures stop acquisition and publish no cache entry", async () => {
+  const { archive } = await fixture();
+  const cacheRoot = await mkdtemp(join(tmpdir(), "sb-porffor-integrity-"));
+  temporary.push(cacheRoot);
+  const error = await ensurePorffor({
+    cacheRoot,
+    url: "fixture",
+    expectedSha256: "0".repeat(64),
+    fetcher: async () => new Response(Bun.file(archive)),
+  }).catch((cause: unknown) => cause);
+  expect(error).toBeInstanceOf(PorfforToolchainError);
+  if (!(error instanceof PorfforToolchainError)) throw error;
+  expect(error.kind).toBe("integrity");
+  expect((await readdir(cacheRoot)).some((name) => name.startsWith("porffor-"))).toBe(false);
+});
+
+test("a corrupted warm cache is replaced from the verified archive", async () => {
+  const { archive, sha256 } = await fixture();
+  const cacheRoot = await mkdtemp(join(tmpdir(), "sb-porffor-corrupt-"));
+  temporary.push(cacheRoot);
+  let requests = 0;
+  const options = {
+    cacheRoot,
+    url: "fixture",
+    expectedSha256: sha256,
+    fetcher: async () => {
+      requests += 1;
+      return new Response(Bun.file(archive));
+    },
+  };
+  const root = await ensurePorffor(options);
+  await writeFile(join(root, "compiler/render.js"), "corrupt");
+  await ensurePorffor(options);
+  expect(requests).toBe(2);
+  expect(await readFile(join(root, "compiler/render.js"), "utf8")).toContain('getenv("PORT")');
+});
+
+test("an interrupted stale lock is recovered", async () => {
+  const { archive, sha256 } = await fixture();
+  const cacheRoot = await mkdtemp(join(tmpdir(), "sb-porffor-interrupted-"));
+  temporary.push(cacheRoot);
+  const lock = join(cacheRoot, `porffor-${PORFFOR_COMMIT_FULL}.lock`);
+  await mkdir(lock);
+  const stale = new Date(Date.now() - 10 * 60_000);
+  await utimes(lock, stale, stale);
+  const root = await ensurePorffor({
+    cacheRoot,
+    url: "fixture",
+    expectedSha256: sha256,
+    fetcher: async () => new Response(Bun.file(archive)),
+  });
+  expect(await readFile(join(root, "runtime/index.js"), "utf8")).toContain("fixture:");
+  expect((await readdir(cacheRoot)).some((name) => name.endsWith(".lock"))).toBe(false);
+});
+
+test("download failures are classified without publishing partial state", async () => {
+  const cacheRoot = await mkdtemp(join(tmpdir(), "sb-porffor-download-"));
+  temporary.push(cacheRoot);
+  let attempts = 0;
+  const error = await ensurePorffor({
+    cacheRoot,
+    url: "https://invalid.test/source.tar.gz",
+    fetcher: async () => {
+      attempts += 1;
+      throw new Error("offline");
+    },
+  }).catch((cause: unknown) => cause);
+  if (!(error instanceof PorfforToolchainError)) throw error;
+  expect(error.kind).toBe("download");
+  expect(attempts).toBe(2);
+  expect(await readdir(cacheRoot)).toEqual([]);
+});

package/src/acquire.ts

@@ -0,0 +1,163 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { ensurePorfforPatched } from "./patch";
+import { PORFFOR_ARCHIVE_SHA256, PORFFOR_ARCHIVE_URL, PORFFOR_COMMIT_FULL } from "./pin";
+
+export class PorfforToolchainError extends Error {
+  constructor(
+    readonly kind: "download" | "integrity" | "archive" | "cache" | "unsupported",
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+type AcquireOptions = {
+  cacheRoot?: string;
+  url?: string;
+  expectedSha256?: string;
+  fetcher?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+  timeoutMs?: number;
+};
+
+const required = ["runtime/index.js", "compiler/render.js", "compiler/index.js", "compiler/uwebsockets.js"];
+async function digest(path: string): Promise<string> {
+  return createHash("sha256")
+    .update(await readFile(path))
+    .digest("hex");
+}
+
+async function complete(dir: string, expectedArchive = PORFFOR_ARCHIVE_SHA256): Promise<boolean> {
+  try {
+    // SAFETY: the cache manifest is private data written below; every consumed
+    // field is still checked before it can make the cache valid.
+    const manifest = JSON.parse(await readFile(resolve(dir, ".sproutboat-complete"), "utf8")) as {
+      commit?: string;
+      archiveSha256?: string;
+      files?: Record<string, string>;
+    };
+    if (manifest.commit !== PORFFOR_COMMIT_FULL || manifest.archiveSha256 !== expectedArchive) return false;
+    for (const file of required)
+      if (!manifest.files?.[file] || (await digest(resolve(dir, file))) !== manifest.files[file]) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function download(
+  url: string,
+  path: string,
+  fetcher: (input: string | URL | Request, init?: RequestInit) => Promise<Response>,
+  timeoutMs: number,
+): Promise<void> {
+  let last: unknown;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const response = await fetcher(url, { signal: AbortSignal.timeout(timeoutMs) });
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      await writeFile(path, new Uint8Array(await response.arrayBuffer()));
+      return;
+    } catch (error) {
+      last = error;
+    }
+  }
+  throw new PorfforToolchainError(
+    "download",
+    `could not download pinned Porffor from ${url}: ${last instanceof Error ? last.message : String(last)}`,
+  );
+}
+
+async function extract(archive: string, stage: string): Promise<void> {
+  const child = Bun.spawn(["tar", "-xzf", archive, "-C", stage, "--strip-components=1"], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [code, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()]);
+  if (code !== 0)
+    throw new PorfforToolchainError("archive", `could not extract pinned Porffor archive: ${stderr.trim()}`);
+  for (const file of required)
+    if (!existsSync(resolve(stage, file)))
+      throw new PorfforToolchainError("archive", `Porffor archive is missing required file ${file}`);
+}
+
+async function waitForPublisher(dir: string, lock: string): Promise<string | null> {
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    if (await complete(dir)) return dir;
+    if (!existsSync(lock)) return null;
+    const age = Date.now() - (await stat(lock)).mtimeMs;
+    if (age > 5 * 60_000) {
+      await rm(lock, { recursive: true, force: true });
+      return null;
+    }
+    await Bun.sleep(25);
+  }
+  throw new PorfforToolchainError("cache", `timed out waiting for Porffor cache lock ${lock}`);
+}
+
+/** Acquire the immutable compiler source into a verified, atomically published cache entry. */
+export async function ensurePorffor(options: AcquireOptions = {}): Promise<string> {
+  const override = process.env.SPROUTBOAT_PORFFOR_DIR;
+  if (override) {
+    const dir = resolve(override);
+    for (const file of required)
+      if (!existsSync(resolve(dir, file)))
+        throw new PorfforToolchainError("unsupported", `SPROUTBOAT_PORFFOR_DIR is missing ${file}`);
+    return dir;
+  }
+  const root = resolve(
+    options.cacheRoot ?? process.env.SPROUTBOAT_TOOLCHAIN_CACHE ?? resolve(homedir(), ".cache/sproutboat"),
+  );
+  const dir = resolve(root, `porffor-${PORFFOR_COMMIT_FULL}`);
+  const expected = options.expectedSha256 ?? PORFFOR_ARCHIVE_SHA256;
+  if (await complete(dir, expected)) return dir;
+  await mkdir(root, { recursive: true });
+  const lock = `${dir}.lock`;
+  try {
+    await mkdir(lock);
+  } catch {
+    const published = await waitForPublisher(dir, lock);
+    if (published) return published;
+    return ensurePorffor(options);
+  }
+  const stage = resolve(root, `.porffor-${PORFFOR_COMMIT_FULL}-${process.pid}-${crypto.randomUUID()}`);
+  try {
+    if (await complete(dir, expected)) return dir;
+    await rm(dir, { recursive: true, force: true });
+    await mkdir(stage);
+    const archive = resolve(stage, "source.tar.gz");
+    await download(options.url ?? PORFFOR_ARCHIVE_URL, archive, options.fetcher ?? fetch, options.timeoutMs ?? 30_000);
+    const actual = await digest(archive);
+    if (actual !== expected)
+      throw new PorfforToolchainError(
+        "integrity",
+        `Porffor archive sha256 mismatch\n  expected ${expected}\n  got      ${actual}`,
+      );
+    await extract(archive, stage);
+    await rm(archive, { force: true });
+    await ensurePorfforPatched(stage);
+    const files = Object.fromEntries(
+      await Promise.all(required.map(async (file) => [file, await digest(resolve(stage, file))] as const)),
+    );
+    await writeFile(
+      resolve(stage, ".sproutboat-complete"),
+      JSON.stringify({ commit: PORFFOR_COMMIT_FULL, archiveSha256: actual, files }),
+      { mode: 0o444 },
+    );
+    await rename(stage, dir);
+    return dir;
+  } finally {
+    await rm(stage, { recursive: true, force: true });
+    await rm(lock, { recursive: true, force: true });
+  }
+}
+
+export function cachedPorfforRoot(
+  root = process.env.SPROUTBOAT_TOOLCHAIN_CACHE ?? resolve(homedir(), ".cache/sproutboat"),
+): string {
+  return resolve(root, `porffor-${PORFFOR_COMMIT_FULL}`);
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * `@sproutboat/toolchain` — the one place the Porffor pin and the source
+ * patches live. Both `sproutboat-cli` and the `sproutboat` monorepo depend on
+ * this so they cannot drift apart (which is exactly what happened before).
+ *
+ * - `pin` — the pinned commit + archive hash, and `porfforVersion()`.
+ * - `patch` — `ensurePorfforPatched(root)` and the individual patch passes.
+ * - `acquire` — `ensurePorffor()`: fetch, verify, extract, patch, cache.
+ */
+export * from "./pin";
+export * from "./patch";
+export * from "./acquire";

package/src/patch.test.ts

@@ -0,0 +1,134 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { patchRenderJs, patchUwebsockets } from "./patch";
+
+// The parts of Porffor's compiler/render.js the patch anchors to.
+const RENDER = `void porf_native_fetch_runtime_init(void) {
+#ifdef _WIN32
+  exit(1);
+#else
+  signal(SIGPIPE, SIG_IGN);
+  porf_init(0, NULL);
+#endif
+}
+
+f64 porf_native_fetch_get_port(void) {
+  return __porffor_native_fetch_port.val;
+}
+`;
+
+// Porffor's compiler/uwebsockets.js, trimmed to the parts the patch touches:
+// body limit (#56), the #156 status-line switch, and #163's collect_headers.
+const SHIM = `static const size_t REQUEST_BODY_MAX_BYTES = 1024u * 1024u;
+
+static std::string_view lookup_status_line(i32 status) {
+  switch (status) {
+    case 200: return "200 OK";
+    case 302: return "302 Found";
+    case 429: return "429 Too Many Requests";
+    default: return {};
+  }
+}
+
+static i32 collect_headers(uWS::HttpRequest* req) {
+  i32 header_capacity = 0;
+  for (auto [key, value] : *req) {
+    (void)key;
+    (void)value;
+    header_capacity += 2;
+  }
+  const i32 header_bytes = 16 + header_capacity * 8;
+  const i32 headers_ptr = (i32)porf_native_fetch_alloc((u32)header_bytes, 208);
+  const i32 entries_ptr = headers_ptr + 16;
+  i32 slot = 0;
+  for (auto [key, value] : *req) {
+    *((u64*)(porf_mem + entries_ptr + slot * 8)) = pack_bytestring((i32)porf_native_fetch_alloc_bytestring(key.data(), key.size()));
+    slot++;
+    *((u64*)(porf_mem + entries_ptr + slot * 8)) = pack_bytestring((i32)porf_native_fetch_alloc_bytestring(value.data(), value.size()));
+    slot++;
+  }
+  *((i32*)(porf_mem + headers_ptr)) = slot;
+
+  return headers_ptr;
+}
+
+static void on_request(uWS::HttpResponse<false>* res, uWS::HttpRequest* req) {
+  const i32 headers_ptr = collect_headers(req);
+}
+`;
+
+async function shimDir(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "sb-patch-uws-"));
+  await mkdir(join(root, "compiler"), { recursive: true });
+  await writeFile(join(root, "compiler/uwebsockets.js"), SHIM);
+  return root;
+}
+
+test("#156: status-line fallback synthesizes a line for unlisted codes, idempotently", async () => {
+  const root = await shimDir();
+  try {
+    await patchUwebsockets(root);
+    const once = await readFile(join(root, "compiler/uwebsockets.js"), "utf8");
+
+    // Return type widened, empty fallback replaced, known cases untouched.
+    expect(once).toContain("static std::string lookup_status_line(i32 status) {");
+    expect(once).not.toContain("std::string_view lookup_status_line");
+    expect(once).toContain('default: return std::to_string(status) + " Status";');
+    expect(once).not.toContain("default: return {};");
+    expect(once).toContain('case 302: return "302 Found";');
+    // 303 gets its real phrase; the switch stays well-formed (302 still present once).
+    expect(once).toContain('case 303: return "303 See Other";');
+    expect(once.match(/case 302: return "302 Found";/g)).toHaveLength(1);
+    // Body-limit edit still rides along.
+    expect(once).toContain("sb_request_body_max");
+
+    // #163: collect_headers takes res, drops a client-sent x-sb-remote-addr, and
+    // appends the real peer; the call site passes res through.
+    expect(once).toContain("static i32 collect_headers(uWS::HttpRequest* req, uWS::HttpResponse<false>* res) {");
+    expect(once).toContain("const i32 headers_ptr = collect_headers(req, res);");
+    expect(once).toContain('if (key == "x-sb-remote-addr") continue;');
+    expect(once).toContain("res->getRemoteAddressAsText()");
+    expect(once).toContain('porf_native_fetch_alloc_bytestring("x-sb-remote-addr", 16)');
+    expect(once).toContain("header_capacity += 2;");
+
+    await patchUwebsockets(root);
+    expect(await readFile(join(root, "compiler/uwebsockets.js"), "utf8")).toBe(once);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("a drifted shim fails loudly instead of silently no-op'ing", async () => {
+  const root = await mkdtemp(join(tmpdir(), "sb-patch-uws-drift-"));
+  try {
+    await mkdir(join(root, "compiler"), { recursive: true });
+    await writeFile(join(root, "compiler/uwebsockets.js"), "// nothing the patch recognizes\n");
+    await expect(patchUwebsockets(root)).rejects.toThrow(/anchor not found/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("#165: render.js routes console output to stderr, unbuffered, idempotently", async () => {
+  const root = await mkdtemp(join(tmpdir(), "sb-patch-render-"));
+  try {
+    await mkdir(join(root, "compiler"), { recursive: true });
+    await writeFile(join(root, "compiler/render.js"), RENDER);
+    await patchRenderJs(root);
+    const once = await readFile(join(root, "compiler/render.js"), "utf8");
+
+    expect(once).toContain("dup2(2, 1);");
+    expect(once).toContain("setvbuf(stdout, NULL, _IONBF, 0);");
+    // Injected inside runtime_init, right after the SIGPIPE line.
+    expect(once).toMatch(/signal\(SIGPIPE, SIG_IGN\);\n {2}\/\* sproutboat #165/);
+    // The $PORT edit still lands too.
+    expect(once).toContain('getenv("PORT")');
+
+    await patchRenderJs(root);
+    expect(await readFile(join(root, "compiler/render.js"), "utf8")).toBe(once);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/patch.ts

@@ -0,0 +1,262 @@
+/**
+ * Idempotent, marker-guarded in-place edits to Porffor's generated C
+ * (`compiler/render.js`, `compiler/index.js`, `compiler/uwebsockets.js`). Run
+ * from the build path, not a `postinstall` hook: package managers block
+ * dependency lifecycle scripts by default, so a published `postinstall` would
+ * silently not run.
+ *
+ * Each edit is independent and re-applied on every build; a file patched by an
+ * older version of this module still receives the newer edits. All of them are
+ * tracked in patches/UPSTREAM.md and go away as Porffor closes the gaps.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+// --- compiler/render.js: the native-fetch server, rendered as C text ---
+
+/** The `porf_native_fetch_get_port()` open brace: $PORT / --port injection site. */
+const PORT_ANCHOR = "f64 porf_native_fetch_get_port(void) {\n";
+/** Port from $PORT (the supervisor and `sproutboat dev` set it). */
+const PORT_INJECT =
+  '  const char* __sb_port = getenv("PORT");\n' +
+  "  if (__sb_port && *__sb_port) { long __sb_v = strtol(__sb_port, NULL, 10); if (__sb_v > 0 && __sb_v < 65536) return (f64)__sb_v; }\n";
+const PORT_MARKER = 'getenv("PORT")';
+
+/**
+ * baronunread/sproutboat#165 — a handler's `console.log` / `console.error` goes
+ * to stdout via `printf`, which is fully buffered when stdout is not a TTY (a
+ * pipe, a file, a service manager) and never flushed, because the native-fetch
+ * server loop never returns. So the output simply vanishes.
+ *
+ * Point stdout at stderr — the conventional log sink, and where Porffor already
+ * writes its own banner and diagnostics — and make it unbuffered so records
+ * land as they happen. Applies to every native-fetch build; a deployed sprout's
+ * supervisor wants the same records (#87, #146).
+ */
+const CONSOLE_ANCHOR = "  signal(SIGPIPE, SIG_IGN);\n";
+const CONSOLE_INJECT =
+  "  /* sproutboat #165: unbuffered handler console output, routed to stderr */\n" +
+  "  dup2(2, 1);\n" +
+  "  setvbuf(stdout, NULL, _IONBF, 0);\n";
+const CONSOLE_MARKER = "sproutboat #165";
+
+/** render.js edits: `[marker, anchor, inject, what]`, each inserted after its anchor. */
+const RENDER_EDITS = [
+  [PORT_MARKER, PORT_ANCHOR, PORT_INJECT, "$PORT support"],
+  [CONSOLE_MARKER, CONSOLE_ANCHOR, CONSOLE_INJECT, "console output sink (#165)"],
+] as const;
+
+// #15 — no `--port` flag: Porffor's native-fetch entry point calls
+// `porf_init(0, NULL)` (see porf_native_fetch_runtime_init in render.js), so a
+// native-fetch binary never sees argv at all. A standalone binary takes its
+// port and data directory from the environment instead, which is what systemd
+// and docker set anyway. Worth an upstream note alongside the $PORT ask.
+
+/**
+ * #15 — let the build add objects to the native-fetch link line.
+ *
+ * Porffor builds `linkArgs` as a fixed array, so an embedded backend that needs
+ * SQLite compiled into the sprout has nowhere to put it. `CXX` is not a way in:
+ * a musl (deploy) build overrides it outright. This splices one spread of
+ * `SB_EXTRA_LINK` before `-lm`, inert unless the variable is set.
+ */
+const LINK_ANCHOR = "          uSocketsArchive,\n          '-lm'\n";
+const LINK_INJECT =
+  "          ...(process.env.SB_EXTRA_LINK ? process.env.SB_EXTRA_LINK.split(' ').filter(Boolean) : []),\n";
+const LINK_MARKER = "SB_EXTRA_LINK";
+
+/**
+ * #15 — and the same for the compile step, so the prelude's inline C can
+ * `#include <bearssl.h>`. The link patch alone is not enough: Porffor compiles
+ * the generated C from stdin with a fixed argument list, so there is otherwise
+ * no way to add an include path.
+ */
+const CFLAGS_ANCHOR = "          '-xc', '-', '-c',\n";
+const CFLAGS_INJECT =
+  "          ...(process.env.SB_EXTRA_CFLAGS ? process.env.SB_EXTRA_CFLAGS.split(' ').filter(Boolean) : []),\n";
+const CFLAGS_MARKER = "SB_EXTRA_CFLAGS";
+
+/**
+ * #56 — make the inbound request-body limit configurable.
+ *
+ * Porffor's uWebSockets shim hardcodes 1 MiB and answers anything larger with a
+ * bare `413 request body too large` before the handler runs, so a project can
+ * neither accept a bigger upload nor say anything useful about the refusal.
+ *
+ * The default stays 1 MiB: a larger body is held in memory whole, so raising it
+ * is a decision about this deployment's memory, not something to inherit.
+ */
+const BODY_ANCHOR = "static const size_t REQUEST_BODY_MAX_BYTES = 1024u * 1024u;";
+const BODY_INJECT = `static size_t sb_request_body_max(void) {
+  static size_t cached = 0;
+  if (cached == 0) {
+    const char* raw = getenv("SB_REQUEST_BODY_MAX");
+    long parsed = raw && *raw ? atol(raw) : 0;
+    cached = parsed > 0 ? (size_t)parsed : 1024u * 1024u;
+  }
+  return cached;
+}
+#define REQUEST_BODY_MAX_BYTES sb_request_body_max()`;
+const BODY_MARKER = "sb_request_body_max";
+
+/**
+ * baronunread/sproutboat#156 — `lookup_status_line()` maps a status code to a
+ * reason string for `res->writeStatus()`, and any code missing from its switch
+ * (303, 206, 300, 305, 402, 451, ...) falls to `default: return {}` — an empty
+ * status line, which uWS emits as a malformed response and the client sees as a
+ * connection reset. Only the embedded/standalone path hits this; the broker
+ * serializes its own status line.
+ *
+ * Rather than chase the IANA registry case by case, synthesize a valid line for
+ * anything unlisted from the number itself (return type widens to `std::string`;
+ * the sole caller feeds it straight to `writeStatus`, which copies synchronously).
+ * Known codes keep their proper reason phrase.
+ */
+const STATUS_SIG_ANCHOR = "static std::string_view lookup_status_line(i32 status) {";
+const STATUS_SIG_INJECT = "static std::string lookup_status_line(i32 status) {";
+const STATUS_SIG_MARKER = "static std::string lookup_status_line(i32 status) {";
+// 303 is the one this was reported for (POST-redirect-GET); give it the real
+// reason phrase. Everything else unlisted rides the synthesized fallback below.
+const STATUS_303_ANCHOR = '    case 302: return "302 Found";\n';
+const STATUS_303_INJECT = '    case 302: return "302 Found";\n    case 303: return "303 See Other";\n';
+const STATUS_303_MARKER = 'case 303: return "303 See Other";';
+const STATUS_DEFAULT_ANCHOR = "    default: return {};";
+const STATUS_DEFAULT_INJECT = '    default: return std::to_string(status) + " Status";';
+const STATUS_DEFAULT_MARKER = 'std::to_string(status) + " Status"';
+
+/**
+ * baronunread/sproutboat#163 — a native-fetch handler has no way to see the
+ * connection's remote address, so standalone apps hand-roll `X-Forwarded-For`
+ * parsing with a spoofable boolean flag. Nothing but C on the socket side can
+ * reach the peer, so `collect_headers` (the one place request headers cross into
+ * JS) grows a `res` argument and appends `x-sb-remote-addr:
+ * <res->getRemoteAddressAsText()>`. Any client-sent header of that name is
+ * dropped first — it is reserved, the server owns it. The prelude reads it into
+ * `request.cf.clientIp` and resolves it against `SB_TRUSTED_PROXIES` if set.
+ */
+const HDR_SIG_ANCHOR = "static i32 collect_headers(uWS::HttpRequest* req) {\n";
+const HDR_SIG_INJECT = "static i32 collect_headers(uWS::HttpRequest* req, uWS::HttpResponse<false>* res) {\n";
+const HDR_SIG_MARKER = "collect_headers(uWS::HttpRequest* req, uWS::HttpResponse";
+
+const HDR_CALL_ANCHOR = "const i32 headers_ptr = collect_headers(req);";
+const HDR_CALL_INJECT = "const i32 headers_ptr = collect_headers(req, res);";
+const HDR_CALL_MARKER = "collect_headers(req, res)";
+
+const HDR_CAP_ANCHOR = "  const i32 header_bytes = 16 + header_capacity * 8;\n";
+const HDR_CAP_INJECT =
+  "  header_capacity += 2; // sproutboat #163: room for the x-sb-remote-addr entry\n" +
+  "  const i32 header_bytes = 16 + header_capacity * 8;\n";
+const HDR_CAP_MARKER = "sproutboat #163";
+
+const HDR_SKIP_ANCHOR = "  i32 slot = 0;\n  for (auto [key, value] : *req) {\n";
+const HDR_SKIP_INJECT =
+  "  i32 slot = 0;\n  for (auto [key, value] : *req) {\n" +
+  '    if (key == "x-sb-remote-addr") continue; // #163: reserved, the server sets it below\n';
+const HDR_SKIP_MARKER = 'key == "x-sb-remote-addr"';
+
+const HDR_APPEND_ANCHOR = "  *((i32*)(porf_mem + headers_ptr)) = slot;\n\n  return headers_ptr;";
+const HDR_APPEND_INJECT =
+  "  {\n" +
+  "    const std::string_view __sb_peer = res ? res->getRemoteAddressAsText() : std::string_view();\n" +
+  '    *((u64*)(porf_mem + entries_ptr + slot * 8)) = pack_bytestring((i32)porf_native_fetch_alloc_bytestring("x-sb-remote-addr", 16));\n' +
+  "    slot++;\n" +
+  "    *((u64*)(porf_mem + entries_ptr + slot * 8)) = pack_bytestring((i32)porf_native_fetch_alloc_bytestring(__sb_peer.data(), __sb_peer.size()));\n" +
+  "    slot++;\n" +
+  "  }\n" +
+  "  *((i32*)(porf_mem + headers_ptr)) = slot;\n\n  return headers_ptr;";
+const HDR_APPEND_MARKER = "__sb_peer";
+
+const done = new Set<string>();
+
+/** Edits to Porffor's uWebSockets shim: `[marker, anchor, inject, what]`. */
+const UWS_EDITS = [
+  [BODY_MARKER, BODY_ANCHOR, BODY_INJECT, "request body limit"],
+  [STATUS_SIG_MARKER, STATUS_SIG_ANCHOR, STATUS_SIG_INJECT, "status-line return type (#156)"],
+  [STATUS_303_MARKER, STATUS_303_ANCHOR, STATUS_303_INJECT, "status-line 303 case (#156)"],
+  [STATUS_DEFAULT_MARKER, STATUS_DEFAULT_ANCHOR, STATUS_DEFAULT_INJECT, "status-line fallback (#156)"],
+  [HDR_SIG_MARKER, HDR_SIG_ANCHOR, HDR_SIG_INJECT, "collect_headers res arg (#163)"],
+  [HDR_CALL_MARKER, HDR_CALL_ANCHOR, HDR_CALL_INJECT, "collect_headers call site (#163)"],
+  [HDR_CAP_MARKER, HDR_CAP_ANCHOR, HDR_CAP_INJECT, "remote-addr header capacity (#163)"],
+  [HDR_SKIP_MARKER, HDR_SKIP_ANCHOR, HDR_SKIP_INJECT, "drop client-sent x-sb-remote-addr (#163)"],
+  [HDR_APPEND_MARKER, HDR_APPEND_ANCHOR, HDR_APPEND_INJECT, "append x-sb-remote-addr (#163)"],
+] as const;
+
+/** The uWebSockets shim source: body limit + the #156 status-line fix. Exported for tests. */
+export async function patchUwebsockets(root: string): Promise<void> {
+  const file = resolve(root, "compiler/uwebsockets.js");
+  let src = await readFile(file, "utf8");
+  let changed = false;
+  for (const [marker, anchor, inject, what] of UWS_EDITS) {
+    if (src.includes(marker)) continue;
+    if (!src.includes(anchor)) {
+      throw new Error(
+        `could not patch Porffor's ${what}: anchor not found in ${file}. ` +
+          "Porffor's uWebSockets shim changed — check patches/UPSTREAM.md.",
+      );
+    }
+    src = src.replace(anchor, inject);
+    changed = true;
+  }
+  if (changed) await writeFile(file, src);
+}
+
+async function patchCompilerArgs(root: string): Promise<void> {
+  const file = resolve(root, "compiler/index.js");
+  let src = await readFile(file, "utf8");
+  let changed = false;
+  for (const [marker, anchor, inject, what] of [
+    [LINK_MARKER, LINK_ANCHOR, LINK_INJECT, "extra link args"],
+    [CFLAGS_MARKER, CFLAGS_ANCHOR, CFLAGS_INJECT, "extra compiler flags"],
+  ] as const) {
+    if (src.includes(marker)) continue;
+    const at = src.indexOf(anchor);
+    if (at === -1) {
+      throw new Error(
+        `could not patch Porffor for ${what}: anchor not found in ${file}. ` +
+          "Porffor's native-fetch build changed — check patches/UPSTREAM.md.",
+      );
+    }
+    // After the anchor for cflags (the args follow it), before it for the link
+    // line (the object list ends with it).
+    src =
+      marker === CFLAGS_MARKER
+        ? src.slice(0, at + anchor.length) + inject + src.slice(at + anchor.length)
+        : src.slice(0, at) + inject + src.slice(at);
+    changed = true;
+  }
+  if (changed) await writeFile(file, src);
+}
+
+/** The native-fetch server source: $PORT support + the #165 console sink. Exported for tests. */
+export async function patchRenderJs(root: string): Promise<void> {
+  const file = resolve(root, "compiler/render.js");
+  let src = await readFile(file, "utf8");
+  let changed = false;
+  for (const [marker, anchor, inject, what] of RENDER_EDITS) {
+    if (src.includes(marker)) continue;
+    const at = src.indexOf(anchor);
+    if (at === -1) {
+      throw new Error(
+        `could not patch Porffor for ${what}: anchor not found in ${file}. ` +
+          "Porffor's native-fetch renderer changed — check patches/UPSTREAM.md.",
+      );
+    }
+    src = src.slice(0, at + anchor.length) + inject + src.slice(at + anchor.length);
+    changed = true;
+  }
+  if (changed) await writeFile(file, src);
+}
+
+/**
+ * Apply every patch to a Porffor checkout at `root` (the directory that holds
+ * `compiler/` and `runtime/`). Idempotent per process and per marker, so it is
+ * safe to call on every build. Callers pass an explicit root — `ensurePorffor`
+ * right after extraction, the compile path against its resolved checkout.
+ */
+export async function ensurePorfforPatched(root: string): Promise<void> {
+  if (done.has(root)) return;
+  await patchCompilerArgs(root);
+  await patchUwebsockets(root);
+  await patchRenderJs(root);
+  done.add(root);
+}

package/src/pin.ts

@@ -0,0 +1,22 @@
+/**
+ * The single pinned Porffor identity for the whole platform — the CLI and the
+ * monorepo both read it from here. The `alpha-*` git tags ship no package.json,
+ * so there is no npm dep to resolve; `ensurePorffor` fetches the commit tarball
+ * and verifies it against `PORFFOR_ARCHIVE_SHA256`.
+ *
+ * To move the pin: bump all four constants below (the sha is
+ * `shasum -a 256` of the archive at `PORFFOR_ARCHIVE_URL`), check whether the
+ * new `compiler/uwebsockets.js` changed `UWS_COMMIT` — if so re-vendor the
+ * uWebSockets archive in `sproutboat-cli/vendor/` — then run both repos'
+ * test + conformance suites. See sproutboat-cli/MIGRATION.md.
+ */
+export const PORFFOR_CHANNEL = "alpha-5";
+export const PORFFOR_COMMIT_FULL = "1f4ae4ae3e0a5f0a93b3bc084359e1a3a23391fd";
+export const PORFFOR_COMMIT = PORFFOR_COMMIT_FULL.slice(0, 7);
+export const PORFFOR_ARCHIVE_SHA256 = "a49a0e857574e93cb09c574dcf53b7cc049d3cb65c5b944b169755cad2a51d5d";
+export const PORFFOR_ARCHIVE_URL = `https://codeload.github.com/CanadaHonk/porffor/tar.gz/${PORFFOR_COMMIT_FULL}`;
+
+/** A compact identity string for a manifest / report (`alpha-5 (1f4ae4a)`). */
+export function porfforVersion(): string {
+  return process.env.PORFFOR_VERSION || `${PORFFOR_CHANNEL} (${PORFFOR_COMMIT})`;
+}