sproutboat 0.2.0 → 0.3.0

package/README.md

@@ -70,9 +70,16 @@ binding, with an Astro UI and a runnable end-to-end harness.
 ## Requirements
 
 - [Bun](https://bun.sh) 1.4+
-- `git` and `make` on `PATH` (first build only — compiles uWebSockets once)
-- No Docker. Builds cross-compile to a static `linux-x86_64` binary with Porffor
-  and Zig. Windows: build from WSL.
+
+`build` / `deploy` cross-compile the handler to a static `linux-x86_64` binary
+with Porffor and Zig (Zig is fetched automatically on first use). The package
+ships a prebuilt uWebSockets, so nothing else is compiled from source. No Docker,
+no root. On Windows, build from WSL.
+
+If that prebuilt is unusable (a `porffor` pin bump before the archive is
+refreshed), the first build falls back to compiling uWebSockets locally, which
+needs `git` and `make` on `PATH`. `SPROUTBOAT_UWS_TARBALL=<archive>` overrides
+the shipped one.
 
 ## Limits (v1)
 

package/SURFACE.md

@@ -3,7 +3,7 @@
 > Generated by `src/surface.test.ts` from `src/surface.ts` + the pinned
 > toolchain constants. Do not edit by hand — run `UPDATE_SURFACE=1 bun test`.
 
-**Package:** `sproutboat` 0.2.0 · runs on Bun (use `bunx`, not `npx`)
+**Package:** `sproutboat` 0.3.0 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 
@@ -30,7 +30,10 @@ usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | dep
 | `SPROUTBOAT_API_URL` | Control-plane URL. Overrides the saved active endpoint. |
 | `SPROUTBOAT_TOKEN` | API token. Overrides the saved credential for the endpoint. |
 | `SPROUTBOAT_ZIG` | Path to a Zig binary to use instead of downloading the pinned one. |
+| `SPROUTBOAT_UWS_TARBALL` | Path to a prebuilt uWebSockets (x86_64-linux-musl) tarball to seed the Porffor cache with, instead of downloading it (removes the first-build git + make need). |
 | `SPROUTBOAT_COMPILE_TIMEOUT_MS` | Porffor compile timeout in ms (default 600000). |
+| `SPROUTBOAT_VARS_JSON` | JSON object of baked `vars` (UPPER_SNAKE -> string), read by the wrapper when generating the worker module. |
+| `SPROUTBOAT_BINDINGS_JSON` | The artifact's bindings.json, read by the wrapper to emit the `__sbInstallBindings` line. |
 | `SPROUTBOAT_CONFIG_DIR` | Directory for credentials.json (default ~/.config/sproutboat). |
 | `XDG_CONFIG_HOME` | Base for the default credentials dir when SPROUTBOAT_CONFIG_DIR is unset. |
 | `PORFFOR_VERSION` | Override the Porffor identity string recorded in the manifest. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "license": "MIT",
   "type": "module",
@@ -22,9 +22,20 @@
   "bin": {
     "sproutboat": "src/main.ts"
   },
+  "exports": {
+    "./runtime/config": "./src/config.ts",
+    "./runtime/source": "./src/source.ts",
+    "./runtime/manifest": "./src/manifest.ts",
+    "./runtime/assets": "./src/assets.ts",
+    "./runtime/broker": "./src/broker.ts",
+    "./runtime/wrap": "./src/wrap.ts",
+    "./runtime/prelude": "./src/native-fetch-prelude.js",
+    "./package.json": "./package.json"
+  },
   "files": [
     "src",
     "!src/*.test.ts",
+    "vendor",
     "SURFACE.md"
   ],
   "engines": {

package/src/assets.ts

@@ -36,6 +36,30 @@ export function contentType(name: string): string {
   return (dot >= 0 ? TYPES.get(name.slice(dot + 1).toLowerCase()) : undefined) ?? "application/octet-stream";
 }
 
+/**
+ * Resolve a request path to a manifest key the way a static host does:
+ *   - an exact hit wins;
+ *   - a directory path (`/docs/`) tries `/docs/index.html`;
+ *   - an extensionless path (`/docs`) tries `/docs.html`, then `/docs/index.html`.
+ * Returns the matched key, or `null`. This only picks which file to serve — no
+ * canonical redirects, and the caller still owns not-found handling. Mirrors
+ * Cloudflare's `html_handling: "auto-trailing-slash"` minus the 3xx responses.
+ */
+export function resolveAssetKey(path: string, has: (key: string) => boolean): string | null {
+  if (!path.startsWith("/")) path = `/${path}`;
+  if (path.endsWith("/")) {
+    const index = `${path}index.html`;
+    return has(index) ? index : null;
+  }
+  if (has(path)) return path;
+  const base = path.slice(path.lastIndexOf("/") + 1);
+  if (!base.includes(".")) {
+    if (has(`${path}.html`)) return `${path}.html`;
+    if (has(`${path}/index.html`)) return `${path}/index.html`;
+  }
+  return null;
+}
+
 /** Walk `dir` recursively, returning `{ "/path": {hash,size,type} }`. */
 export function walkAssets(dir: string) {
   const out: AssetFiles = {};

package/src/broker.ts

@@ -22,7 +22,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join, normalize, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import type { AssetManifest } from "./assets";
+import { resolveAssetKey, type AssetManifest } from "./assets";
 
 export type Bindings = {
   kv: string[];
@@ -109,6 +109,11 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
 
   const db = new Database(dbPath);
   db.exec("PRAGMA journal_mode = WAL");
+  // WAL + NORMAL is the standard pairing: a write no longer fsyncs the WAL, so
+  // host power loss can drop the last few committed txns, but a process crash
+  // never can and the file never corrupts. Right trade for a single-VPS
+  // KV/queue/DO store; on real block storage this is ~10-100x on writes.
+  db.exec("PRAGMA synchronous = NORMAL");
   db.exec("CREATE TABLE IF NOT EXISTS kv (ns TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, PRIMARY KEY (ns, key))");
   db.exec(
     "CREATE TABLE IF NOT EXISTS r2 (bucket TEXT NOT NULL, key TEXT NOT NULL, body TEXT NOT NULL, size INTEGER NOT NULL, " +
@@ -158,6 +163,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       if (d1Dir) mkdirSync(d1Dir, { recursive: true });
       conn = new Database(d1Dir ? join(d1Dir, `${name}.sqlite`) : ":memory:", { create: true });
       conn.exec("PRAGMA journal_mode = WAL");
+      conn.exec("PRAGMA synchronous = NORMAL");
       d1Conns.set(name, conn);
     }
     return conn;
@@ -290,9 +296,9 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         const prefix = str(msg.prefix);
         const cursor = str(msg.cursor);
         const limit = Math.min(Math.max(Number(msg.limit) || 1000, 1), 1000);
-        const rows = db.query<R2Row, [string, string, string]>(
-          "SELECT * FROM r2 WHERE bucket = ? AND key LIKE ? || '%' AND key > ? ORDER BY key LIMIT " + (limit + 1),
-        ).all(bucket, prefix, cursor);
+        const rows = db.query<R2Row, [string, string, string, number]>(
+          "SELECT * FROM r2 WHERE bucket = ? AND key LIKE ? || '%' AND key > ? ORDER BY key LIMIT ?",
+        ).all(bucket, prefix, cursor, limit + 1);
         const truncated = rows.length > limit;
         const page = truncated ? rows.slice(0, limit) : rows;
         return {
@@ -335,9 +341,9 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         // query it via the SQL API). Exposed here so a dashboard can read back.
         const ds = requireAe(msg.dataset);
         const limit = Math.min(Math.max(Number(msg.limit) || 20, 1), 200);
-        const rows = db.query<{ ts: number; indexes_json: string; blobs_json: string; doubles_json: string }, [string]>(
-          "SELECT ts, indexes_json, blobs_json, doubles_json FROM ae WHERE dataset = ? ORDER BY ts DESC, rowid DESC LIMIT " + limit,
-        ).all(ds);
+        const rows = db.query<{ ts: number; indexes_json: string; blobs_json: string; doubles_json: string }, [string, number]>(
+          "SELECT ts, indexes_json, blobs_json, doubles_json FROM ae WHERE dataset = ? ORDER BY ts DESC, rowid DESC LIMIT ?",
+        ).all(ds, limit);
         const total = db.query<{ n: number }, [string]>("SELECT count(*) AS n FROM ae WHERE dataset = ?").get(ds);
         return {
           ok: true,
@@ -376,18 +382,17 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       case "do.storage.list": {
         const cls = requireDoClass(msg.cls);
         const limit = Math.min(Math.max(Number(msg.limit) || 1000, 1), 10000);
-        const rows = db.query<{ key: string; value: string }, [string, string, string]>(
-          "SELECT key, value FROM do_storage WHERE cls = ? AND id = ? AND key LIKE ? || '%' ORDER BY key LIMIT " + limit,
-        ).all(cls, str(msg.id), str(msg.prefix));
+        const rows = db.query<{ key: string; value: string }, [string, string, string, number]>(
+          "SELECT key, value FROM do_storage WHERE cls = ? AND id = ? AND key LIKE ? || '%' ORDER BY key LIMIT ?",
+        ).all(cls, str(msg.id), str(msg.prefix), limit);
         return { ok: true, entries: rows.map((r) => [r.key, r.value]) };
       }
 
       case "assets.get": {
         if (!bindings.assets) throw new Error("assets not bound");
-        let path = str(msg.path) || "/";
-        if (!path.startsWith("/")) path = `/${path}`;
-        if (path.endsWith("/")) path += "index.html";
-        const hit = readAsset(path);
+        const reqPath = str(msg.path) || "/";
+        const key = resolveAssetKey(reqPath, (k) => !!assetManifest?.files[k]);
+        const hit = key ? readAsset(key) : null;
         if (hit) return { ok: true, found: true, status: 200, type: hit.type, hash: hit.hash, body: hit.body };
         const nfh = assetManifest?.notFound ?? "none";
         if (nfh === "single-page-application") {

package/src/compile.ts

@@ -4,89 +4,20 @@
  * `zig cc -target x86_64-linux-musl` and statically links, so the same command
  * works from macOS, Linux, or WSL with no Docker.
  *
- * One-time per machine: Porffor git-clones uWebSockets and builds `uSockets.a`
- * into ~/.cache/porffor/deps/ (needs `git` and `make` on PATH). Later builds
- * reuse it and take a few seconds.
+ * One-time per machine: the uWebSockets tree Porffor links is unpacked into
+ * ~/.cache/porffor/deps/. `ensureUWebSockets()` extracts the prebuilt archive
+ * shipped in `vendor/` so this needs no `git` or `make`; if that archive is
+ * unusable it falls back to Porffor's own git + make path (needs both on PATH).
  */
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { ensurePorfforPatched } from "./patch-porffor";
-import { porfforRoot } from "./toolchain";
+import { ensureUWebSockets, porfforRoot, UwsUnavailableError } from "./toolchain";
+import { EMPTY_BINDINGS, preludePath, wrapNativeFetchHandler, type Bindings } from "./wrap";
 
-const preludePath = new URL("./native-fetch-prelude.js", import.meta.url);
-// The server honours $PORT at runtime (patches/porffor-render.patch); this baked
-// value is only a fallback for a directly-run binary.
-const DEFAULT_PORT = 8080;
-const COMPILE_TIMEOUT_MS = Number(process.env.SPROUTBOAT_COMPILE_TIMEOUT_MS || 600_000);
-
-/**
- * Binding names a project declares. `do` maps a binding name to a Durable Object
- * class name; `crons` are schedule expressions with no name.
- */
-export type Bindings = {
-  kv: string[];
-  secrets: string[];
-  outbound: string[];
-  d1: string[];
-  r2: string[];
-  queues: string[];
-  analytics: string[];
-  do: Array<{ binding: string; className: string }>;
-  crons: string[];
-  /** Static-asset binding name for `env.<NAME>.fetch(request)`; `""` when assets are edge-only. */
-  assets: string;
-};
-
-const EMPTY_BINDINGS: Bindings = { kv: [], secrets: [], outbound: [], d1: [], r2: [], queues: [], analytics: [], do: [], crons: [], assets: "" };
+export { EMPTY_BINDINGS, preludePath, wrapNativeFetchHandler, type Bindings } from "./wrap";
 
-function hasBindings(b: Bindings): boolean {
-  return (
-    b.kv.length > 0 || b.secrets.length > 0 || b.outbound.length > 0 || b.d1.length > 0 || b.r2.length > 0 ||
-    b.queues.length > 0 || b.analytics.length > 0 || b.do.length > 0 || b.assets !== ""
-  );
-}
-
-/**
- * Build the final native-fetch module: the prelude (Web API shims + the broker
- * binding shim + the trigger dispatcher), then `const env = {…}` with the baked
- * `vars`, then — if any binding is declared — one `__sbInstallBindings(env, …)`
- * line, then the user's source with its `export` keywords neutralised (so its
- * `export default {…}` becomes a plain object we can hand to the dispatcher),
- * then our single `export default { fetch }` that routes every request through
- * `__sbEntry` (HTTP → `handlers.fetch`; `x-sb-trigger` → scheduled / queue / DO).
- *
- * With no bindings and no `scheduled`/`queue`/DO the output behaves exactly like
- * a plain `export default { fetch }` worker.
- */
-export function wrapNativeFetchHandler(
-  source: string,
-  prelude: string,
-  vars: Record<string, string> = {},
-  bindings: Bindings = EMPTY_BINDINGS,
-): string {
-  if (!/\bexport\s+default\s*\{/.test(source) || !/\bfetch\s*\(/.test(source)) {
-    throw new Error("handler must default-export an object with a fetch(request) method");
-  }
-  // Neutralise the module's exports: its default object becomes `__sbHandlers`,
-  // and any `export class`/`function`/`const` (Durable Object classes, helpers)
-  // becomes a plain top-level declaration. Imports are already rejected upstream.
-  const neutralised = source
-    .replace(/^(\s*)export\s+default\s*/m, "$1const __sbHandlers = ")
-    .replace(/^export\s+(async\s+function|function|class|const|let|var)\b/gm, "$1");
-
-  const env = `const env = ${JSON.stringify(vars)};\nglobalThis.env = env;\n`;
-  const wire = hasBindings(bindings) ? `__sbInstallBindings(env, ${JSON.stringify(bindings)});\n` : "";
-  const registerDO = bindings.do.length
-    ? `__sbRegisterDO({ ${bindings.do.map((d) => `${d.className}: ${d.className}`).join(", ")} });\n`
-    : "";
-
-  return (
-    `${prelude}\n${env}${wire}` +
-    `${neutralised}\n` +
-    `${registerDO}` +
-    `export default {\n  port: ${DEFAULT_PORT},\n  fetch(request) { return __sbEntry(__sbHandlers, request); }\n};\n`
-  );
-}
+const COMPILE_TIMEOUT_MS = Number(process.env.SPROUTBOAT_COMPILE_TIMEOUT_MS || 600_000);
 
 export type CompileInput = {
   sourcePath: string;
@@ -99,6 +30,28 @@ export type CompileInput = {
 /** Compile `sourcePath` to a native binary at `outPath` (mode 0555). */
 export async function compileWorker(input: CompileInput): Promise<void> {
   await ensurePorfforPatched();
+
+  // Seed the Porffor uWebSockets cache from the prebuilt archive in `vendor/` so
+  // the first build needs no `git` / `make`. Fall back to Porffor's own git+make
+  // path if the archive is missing or fails its checksum.
+  try {
+    await ensureUWebSockets();
+  } catch (error) {
+    if (!(error instanceof UwsUnavailableError)) throw error;
+    const haveGit = Bun.which("git");
+    const haveMake = Bun.which("make");
+    if (haveGit && haveMake) {
+      console.warn(`prebuilt uWebSockets unusable (${error.message.split("\n")[0]}); falling back to git + make (slower, one-time)`);
+    } else {
+      const missing = [!haveGit && "git", !haveMake && "make"].filter(Boolean).join(" and ");
+      throw new Error(
+        `${error.message}\n\nThe prebuilt uWebSockets is unusable, and ${missing} ` +
+        `${missing.includes("and") ? "are" : "is"} not on PATH for the fallback build. ` +
+        `Install ${missing}, or set SPROUTBOAT_UWS_TARBALL to a valid archive.`,
+      );
+    }
+  }
+
   const outDir = dirname(input.outPath);
   await mkdir(outDir, { recursive: true });
   const generatedPath = resolve(outDir, "worker.generated.js");
@@ -111,8 +64,11 @@ export async function compileWorker(input: CompileInput): Promise<void> {
   const binDir = resolve(porffor, "../.bin");
   const path = `${dirname(input.zigBin)}:${binDir}:${process.env.PATH ?? ""}`;
 
+  // `-s`: strip at link. The unstripped static-musl binary is ~90% DWARF that
+  // nothing needs at runtime (12 MB -> ~1.3 MB for the kitchen-sink). Porffor
+  // forwards `-s` straight to the `zig cc` link step.
   const child = Bun.spawn(
-    [process.execPath, launcher, "native", generatedPath, "-o", input.outPath, "--musl"],
+    [process.execPath, launcher, "native", generatedPath, "-o", input.outPath, "--musl", "-s"],
     { cwd: outDir, stdout: "pipe", stderr: "pipe", env: { ...process.env, PATH: path } },
   );
   let timedOut = false;

package/src/native-fetch-prelude.js

@@ -11,6 +11,26 @@
 // Declared before it is referenced: a getter body that names a later top-level
 // class throws ReferenceError in Porffor (see patches/UPSTREAM.md draft B).
 
+// #41 — cold-start phase marker. Runs as the first thing in the bundle: writes
+// the current wall-clock ms to $SB_STARTUP_FILE so the supervisor can split
+// cold-start into "spawn -> JS starts" (process + runtime bootstrap) and
+// "JS starts -> listening" (module eval + server bind). No-op when unset.
+function __sbStartupMark() {
+  Porffor.c`
+    const char* __f = getenv("SB_STARTUP_FILE");
+    if (__f) {
+      struct timespec __ts;
+      clock_gettime(CLOCK_REALTIME, &__ts);
+      double __ms = (double)__ts.tv_sec * 1000.0 + (double)__ts.tv_nsec / 1000000.0;
+      char __buf[32];
+      int __n = snprintf(__buf, sizeof(__buf), "%.0f", __ms);
+      int __fd = open(__f, O_WRONLY | O_CREAT | O_TRUNC, 0600);
+      if (__fd >= 0) { write(__fd, __buf, (size_t)__n); close(__fd); }
+    }
+  `;
+}
+__sbStartupMark();
+
 class __SproutboatURLSearchParams {
   constructor(init) {
     this._keys = [];
@@ -118,13 +138,21 @@ __sbDefineURLAccessor('username', function () { return ''; });
 __sbDefineURLAccessor('password', function () { return ''; });
 
 // crypto.randomUUID / getRandomValues are absent in native-fetch. Provide them
-// so Worker code (request ids, cache keys, idempotency keys) runs.
-// ponytail: Math.random() is NOT cryptographically strong. Swap for a real
-// CSPRNG the moment Porffor exposes one — do not use these for tokens/secrets.
+// backed by the OS CSPRNG (`__sbRandomBytes` -> inline C -> /dev/urandom), so
+// tokens, idempotency keys and UUIDs are unpredictable. Deliberately no insecure
+// fallback — a silent downgrade to a weak source is worse than throwing.
 if (globalThis.crypto == null) globalThis.crypto = {};
 if (globalThis.crypto.getRandomValues == null) {
   globalThis.crypto.getRandomValues = function (view) {
-    for (let i = 0; i < view.length; i++) view[i] = Math.floor(Math.random() * 256);
+    const n = view.length >>> 0;
+    // WebCrypto caps a single call at 65536 bytes.
+    if (n > 65536) throw new RangeError("crypto.getRandomValues: byte length exceeds 65536");
+    if (n === 0) return view;
+    // One CSPRNG byte per element. Correct for Uint8Array (and randomUUID); a
+    // wider view gets its low byte filled, matching the previous polyfill's shape.
+    const bytes = __sbRandomBytes(String(n));
+    if (bytes.length !== n) throw new Error("crypto.getRandomValues: OS entropy source unavailable");
+    for (let i = 0; i < n; i++) view[i] = bytes.charCodeAt(i) & 0xff;
     return view;
   };
 }
@@ -151,62 +179,103 @@ if (globalThis.crypto.randomUUID == null) {
 
 // ---------------------------------------------------------------------------
 // Bindings: env.<KV>, env.<SECRET>, env.<D1>, env.<R2>, and globalThis.fetch,
-// backed by a Bun broker on a loopback TCP port. The transport is inline C — blocking
-// socket/connect/write/read per call (http-sync-v0: one worker event-loop turn
-// per request, so a blocking roundtrip is acceptable). Wire frame:
+// backed by a Bun broker on a loopback TCP port. The transport is inline C —
+// blocking write/read per call over ONE long-lived connection (http-sync-v0: one
+// worker event-loop turn per request, so a blocking roundtrip is acceptable).
+// Wire frame:
 //   [u32 LE len][ <token> "\n" <json> ]   reply: [u32 LE len][ <json> ]
 // SB_BROKER_PORT / SB_BROKER_TOKEN are set by the supervisor next to $PORT.
 // If SB_BROKER_PORT is unset the shims below are never installed (compile.ts
 // only emits the __sbInstallBindings call when the project declares bindings),
 // so a plain worker is byte-for-byte unchanged.
-// ponytail: blocking IO, fresh connection per call, text values only. Connection
-// pooling + binary values + non-blocking = v2.
+// ponytail: text values only; still AF_INET loopback, not AF_UNIX. A failed
+// exchange reconnects and resends once — a broker crash between "request applied"
+// and "reply read" can double-apply a non-idempotent op (queue.send, INSERT);
+// the old fresh-connection-per-call path just failed the call there instead.
+// Binary values + AF_UNIX = v2.
 
 Porffor.c`
 #include <sys/socket.h>
 #include <netinet/in.h>
+#include <netinet/tcp.h>
+#include <signal.h>
 #include <unistd.h>
 #include <string.h>
 #include <stdlib.h>
 #include <stdio.h>
+#include <fcntl.h>
+#include <errno.h>
+#include <time.h>
 
 u32 porf_native_fetch_alloc_bytestring(const char* input, size_t len);
 int porf_native_fetch_read_value(jsval value, const char** out_buf, size_t* out_len, char** out_owned);
 
+// Fill buf with n bytes from the OS CSPRNG. /dev/urandom is present on Linux and
+// macOS and inside the bubblewrap sandbox; blocking is not a concern after the
+// pool is seeded. Returns 0, or -1 if the source could not be read in full.
+static int sb_os_random(unsigned char* buf, size_t n) {
+  int fd = open("/dev/urandom", O_RDONLY | O_CLOEXEC);
+  if (fd < 0) return -1;
+  size_t off = 0;
+  while (off < n) {
+    long r = read(fd, buf + off, n - off);
+    if (r <= 0) {
+      if (r < 0 && errno == EINTR) continue;
+      close(fd);
+      return -1;
+    }
+    off += (size_t)r;
+  }
+  close(fd);
+  return 0;
+}
+
 static int sb_io_all(int fd, unsigned char* buf, size_t len, int writing) {
   size_t done = 0;
   while (done < len) {
     long n = writing ? write(fd, buf + done, len - done) : read(fd, buf + done, len - done);
-    if (n <= 0) return -1;
+    if (n <= 0) {
+      if (n < 0 && errno == EINTR) continue;
+      return -1;
+    }
     done += (size_t)n;
   }
   return 0;
 }
 
-static int sb_broker_roundtrip(const char* req, size_t req_len, char** resp_out, size_t* resp_len_out) {
-  *resp_out = NULL;
-  *resp_len_out = 0;
+// One long-lived loopback connection to the broker, reused across every binding
+// call. The broker frames each request/reply independently and keeps the socket
+// open, so the steady-state per-call cost is just write + read — no socket(),
+// connect() handshake or close() each time. -1 = not connected.
+static int sb_broker_fd = -1;
 
+static int sb_broker_connect(void) {
   const char* port_s = getenv("SB_BROKER_PORT");
   if (!port_s) return -10;
-  int port = atoi(port_s);
-  const char* tok = getenv("SB_BROKER_TOKEN");
-  size_t tok_len = tok ? strlen(tok) : 0;
-
+  signal(SIGPIPE, SIG_IGN); // a dead broker must yield EPIPE, not kill the worker
   int fd = socket(AF_INET, SOCK_STREAM, 0);
   if (fd < 0) return -1;
-
+  int one = 1;
+  setsockopt(fd, IPPROTO_TCP, TCP_NODELAY, &one, sizeof(one));
   struct sockaddr_in addr;
   memset(&addr, 0, sizeof(addr));
   addr.sin_family = AF_INET;
-  addr.sin_port = htons((unsigned short)port);
+  addr.sin_port = htons((unsigned short)atoi(port_s));
   addr.sin_addr.s_addr = htonl(0x7f000001u); // 127.0.0.1
   if (connect(fd, (struct sockaddr*)&addr, sizeof(addr)) != 0) { close(fd); return -2; }
+  sb_broker_fd = fd;
+  return 0;
+}
+
+// Send one framed request, read one framed reply, on the persistent fd.
+static int sb_broker_exchange(const char* req, size_t req_len, char** resp_out, size_t* resp_len_out) {
+  const char* tok = getenv("SB_BROKER_TOKEN");
+  size_t tok_len = tok ? strlen(tok) : 0;
 
   // frame body: token "\n" json
   size_t body_len = tok_len + 1 + req_len;
   unsigned char* frame = (unsigned char*)malloc(4 + body_len);
-  if (!frame) { close(fd); return -5; }
+  if (!frame) return -5;
   frame[0] = (unsigned char)(body_len & 0xff);
   frame[1] = (unsigned char)((body_len >> 8) & 0xff);
   frame[2] = (unsigned char)((body_len >> 16) & 0xff);
@@ -214,23 +283,40 @@ static int sb_broker_roundtrip(const char* req, size_t req_len, char** resp_out,
   if (tok_len) memcpy(frame + 4, tok, tok_len);
   frame[4 + tok_len] = '\n';
   if (req_len) memcpy(frame + 4 + tok_len + 1, req, req_len);
-  int wr = sb_io_all(fd, frame, 4 + body_len, 1);
+  int wr = sb_io_all(sb_broker_fd, frame, 4 + body_len, 1);
   free(frame);
-  if (wr != 0) { close(fd); return -3; }
+  if (wr != 0) return -3;
 
   unsigned char rhdr[4];
-  if (sb_io_all(fd, rhdr, 4, 0) != 0) { close(fd); return -4; }
+  if (sb_io_all(sb_broker_fd, rhdr, 4, 0) != 0) return -4;
   size_t rlen = (size_t)rhdr[0] | ((size_t)rhdr[1] << 8) | ((size_t)rhdr[2] << 16) | ((size_t)rhdr[3] << 24);
 
   char* buf = (char*)malloc(rlen ? rlen : 1);
-  if (!buf) { close(fd); return -5; }
-  if (rlen && sb_io_all(fd, (unsigned char*)buf, rlen, 0) != 0) { free(buf); close(fd); return -6; }
-  close(fd);
+  if (!buf) return -5;
+  if (rlen && sb_io_all(sb_broker_fd, (unsigned char*)buf, rlen, 0) != 0) { free(buf); return -6; }
 
   *resp_out = buf;
   *resp_len_out = rlen;
   return 0;
 }
+
+static int sb_broker_roundtrip(const char* req, size_t req_len, char** resp_out, size_t* resp_len_out) {
+  *resp_out = NULL;
+  *resp_len_out = 0;
+  // Two tries: a broker restart (or an idle-closed socket) invalidates the fd,
+  // so a failed exchange drops the connection and reconnects once before failing.
+  for (int attempt = 0; attempt < 2; attempt++) {
+    if (sb_broker_fd < 0) {
+      int rc = sb_broker_connect();
+      if (rc != 0) return rc;
+    }
+    int rc = sb_broker_exchange(req, req_len, resp_out, resp_len_out);
+    if (rc == 0) return 0;
+    close(sb_broker_fd);
+    sb_broker_fd = -1;
+  }
+  return -3;
+}
 `;
 
 // One request string in, one reply string out. `reqJson` is a parameter, so the
@@ -255,6 +341,30 @@ function __sbCall(reqJson) {
   return res;
 }
 
+// `nStr` is the decimal byte count as a string (same string-param pattern as
+// __sbEnv). Returns a bytestring of that many CSPRNG bytes, or '' on failure.
+function __sbRandomBytes(nStr) {
+  let out = '';
+  Porffor.c`
+    const char* __ns; size_t __nsl; char* __nso = 0;
+    porf_native_fetch_read_value(nStr, &__ns, &__nsl, &__nso);
+    char __nb[16];
+    size_t __k = __nsl < 15 ? __nsl : 15;
+    memcpy(__nb, __ns, __k); __nb[__k] = 0;
+    if (__nso) free(__nso);
+    long __n = atol(__nb);
+    if (__n > 0 && __n <= 65536) {
+      unsigned char* __b = (unsigned char*)malloc((size_t)__n);
+      if (__b) {
+        if (sb_os_random(__b, (size_t)__n) == 0)
+          out = porf_box((f64)porf_native_fetch_alloc_bytestring((const char*)__b, (size_t)__n), 195);
+        free(__b);
+      }
+    }
+  `;
+  return out;
+}
+
 function __sbRpc(op, extra) {
   const req = { op };
   if (extra) for (const k in extra) req[k] = extra[k];
@@ -359,9 +469,17 @@ globalThis.__sbInstallBindings = function (target, bindings) {
 
   for (let i = 0; i < (bindings.secrets || []).length; i++) {
     const name = bindings.secrets[i];
+    // Fetch lazily, then freeze as a data property: a secret is process-lifetime
+    // immutable (a new value means a redeploy = a new process), so one broker
+    // round-trip on first read, zero after. A getter that RPCs on every access
+    // turns `'Bearer ' + env.KEY` in a loop into a syscall storm.
     Object.defineProperty(target, name, {
       configurable: true,
-      get() { return __sbRpc('secret.get', { name }).value; },
+      get() {
+        const value = __sbRpc('secret.get', { name }).value;
+        Object.defineProperty(target, name, { value, configurable: true, enumerable: true });
+        return value;
+      },
     });
   }
 
@@ -509,8 +627,7 @@ function __sbMakeDONamespace(binding, className) {
     idFromName(name) { return { toString() { return 'name:' + String(name); }, name: String(name) }; },
     idFromString(hex) { return { toString() { return String(hex); } }; },
     newUniqueId() {
-      const id = (globalThis.crypto && crypto.randomUUID ? crypto.randomUUID() : String(Math.random()).slice(2));
-      return { toString() { return 'uid:' + id; } };
+      return { toString() { return 'uid:' + crypto.randomUUID(); } };
     },
     get(id) {
       const idStr = typeof id === 'string' ? id : id.toString();

package/src/surface.ts

@@ -25,7 +25,10 @@ export const ENV_VARS: readonly EnvVar[] = [
   { name: "SPROUTBOAT_API_URL", purpose: "Control-plane URL. Overrides the saved active endpoint." },
   { name: "SPROUTBOAT_TOKEN", purpose: "API token. Overrides the saved credential for the endpoint." },
   { name: "SPROUTBOAT_ZIG", purpose: "Path to a Zig binary to use instead of downloading the pinned one." },
+  { name: "SPROUTBOAT_UWS_TARBALL", purpose: "Path to a prebuilt uWebSockets (x86_64-linux-musl) tarball to seed the Porffor cache with, instead of downloading it (removes the first-build git + make need)." },
   { name: "SPROUTBOAT_COMPILE_TIMEOUT_MS", purpose: "Porffor compile timeout in ms (default 600000)." },
+  { name: "SPROUTBOAT_VARS_JSON", purpose: "JSON object of baked `vars` (UPPER_SNAKE -> string), read by the wrapper when generating the worker module." },
+  { name: "SPROUTBOAT_BINDINGS_JSON", purpose: "The artifact's bindings.json, read by the wrapper to emit the `__sbInstallBindings` line." },
   { name: "SPROUTBOAT_CONFIG_DIR", purpose: "Directory for credentials.json (default ~/.config/sproutboat)." },
   { name: "XDG_CONFIG_HOME", purpose: "Base for the default credentials dir when SPROUTBOAT_CONFIG_DIR is unset." },
   { name: "PORFFOR_VERSION", purpose: "Override the Porffor identity string recorded in the manifest." },

package/src/toolchain.ts

@@ -30,6 +30,14 @@ const PORFFOR_COMMIT = "a415d19";
 // uWebSockets commit Porffor alpha-4 fetches for the native-fetch server. Read
 // from node_modules/porffor at build time; this is the fallback for the stamp.
 const UWS_COMMIT = "360c276d";
+const UWS_COMMIT_FULL = "360c276d609d59af56ae6932adb95154ace9f15f";
+
+// `vendor/uwebsockets-<UWS_COMMIT>-musl.tar.xz` ships in the package: the
+// checked-out, patched, `zig cc -target x86_64-linux-musl`-built uWebSockets
+// tree (headers + `uSockets/uSockets.a`). Regenerate + re-pin the sha whenever
+// the `porffor` pin (and thus UWS_COMMIT_FULL) changes — `bun tools/prebuild-uws.ts`
+// or the `uws-prebuild` workflow.
+const UWS_TARBALL_SHA256 = "e83736f3f8cf9d56a1ebe6ea61625a7af12386763374d47c14cff472ada7484a";
 
 function platformKey(): string {
   const arch = process.arch === "arm64" ? "aarch64" : process.arch === "x64" ? "x86_64" : null;
@@ -82,6 +90,66 @@ export async function ensureZig(): Promise<string> {
   return bin;
 }
 
+function uwsCommitFull(): string {
+  try {
+    const src = readFileSync(resolve(porfforRoot(), "compiler/uwebsockets.js"), "utf8");
+    return /UWS_COMMIT\s*=\s*['"]([0-9a-f]{40})/.exec(src)?.[1] ?? UWS_COMMIT_FULL;
+  } catch {
+    return UWS_COMMIT_FULL;
+  }
+}
+
+/** Thrown when the prebuilt uWebSockets archive is missing or fails its checksum. */
+export class UwsUnavailableError extends Error {}
+
+/** Path to the vendored prebuilt archive for the given short commit. */
+export function uwsVendorArchive(short: string): string {
+  return resolve(import.meta.dir, "..", "vendor", `uwebsockets-${short}-musl.tar.xz`);
+}
+
+/**
+ * Seed `~/.cache/porffor/deps/uWebSockets-<commit>-musl/` with the checked-out,
+ * patched, `x86_64-linux-musl`-built uWebSockets tree so Porffor's own
+ * `ensureUWebSockets` / `ensureUSocketsBuilt` short-circuit — the first build
+ * then needs no `git` and no `make`, only Zig.
+ *
+ * The archive ships in the package (`vendor/`). No-ops if the cache is already
+ * populated. Throws `UwsUnavailableError` if the archive is missing or fails its
+ * checksum; the caller decides whether to fall back to Porffor's git + make path.
+ *
+ * `SPROUTBOAT_UWS_TARBALL=/path/to/archive.tar.xz` overrides the vendored one.
+ */
+export async function ensureUWebSockets(): Promise<void> {
+  const commit = uwsCommitFull();
+  const short = commit.slice(0, 8);
+  const depsRoot = resolve(homedir(), ".cache/porffor/deps");
+  const dir = resolve(depsRoot, `uWebSockets-${commit}-musl`);
+  if (existsSync(resolve(dir, "src/App.h")) && existsSync(resolve(dir, "uSockets/uSockets.a"))) return;
+
+  const archive = process.env.SPROUTBOAT_UWS_TARBALL || uwsVendorArchive(short);
+  if (!existsSync(archive)) {
+    throw new UwsUnavailableError(
+      process.env.SPROUTBOAT_UWS_TARBALL
+        ? `SPROUTBOAT_UWS_TARBALL=${archive} does not exist`
+        : `no vendored uWebSockets archive at ${archive} (porffor pin moved? run \`bun tools/prebuild-uws.ts\`)`,
+    );
+  }
+  if (!process.env.SPROUTBOAT_UWS_TARBALL) {
+    const actual = await sha256File(archive);
+    if (actual !== UWS_TARBALL_SHA256) {
+      throw new UwsUnavailableError(`vendored uWebSockets sha256 mismatch\n  expected ${UWS_TARBALL_SHA256}\n  got      ${actual}`);
+    }
+  }
+
+  await mkdir(dir, { recursive: true });
+  const untar = Bun.spawn(["tar", "-xJf", archive, "-C", dir, "--strip-components=1"], { stdout: "pipe", stderr: "pipe" });
+  const [code, err] = await Promise.all([untar.exited, new Response(untar.stderr).text()]);
+  if (code !== 0) {
+    await rm(dir, { recursive: true, force: true });
+    throw new UwsUnavailableError(`could not extract vendored uWebSockets: ${err.trim()}`);
+  }
+}
+
 /** Directory holding node_modules/porffor (walks up from this file). */
 export function porfforRoot(start = import.meta.dir): string {
   let dir = start;

package/src/wrap.ts

@@ -0,0 +1,151 @@
+/**
+ * The build-independent half of worker compilation: the binding/trigger wrapper
+ * that turns a user's `export default { fetch }` into a native-fetch module, plus
+ * the `Bindings` shape and the `SPROUTBOAT_*_JSON` env readers.
+ *
+ * This module has no imports on purpose — the monorepo consumes it via the
+ * `sproutboat/runtime/wrap` export to drive its own (host-native, non-musl)
+ * compile path without pulling in `toolchain.ts` / `patch-porffor.ts`.
+ */
+
+/** The prelude file (Web API shims + broker binding shim + trigger dispatcher).
+ *  It is read as text and string-prepended before Porffor sees it, never
+ *  imported — callers do `readFile(preludePath, "utf8")`. */
+export const preludePath = new URL("./native-fetch-prelude.js", import.meta.url);
+
+// The server honours $PORT at runtime (patches/porffor-render.patch); this baked
+// value is only a fallback for a directly-run binary.
+const DEFAULT_PORT = 8080;
+
+/**
+ * Binding names a project declares. `do` maps a binding name to a Durable Object
+ * class name; `crons` are schedule expressions with no name.
+ */
+export type Bindings = {
+  kv: string[];
+  secrets: string[];
+  outbound: string[];
+  d1: string[];
+  r2: string[];
+  queues: string[];
+  analytics: string[];
+  do: Array<{ binding: string; className: string }>;
+  crons: string[];
+  /** Static-asset binding name for `env.<NAME>.fetch(request)`; `""` when assets are edge-only. */
+  assets: string;
+};
+
+export const EMPTY_BINDINGS: Bindings = { kv: [], secrets: [], outbound: [], d1: [], r2: [], queues: [], analytics: [], do: [], crons: [], assets: "" };
+
+function hasBindings(b: Bindings): boolean {
+  return (
+    b.kv.length > 0 || b.secrets.length > 0 || b.outbound.length > 0 || b.d1.length > 0 || b.r2.length > 0 ||
+    b.queues.length > 0 || b.analytics.length > 0 || b.do.length > 0 || b.assets !== ""
+  );
+}
+
+/**
+ * Build the final native-fetch module: the prelude (Web API shims + the broker
+ * binding shim + the trigger dispatcher), then `const env = {…}` with the baked
+ * `vars`, then — if any binding is declared — one `__sbInstallBindings(env, …)`
+ * line, then the user's source with its `export` keywords neutralised (so its
+ * `export default {…}` becomes a plain object we can hand to the dispatcher),
+ * then our single `export default { fetch }` that routes every request through
+ * `__sbEntry` (HTTP → `handlers.fetch`; `x-sb-trigger` → scheduled / queue / DO).
+ *
+ * With no bindings and no `scheduled`/`queue`/DO the output behaves exactly like
+ * a plain `export default { fetch }` worker.
+ *
+ * `port` is only the baked fallback in `export default { port }`; the runtime
+ * reads `$PORT` first. The monorepo's bench path overrides it.
+ *
+ * ponytail: the worker process is long-lived, so a handler that mutates `env`
+ * leaks that change to later requests. Freeze upstream once Porffor supports
+ * Object.freeze in native mode.
+ */
+export function wrapNativeFetchHandler(
+  source: string,
+  prelude: string,
+  vars: Record<string, string> = {},
+  bindings: Bindings = EMPTY_BINDINGS,
+  port: number = DEFAULT_PORT,
+): string {
+  if (!/\bexport\s+default\s*\{/.test(source) || !/\bfetch\s*\(/.test(source)) {
+    throw new Error("handler must default-export an object with a fetch(request) method");
+  }
+  // Neutralise the module's exports: its default object becomes `__sbHandlers`,
+  // and any `export class`/`function`/`const` (Durable Object classes, helpers)
+  // becomes a plain top-level declaration. Imports are already rejected upstream.
+  const neutralised = source
+    .replace(/^(\s*)export\s+default\s*/m, "$1const __sbHandlers = ")
+    .replace(/^export\s+(async\s+function|function|class|const|let|var)\b/gm, "$1");
+
+  const env = `const env = ${JSON.stringify(vars)};\nglobalThis.env = env;\n`;
+  const wire = hasBindings(bindings) ? `__sbInstallBindings(env, ${JSON.stringify(bindings)});\n` : "";
+  const registerDO = bindings.do.length
+    ? `__sbRegisterDO({ ${bindings.do.map((d) => `${d.className}: ${d.className}`).join(", ")} });\n`
+    : "";
+
+  return (
+    `${prelude}\n${env}${wire}` +
+    `${neutralised}\n` +
+    `${registerDO}` +
+    `export default {\n  port: ${port},\n  fetch(request) { return __sbEntry(__sbHandlers, request); }\n};\n`
+  );
+}
+
+type VarsJson = string | number | boolean | null | { readonly [key: string]: VarsJson } | VarsJson[];
+function isVarsObject(value: VarsJson): value is { readonly [key: string]: VarsJson } {
+  return value !== null && Object(value) === value && !Array.isArray(value);
+}
+function isVarsString(value: VarsJson): value is string {
+  return Object(value) !== value && value === String(value);
+}
+
+/** `SPROUTBOAT_VARS_JSON` (set by the build) → a validated flat string map. */
+export function readVarsFromEnv(): Record<string, string> {
+  const raw = process.env.SPROUTBOAT_VARS_JSON;
+  const vars: Record<string, string> = {};
+  if (!raw) return vars;
+  const parsed: VarsJson = JSON.parse(raw);
+  if (!isVarsObject(parsed)) throw new Error("SPROUTBOAT_VARS_JSON must be a JSON object");
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!/^[A-Z][A-Z0-9_]*$/.test(key) || !isVarsString(value)) throw new Error(`SPROUTBOAT_VARS_JSON.${key} must map an UPPER_SNAKE name to a string`);
+    vars[key] = value;
+  }
+  return vars;
+}
+
+/**
+ * `SPROUTBOAT_BINDINGS_JSON` (the artifact's `bindings.json`, passed by the
+ * build) → a `Bindings` shape. Every field is re-validated here; unknown keys
+ * are dropped and a missing / empty payload is `EMPTY_BINDINGS`, so an old build
+ * with no bindings still compiles.
+ */
+export function readBindingsFromEnv(): Bindings {
+  const raw = process.env.SPROUTBOAT_BINDINGS_JSON;
+  if (!raw) return EMPTY_BINDINGS;
+  const parsed: VarsJson = JSON.parse(raw);
+  if (!isVarsObject(parsed)) throw new Error("SPROUTBOAT_BINDINGS_JSON must be a JSON object");
+  const strings = (v: VarsJson): string[] => (Array.isArray(v) ? v.filter(isVarsString) : []);
+  const dos: Array<{ binding: string; className: string }> = [];
+  if (Array.isArray(parsed.do)) {
+    for (const entry of parsed.do) {
+      if (isVarsObject(entry) && isVarsString(entry.binding) && isVarsString(entry.className)) {
+        dos.push({ binding: entry.binding, className: entry.className });
+      }
+    }
+  }
+  return {
+    kv: strings(parsed.kv),
+    secrets: strings(parsed.secrets),
+    outbound: strings(parsed.outbound),
+    d1: strings(parsed.d1),
+    r2: strings(parsed.r2),
+    queues: strings(parsed.queues),
+    analytics: strings(parsed.analytics),
+    do: dos,
+    crons: strings(parsed.crons),
+    assets: isVarsString(parsed.assets) ? parsed.assets : "",
+  };
+}