sproutboat 0.10.1 → 0.10.3

package/CHANGELOG.md

@@ -10,6 +10,42 @@ maintained going forward by the `release` skill.
 
 ## [Unreleased]
 
+## [0.10.3] - 2026-09-11
+### Added
+- Rate-limiter result carries `resetAt`: `env.<NAME>.limit({ key })` now returns
+  `{ success, resetAt }`, where `resetAt` is epoch ms for when the fixed window
+  rolls, so a `429` can send an accurate `Retry-After`
+  (baronunread/sproutboat#69). Additive; callers reading only `success` are
+  unaffected.
+
+### Changed
+- `@sproutboat/runtime` and `@sproutboat/wire` bumped to `^0.5.0`; they carry
+  the `resetAt` value the rate-limiter type now declares.
+
+### Docs
+- `docs/standalone.md`: dropped the stale "outbound `fetch()` speaks `http://`
+  only" bullet. Standalone binaries link BearSSL and verify HTTPS against the
+  Mozilla root set (see "TLS, in both directions"). Added a
+  dev/standalone/deployed parity note: every binding op, rate limiters and
+  `request.cf.clientIp` with `SB_TRUSTED_PROXIES` included, behaves the same
+  under `sproutboat dev` as in a standalone binary and a deployed sprout.
+- `capability-http-sync-v0.md`: documented async handlers. `fetch` may return a
+  promise it creates (not a `.then()`-chained one, which hangs); async responses
+  omit `x-sb-cpu-ms`; `crypto.subtle` digest/sign/verify are async in signature
+  only over synchronous inline C, so per-request hashing costs no I/O.
+
+## [0.10.2] - 2026-09-11
+### Fixed
+- The one-time Zig download no longer depends on ziglang.org being reachable.
+  It now pulls from a random Zig community mirror, with ziglang.org kept only
+  as a last resort, and tries the mirrors in turn on failure. ziglang.org
+  rate-limits the multi-megabyte tarballs and had been timing out mid-build,
+  with no fallback (baronunread/sproutboat#166). The archive sha256 is still
+  enforced whatever the source. `SPROUTBOAT_ZIG_URL` overrides the source;
+  `SPROUTBOAT_ZIG` still points at a prebuilt binary.
+- A leftover `~/.cache/sproutboat/zig-<version>/` directory from an earlier
+  cache layout is removed on the next build instead of sitting unused.
+
 ## [0.10.1] - 2026-09-11
 ### Fixed
 - `npm install sproutboat` / `bunx sproutboat` work again. 0.10.0's launcher
@@ -358,7 +394,9 @@ its own package.
 - Renamed the package to `sproutboat` (was `@sproutboat/cli`); dropped the
   `sprout` bin alias in favour of a user-defined shell alias.
 
-[Unreleased]: https://github.com/baronunread/sproutboat-cli/compare/v0.10.1...HEAD
+[Unreleased]: https://github.com/baronunread/sproutboat-cli/compare/v0.10.3...HEAD
+[0.10.3]: https://github.com/baronunread/sproutboat-cli/compare/v0.10.2...v0.10.3
+[0.10.2]: https://github.com/baronunread/sproutboat-cli/compare/v0.10.1...v0.10.2
 [0.10.1]: https://github.com/baronunread/sproutboat-cli/compare/v0.10.0...v0.10.1
 [0.10.0]: https://github.com/baronunread/sproutboat-cli/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/baronunread/sproutboat-cli/compare/v0.8.0...v0.9.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.10.1 · runs on Bun (use `bunx`, not `npx`)
+**Package:** `sproutboat` 0.10.3 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 
@@ -40,6 +40,7 @@ usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev
 | `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_ZIG_URL` | URL to download the pinned Zig tarball from, instead of a Zig community mirror. The sha256 is still enforced. |
 | `SPROUTBOAT_UWS_TARBALL` | Path to a uWebSockets source tarball to seed the Porffor cache with, instead of the one vendored in the package. Both targets are seeded from it. |
 | `CC` | C compiler used to build uSockets for a host build (default `cc`). A host build needs one regardless: it is what Porffor compiles its own generated C with. |
 | `AR` | Archiver used to assemble uSockets.a for a host build (default `ar`). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -63,9 +63,9 @@
     "@sproutboat/artifact": "^0.2.0",
     "@sproutboat/assets": "^0.2.0",
     "@sproutboat/config": "^0.3.0",
-    "@sproutboat/runtime": "^0.4.0",
+    "@sproutboat/runtime": "^0.5.0",
     "@sproutboat/toolchain": "^0.3.0",
-    "@sproutboat/wire": "^0.4.0",
+    "@sproutboat/wire": "^0.5.0",
     "esbuild": "^0.28.2"
   },
   "devDependencies": {

package/src/surface.ts

@@ -194,6 +194,11 @@ 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_ZIG_URL",
+    purpose:
+      "URL to download the pinned Zig tarball from, instead of a Zig community mirror. The sha256 is still enforced.",
+  },
   {
     name: "SPROUTBOAT_UWS_TARBALL",
     purpose:

package/src/toolchain.ts

@@ -2,8 +2,11 @@
  * The build toolchain: a pinned Zig (the linux-x86_64 cross-compiler Porffor
  * shells out to for `--musl`) plus version stamps for the artifact manifest.
  *
- * Zig is fetched once to ~/.cache/sproutboat/zig-<version>/ and reused. No
- * Docker, no root. Override with SPROUTBOAT_ZIG=/path/to/zig.
+ * Zig is fetched once to ~/.cache/sproutboat/zig-<version>-<platform>/ and
+ * reused. No Docker, no root. It comes from a random Zig community mirror with
+ * ziglang.org as the last resort, because ziglang.org rate-limits the large
+ * tarballs and has been timing out. Override the binary with
+ * SPROUTBOAT_ZIG=/path/to/zig, or the download source with SPROUTBOAT_ZIG_URL.
  */
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
@@ -101,24 +104,69 @@ async function zigComplete(dir: string, key: ZigPlatform, expectedArchive: strin
   }
 }
 
+// Zig asks tooling not to hammer ziglang.org for the multi-megabyte tarballs:
+// pick a random community mirror and keep the official host only as a last
+// resort. https://ziglang.org/download/community-mirrors.txt
+const ZIG_MIRRORS_URL = "https://ziglang.org/download/community-mirrors.txt";
+
+function shuffle<T>(items: T[]): T[] {
+  for (let i = items.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [items[i], items[j]] = [items[j], items[i]];
+  }
+  return items;
+}
+
+/**
+ * Ordered list of URLs to try for the pinned Zig tarball: the community mirrors
+ * (shuffled) followed by ziglang.org. Falls back to ziglang.org alone if the
+ * mirror list itself is unreachable.
+ */
+async function zigDownloadUrls(
+  key: ZigPlatform,
+  fetcher: NonNullable<EnsureZigOptions["fetcher"]>,
+  timeoutMs: number,
+): Promise<string[]> {
+  const file = `zig-${key}-${ZIG_VERSION}.tar.xz`;
+  const official = `https://ziglang.org/download/${ZIG_VERSION}/${file}`;
+  try {
+    const response = await fetcher(ZIG_MIRRORS_URL, { signal: AbortSignal.timeout(Math.min(timeoutMs, 10_000)) });
+    if (response.ok) {
+      const mirrors = (await response.text())
+        .split(/\s+/)
+        .filter((line) => line.startsWith("https://"))
+        .map((base) => `${base.replace(/\/+$/, "")}/${file}`);
+      if (mirrors.length > 0) return [...shuffle(mirrors), official];
+    }
+  } catch {
+    // Mirror list unreachable: the official host is the only option left.
+  }
+  return [official];
+}
+
 async function downloadZig(
-  url: string,
+  urls: string[],
   path: string,
   fetcher: NonNullable<EnsureZigOptions["fetcher"]>,
   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;
+  // One shot per mirror; two at the single fallback URL so a lone flaky host
+  // still gets a retry.
+  const attemptsPer = urls.length > 1 ? 1 : 2;
+  const failures: string[] = [];
+  for (const url of urls) {
+    for (let attempt = 0; attempt < attemptsPer; 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) {
+        failures.push(`${url}: ${String(error)}`);
+      }
     }
   }
-  throw new ZigToolchainError("download", `could not download pinned Zig from ${url}: ${String(last)}`);
+  throw new ZigToolchainError("download", `could not download pinned Zig\n  ${failures.join("\n  ")}`);
 }
 
 async function waitForZigPublisher(
@@ -151,6 +199,10 @@ export async function ensureZig(options: EnsureZigOptions = {}): Promise<string>
   const root = resolve(
     options.cacheRoot ?? process.env.SPROUTBOAT_TOOLCHAIN_CACHE ?? resolve(homedir(), ".cache/sproutboat"),
   );
+  // Older builds cached Zig at `zig-<version>/` with no platform suffix; nothing
+  // reads that layout now, so drop it rather than leave it as dead weight.
+  const legacy = resolve(root, `zig-${ZIG_VERSION}`);
+  if (existsSync(legacy)) await rm(legacy, { recursive: true, force: true }).catch(() => {});
   const dir = resolve(root, `zig-${ZIG_VERSION}-${key}`);
   const expected = options.expectedSha256 ?? ZIG_SHA256[key];
   if (await zigComplete(dir, key, expected)) return resolve(dir, "zig");
@@ -164,14 +216,16 @@ export async function ensureZig(options: EnsureZigOptions = {}): Promise<string>
     return ensureZig(options);
   }
   const stage = resolve(root, `.zig-${ZIG_VERSION}-${key}-${process.pid}-${crypto.randomUUID()}`);
