sproutboat 0.2.0 → 0.2.1

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.2.1 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 
@@ -30,6 +30,7 @@ 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_CONFIG_DIR` | Directory for credentials.json (default ~/.config/sproutboat). |
 | `XDG_CONFIG_HOME` | Base for the default credentials dir when SPROUTBOAT_CONFIG_DIR is unset. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "license": "MIT",
   "type": "module",
@@ -25,6 +25,7 @@
   "files": [
     "src",
     "!src/*.test.ts",
+    "vendor",
     "SURFACE.md"
   ],
   "engines": {

package/src/compile.ts

@@ -4,14 +4,15 @@
  * `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";
 
 const preludePath = new URL("./native-fetch-prelude.js", import.meta.url);
 // The server honours $PORT at runtime (patches/porffor-render.patch); this baked
@@ -99,6 +100,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");

package/src/surface.ts

@@ -25,6 +25,7 @@ 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_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." },

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;