sproutboat 0.7.0 → 0.8.0

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.7.0 · runs on Bun (use `bunx`, not `npx`)
+**Package:** `sproutboat` 0.8.0 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 
@@ -12,7 +12,7 @@
 | `init` | `[name]` | Scaffold sproutboat.jsonc + src/index.js in ./<name>. |
 | `check` | `[project-dir]` | Validate the config and entry point without building. |
 | `dev` | `[project-dir] [--port <n>] [--no-watch]` | Run the project on this machine against a real broker, rebuilding on save. |
-| `build` | `[project-dir] [--target host]` | Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally — not deployable. |
+| `build` | `[project-dir] [--target host] [--standalone]` | Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally — not deployable. `--standalone` emits one executable carrying its own bindings, with SQLite compiled in (~2 MB) and no broker process. |
 | `deploy` | `[project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision]` | Build (unless --artifact), auto-provision id-less storage bindings and pin their ids into sproutboat.jsonc, print the report, upload, wait until the URL serves. The control plane skips an upload that matches the live artifact byte-for-byte. --dry-run stops before upload; --no-wait skips the health check; --no-provision leaves id-less bindings as ephemeral deploy-scoped stores. |
 | `versions` | `<list | view <version-id>> [project-dir]` | List the project's deployed versions, or show one version's artifact and bindings. |
 | `rollback` | `<version-id> [project-dir]` | Re-activate a previous version. |
@@ -29,7 +29,7 @@
 | `whoami` | — | Show the active endpoint and the account the stored token belongs to. |
 
 ```
-usage: sproutboat <init [name] | check [project-dir] | dev [project-dir] [--port <n>] [--no-watch] | build [project-dir] [--target host] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions <list | view <version-id>> [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--sprout] | kv <list | create <name> | info <name> | rename <name> <new> | delete <name>> | d1 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] | secrets <list | put <NAME> [--value <value>] | delete <NAME>> [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>] | logout [--api-url <url>] | whoami>
+usage: sproutboat <init [name] | check [project-dir] | dev [project-dir] [--port <n>] [--no-watch] | build [project-dir] [--target host] [--standalone] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions <list | view <version-id>> [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--sprout] | kv <list | create <name> | info <name> | rename <name> <new> | delete <name>> | d1 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] | secrets <list | put <NAME> [--value <value>] | delete <NAME>> [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>] | logout [--api-url <url>] | whoami>
 ```
 
 ## Environment variables