-  const url = options.url ?? `https://ziglang.org/download/${ZIG_VERSION}/zig-${key}-${ZIG_VERSION}.tar.xz`;
+  const fetcher = options.fetcher ?? fetch;
+  const sourceUrl = options.url ?? process.env.SPROUTBOAT_ZIG_URL;
+  const urls = sourceUrl ? [sourceUrl] : await zigDownloadUrls(key, fetcher, options.timeoutMs ?? 30_000);
   console.log(`Fetching Zig ${ZIG_VERSION} (${key}, one-time)...`);
   try {
     if (await zigComplete(dir, key, expected)) return resolve(dir, "zig");
     await rm(dir, { recursive: true, force: true });
     await mkdir(stage);
     const archive = resolve(stage, "zig.tar.xz");
-    await downloadZig(url, archive, options.fetcher ?? fetch, options.timeoutMs ?? 30_000);
+    await downloadZig(urls, archive, fetcher, options.timeoutMs ?? 60_000);
     const actual = await sha256File(archive);
     if (actual !== expected)
       throw new ZigToolchainError(

package/types/sproutboat.d.ts

@@ -182,9 +182,13 @@ declare global {
    * A rate-limiter binding (#69). `limit` and `period` are fixed in
    * sproutboat.jsonc; `limit({ key })` counts one call against a fixed window
    * and reports whether the key is still under the cap.
+   *
+   * `resetAt` is epoch milliseconds for when the window rolls and the count
+   * clears — the same for a hit or a miss. Turn a rejection into a header with
+   * `Retry-After: Math.ceil((resetAt - Date.now()) / 1000)`.
    */
   interface RateLimit {
-    limit(options: { key: string }): { success: boolean };
+    limit(options: { key: string }): { success: boolean; resetAt: number };
   }
 
   // ------------------------------------ Crypto