sproutboat 0.10.1 → 0.10.2

package/CHANGELOG.md

@@ -10,6 +10,18 @@ maintained going forward by the `release` skill.
 
 ## [Unreleased]
 
+## [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 +370,8 @@ 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.2...HEAD
+[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.2 · 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.2",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",

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(