@@ -51,6 +51,13 @@ usage: sproutboat <init [name] | check [project-dir] | dev [project-dir] [--port
 | `SB_BROKER_PORT` | Loopback port of the binding broker, read by the compiled sprout at runtime (set by the control plane, or by `src/broker.ts` for local runs). |
 | `SB_BROKER_TOKEN` | Per-deployment auth token the sprout sends on every broker frame, and the broker sends back on scheduled/queue triggers (paired with SB_BROKER_PORT). |
 | `SB_SPROUT_URL` | http://127.0.0.1:<PORT> of the sprout; when set, `src/broker.ts` runs the cron scheduler and queue consumer and delivers triggers to it. |
+| `SB_DATA_DIR` | Where a standalone binary keeps store.sqlite and d1/ (#15). Read by the sprout itself in an embedded build; defaults to ./<name>.data. |
+| `SPROUTBOAT_DATA` | Data directory for a standalone binary, after --data and SB_DATA_DIR, before the ./<name>.data default (#15). |
+| `SB_CA_BUNDLE` | PEM bundle of extra certificate authorities a standalone binary should trust, on top of the compiled-in Mozilla root set (#15). Adds trust; nothing disables verification. |
+| `SB_FETCH_MAX_BYTES` | Largest outbound `fetch()` response body a sprout will read, in bytes (default 33554432). The size is the remote host's choice and the body is held whole, so this is the ceiling that stops one upstream exhausting memory. |
+| `SB_REQUEST_BODY_MAX` | Largest inbound request body the runtime accepts, in bytes (default 1048576). Anything larger is refused with 413 before the handler runs. |
+| `SB_EXTRA_CFLAGS` | Flags added to Porffor's native-fetch compile step, set by the build so inline C can include BearSSL's header (#15). |
+| `SB_EXTRA_LINK` | Objects to add to Porffor's native-fetch link line, set by the build so a standalone binary links SQLite and BearSSL (#15). |
 
 ## Build toolchain (pinned)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -49,7 +49,9 @@
     "surface": "UPDATE_SURFACE=1 bun test src/surface.test.ts",
     "version": "bun run surface && git add SURFACE.md",
     "prepublishOnly": "bun run typecheck && bun test",
-    "style": "bunx style-doctor@latest --quiet"
+    "style": "bunx style-doctor@latest --quiet",
+    "kitchen-sink": "bun examples/kitchen-sink/harness.ts",
+    "kitchen-sink:standalone": "bun examples/kitchen-sink/harness-standalone.ts"
   },
   "dependencies": {
     "esbuild": "^0.28.2",

package/src/bearssl.ts

@@ -0,0 +1,180 @@
+/**
+ * #15 — the TLS client an embedded sprout links against.
+ *
+ * BearSSL (MIT), plus the Mozilla root set compiled in as trust anchors. Both
+ * are downloaded, checksummed and built once into ~/.cache/sproutboat, keyed by
+ * version and target, in the same shape as the SQLite object.
+ *
+ * Why compiled-in anchors: a static musl binary has no portable system trust
+ * store — locations differ per distro and macOS wants keychain calls — so the
+ * root set travels with the binary. celld does the same. `SB_CA_BUNDLE` can
+ * point at a different bundle at run time.
+ *
+ * Why BearSSL over mbedTLS: measured, not assumed. A complete static client
+ * with all 121 anchors came to 192 KB against a 1.9 MB sprout.
+ */
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+export const BEARSSL_VERSION = "0.6";
+const BEARSSL_URL = `https://bearssl.org/bearssl-${BEARSSL_VERSION}.tar.gz`;
+const BEARSSL_SHA256 = "6705bba1714961b41a728dfc5debbe348d2966c117649392f8c8139efc83ff14";
+
+/**
+ * The Mozilla root set, as curl publishes it. Pinned by hash like everything
+ * else: a root store that changed under us without a version bump would be a
+ * silent change to what the binary trusts.
+ *
+ * ponytail: pinned per CLI release, so a certificate authority added after this
+ * release is unknown until the next one. Fine while releases are frequent;
+ * revisit if a user is ever stuck on an old CLI for months.
+ */
+const CACERT_URL = "https://curl.se/ca/cacert.pem";
+const CACERT_SHA256 = "f66dff1bdf8f96060b8177976f8b7d9254bc89bc4db933d769f7384d28480bc9";
+
+const cacheDir = (): string => resolve(homedir(), ".cache/sproutboat", `bearssl-${BEARSSL_VERSION}`);
+
+export type BearsslInput = {
+  target: "linux-x86_64" | "host";
+  /** Zig binary, required for the linux target. */
+  zigBin?: string;
+};
+
+export type BearsslBuild = {
+  /** Add to the compile step so the prelude can `#include <bearssl.h>`. */
+  includeDir: string;
+  /** Objects to add to the link line: the library plus the trust anchors. */
+  objects: string[];
+};
+
+const run = (cmd: string, args: string[], cwd?: string): Promise<{ code: number; stderr: string }> =>
+  new Promise((done) => {
+    const child = spawn(cmd, args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => (stderr += String(chunk)));
+    child.on("close", (code) => done({ code: code ?? 1, stderr }));
+  });
+
+async function download(url: string, expected: string, to: string): Promise<Buffer> {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`could not download ${url}: HTTP ${response.status}`);
+  const bytes = Buffer.from(await response.arrayBuffer());
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  if (digest !== expected) throw new Error(`checksum mismatch for ${url}: expected ${expected}, got ${digest}`);
+  await writeFile(to, bytes);
+  return bytes;
+}
+
+/** Unpack the source tree once, and build the host tools we need from it. */
+async function sourceTree(): Promise<string> {
+  const dir = cacheDir();
+  const tree = resolve(dir, `bearssl-${BEARSSL_VERSION}`);
+  if (existsSync(resolve(tree, "inc/bearssl.h"))) return tree;
+  await mkdir(dir, { recursive: true });
+  const tarball = resolve(dir, "bearssl.tar.gz");
+  if (!existsSync(tarball)) await download(BEARSSL_URL, BEARSSL_SHA256, tarball);
+  const untar = await run("tar", ["xzf", tarball], dir);
+  if (untar.code !== 0) throw new Error(`could not unpack BearSSL: ${untar.stderr}`);
+  return tree;
+}
+
+/** Every .c under src/, which is what the library is. */
+async function sources(tree: string): Promise<string[]> {
+  const found: string[] = [];
+  const walk = async (dir: string): Promise<void> => {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const path = resolve(dir, entry.name);
+      if (entry.isDirectory()) await walk(path);
+      else if (entry.name.endsWith(".c")) found.push(path);
+    }
+  };
+  await walk(resolve(tree, "src"));
+  return found.sort();
+}
+
+/**
+ * `brssl ta` turns a PEM bundle into C trust-anchor structs. It is a host tool,
+ * so it is built with the host compiler whatever the sprout's target is.
+ */
+async function trustAnchorTool(tree: string): Promise<string> {
+  const tool = resolve(tree, "build/brssl");
+  if (existsSync(tool)) return tool;
+  const make = await run("make", ["-j8", "build/brssl"], tree);
+  if (!existsSync(tool)) throw new Error(`could not build brssl: ${make.stderr}`);
+  return tool;
+}
+
+/**
+ * Generate the trust anchors as linkable C.
+ *
+ * `brssl` emits them `static`, which is right for its own samples and useless
+ * to us: the prelude has to reach them from another translation unit. Rename
+ * the array and publish a count beside it.
+ */
+async function trustAnchorSource(tree: string): Promise<string> {
+  const out = resolve(cacheDir(), "trust-anchors.c");
+  if (existsSync(out)) return out;
+  const pem = resolve(cacheDir(), "cacert.pem");
+  if (!existsSync(pem)) await download(CACERT_URL, CACERT_SHA256, pem);
+  const tool = await trustAnchorTool(tree);
+
+  const generated = await new Promise<string>((done, fail) => {
+    const child = spawn(tool, ["ta", pem], { stdio: ["ignore", "pipe", "pipe"] });
+    let text = "";
+    let err = "";
+    child.stdout.on("data", (chunk) => (text += String(chunk)));
+    child.stderr.on("data", (chunk) => (err += String(chunk)));
+    child.on("close", (code) => (code === 0 ? done(text) : fail(new Error(`brssl ta failed: ${err}`))));
+  });
+
+  const count = /#define TAs_NUM\s+(\d+)/.exec(generated)?.[1];
+  if (!count) throw new Error("brssl ta produced no TAs_NUM — its output format changed");
+  const linkable = generated
+    .replace(/static const br_x509_trust_anchor TAs\[/, "const br_x509_trust_anchor sb_trust_anchors[")
+    .replace(/#define TAs_NUM\s+\d+/, `const size_t sb_trust_anchor_count = ${count};`);
+  await writeFile(out, `#include <stddef.h>\n#include "bearssl.h"\n${linkable}\n`);
+  return out;
+}
+
+/** Compile one C file, caching on the output path. */
+async function compile(cc: string, prefix: string[], source: string, out: string, includes: string[]): Promise<void> {
+  if (existsSync(out)) return;
+  const result = await run(cc, [...prefix, "-c", source, "-o", out, "-Os", ...includes.flatMap((i) => ["-I", i])]);
+  if (result.code !== 0) throw new Error(`could not compile ${source}:\n${result.stderr}`);
+}
+
+/** BearSSL objects plus trust anchors for this target, building them on first use. */
+export async function ensureBearssl(input: BearsslInput): Promise<BearsslBuild> {
+  const tree = await sourceTree();
+  const includeDir = resolve(tree, "inc");
+  const objDir = resolve(cacheDir(), `obj-${input.target}`);
+  await mkdir(objDir, { recursive: true });
+
+  const [cc, prefix] =
+    input.target === "host"
+      ? (["cc", []] as const)
+      : ([input.zigBin ?? "zig", ["cc", "-target", "x86_64-linux-musl"]] as const);
+  const includes = [includeDir, resolve(tree, "src")];
+
+  const objects: string[] = [];
+  // Sequential rather than parallel: this runs once per target and a burst of
+  // ~180 compiler processes is a worse neighbour than a slow first build.
+  for (const source of await sources(tree)) {
+    const out = resolve(objDir, `${source.split("/").pop()!.replace(/\.c$/, "")}.o`);
+    await compile(cc, [...prefix], source, out, includes);
+    objects.push(out);
+  }
+
+  const anchors = await trustAnchorSource(tree);
+  const anchorObject = resolve(objDir, "trust-anchors.o");
+  await compile(cc, [...prefix], anchors, anchorObject, includes);
+  objects.push(anchorObject);
+
+  return { includeDir, objects };
+}
+
+export const bearsslStamp = (): string => `bearssl/${BEARSSL_VERSION}`;