sproutboat 0.6.0 → 0.7.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.6.0 · runs on Bun (use `bunx`, not `npx`)
+**Package:** `sproutboat` 0.7.0 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 
@@ -20,7 +20,7 @@
 | `kv` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | KV namespaces. `create` prints the id to bind from sproutboat.jsonc. |
 | `d1` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | D1 databases. `create` prints the id to bind from sproutboat.jsonc. |
 | `r2` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | R2 buckets. `create` prints the id to bind from sproutboat.jsonc. |
-| `queues` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | Queues. `create` prints the id to bind from sproutboat.jsonc; consumers are not implemented yet. |
+| `queues` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | Queues. `create` prints the id to bind from sproutboat.jsonc; consumers deliver in batches with retries, and stop after 5 attempts. |
 | `domains` | `<list | add <host> | verify <host> | delete <host>> [project-dir]` | Attach a custom domain to the project (TXT-verified). No sub-command lists. |
 | `secrets` | `<list | put <NAME> [--value <value>] | delete <NAME>> [project-dir]` | Manage encrypted project secrets (read as env.NAME). `put` reads the value from stdin unless --value is given, so it stays out of shell history; applies on next deploy. |
 | `delete` | `[project-dir] [--name <project>] --yes` | Delete the project, every version, and its route. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -61,7 +61,7 @@
     "lefthook": "2.1.12",
     "oxfmt": "0.66.0",
     "oxlint": "1.81.0",
-    "typescript": "5.9.2"
+    "typescript": "7.0.2"
   },
   "engines": {
     "bun": ">=1.4.0"

package/src/api-version.ts

@@ -0,0 +1,32 @@
+/**
+ * Version skew between a CLI and a control plane.
+ *
+ * The two update independently — the CLI from npm, a self-hosted node from its
+ * own `SB_REF` — so a user can easily point a months-old CLI at a fresh box or
+ * the reverse. Without a handshake that shows up as a 400 from a route that
+ * moved, which tells them nothing.
+ *
+ * The exchange is response-only: every `/api/` response carries the control
+ * plane's version and the oldest CLI it supports, and the CLI checks those on
+ * responses it was already reading. Nothing is added to requests, so an old
+ * control plane simply sends no headers and nothing happens.
+ */
+import { isNewer } from "./update-check";
+
+export const CONTROL_VERSION_HEADER = "x-sproutboat-control";
+export const MIN_CLI_HEADER = "x-sproutboat-min-cli";
+
+/**
+ * The warning to print for this response, or null when the pair is fine.
+ * Pure so it can be tested without a server; `main.ts` prints what it returns.
+ */
+export function controlVersionWarning(response: Response, cliVersion: string): string | null {
+  const min = response.headers.get(MIN_CLI_HEADER);
+  // No header: a control plane older than this handshake. Nothing to say.
+  if (!min || !isNewer(min, cliVersion)) return null;
+  const control = response.headers.get(CONTROL_VERSION_HEADER);
+  return (
+    `this control plane${control ? ` (${control})` : ""} needs sproutboat ${min} or newer, ` +
+    `and you are on ${cliVersion} — upgrade with \`bun add -g sproutboat@latest\``
+  );
+}

package/src/build.ts

@@ -99,6 +99,7 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
     bindings,
     zigBin,
     target: input.target,
+    compatibilityDate: input.config.compatibility_date,
   });
 
   const sprout = await readFile(sproutPath);
@@ -111,6 +112,7 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
     porfforVersion: porfforVersion(),
     esbuildVersion: esbuildVersion(),
     buildImage: toolchainStamp(),
+    compatibilityDate: input.config.compatibility_date,
     sourceHash,
     binaryHash: digest(sprout),
     binarySize: (await stat(sproutPath)).size,

package/src/compile.ts

@@ -15,7 +15,13 @@ import { ensurePorfforPatched } from "./patch-porffor";
 import { ensureUWebSockets, porfforRoot, UwsUnavailableError } from "./toolchain";
 import { EMPTY_BINDINGS, preludePath, wrapNativeFetchHandler, type Bindings } from "./wrap";
 
-export { EMPTY_BINDINGS, preludePath, wrapNativeFetchHandler, type Bindings } from "./wrap";
+export {
+  BASELINE_COMPATIBILITY_DATE,
+  EMPTY_BINDINGS,
+  preludePath,
+  wrapNativeFetchHandler,
+  type Bindings,
+} from "./wrap";
 
 const COMPILE_TIMEOUT_MS = Number(process.env.SPROUTBOAT_COMPILE_TIMEOUT_MS || 600_000);
 
@@ -26,6 +32,9 @@ export type CompileInput = {
   outPath: string;
   vars: Record<string, string>;
   bindings?: Bindings;
+  /** The project's `compatibility_date`, baked in so the runtime can gate a
+   *  behaviour change on it. Defaults to the baseline when absent. */
+  compatibilityDate?: string;
   /** Cross-compiler for `linux-x86_64`. Not needed, and not used, for `host`. */
   zigBin?: string;
   /**
@@ -76,7 +85,17 @@ export async function compileSprout(input: CompileInput): Promise<void> {
     input.source === undefined ? readFile(input.sourcePath, "utf8") : Promise.resolve(input.source),
     readFile(preludePath, "utf8"),
   ]);
-  await writeFile(generatedPath, wrapNativeFetchHandler(source, prelude, input.vars, input.bindings ?? EMPTY_BINDINGS));
+  await writeFile(
+    generatedPath,
+    wrapNativeFetchHandler(
+      source,
+      prelude,
+      input.vars,
+      input.bindings ?? EMPTY_BINDINGS,
+      undefined,
+      input.compatibilityDate,
+    ),
+  );
 
   const porffor = porfforRoot();
   const launcher = resolve(porffor, "runtime/index.js");

package/src/main.ts

@@ -13,11 +13,26 @@ import { CLI_VERSION, printDeployReport } from "./report";
 import { activeApiUrl, forgetToken, savedToken, saveToken } from "./credentials";
 import { helpText, STORAGE_PRODUCTS, STORAGE_VERBS, type StorageProduct } from "./surface";
 import { notifyIfOutdated } from "./update-check";
+import { controlVersionWarning } from "./api-version";
 import { amber, bold, dim, leaf, ok, rose } from "./style";
 
 const defaultApiUrl = "https://dashboard.sproutboat.com";
 
+/** Warn at most once per run: every API response carries the headers, and one
+ *  command makes several calls. */
+let skewWarned = false;
+
 async function responseText(response: Response, failure: string): Promise<string> {
+  // Checked here rather than at each call site: every control-plane response
+  // funnels through this helper, including the failures — and a version-skew
+  // 400 is exactly when the user most needs to be told which side is old.
+  if (!skewWarned) {
+    const warning = controlVersionWarning(response, CLI_VERSION);
+    if (warning) {
+      skewWarned = true;
+      console.warn(amber(`! ${warning}`));
+    }
+  }
   if (response.ok) return response.text();
   fail(`${failure} (${response.status}): ${await response.text()}`);
 }

package/src/manifest.ts

@@ -24,6 +24,16 @@ export type ArtifactManifest = {
   esbuildVersion: string;
   /** Build provenance, e.g. `zig-musl/0.16.0+porffor/a415d19+uws/360c276d`. */
   buildImage: string;
+  /**
+   * The project's `compatibility_date`, as `YYYY-MM-DD`. Optional: artifacts
+   * built before this field existed have none, and every reader must treat that
+   * as the baseline (see `BASELINE_COMPATIBILITY_DATE` in `wrap.ts`). This is
+   * how a runtime behaviour change ships without breaking deployed apps — new
+   * builds opt in by moving their date, old binaries keep the old semantics —
+   * so it is deliberately *not* part of `schemaVersion`, which stays frozen
+   * at 2.
+   */
+  compatibilityDate?: string;
   sourceHash: `sha256:${string}`;
   binaryHash: `sha256:${string}`;
   binarySize: number;
@@ -110,6 +120,15 @@ export function validateManifest(value: ManifestInput): ManifestValidation {
   if (binarySize === null) errors.push("binarySize must be a positive integer");
   const builtAt = isString(value.builtAt) && !Number.isNaN(Date.parse(value.builtAt)) ? value.builtAt : null;
   if (builtAt === null) errors.push("builtAt must be an ISO-8601 timestamp");
+  // Optional by design: an artifact from before the field existed is valid and
+  // must stay deployable, so "absent" is not an error — only "present and
+  // malformed" is.
+  let compatibilityDate: string | undefined;
+  if (value.compatibilityDate !== undefined) {
+    if (isString(value.compatibilityDate) && /^\d{4}-\d{2}-\d{2}$/.test(value.compatibilityDate))
+      compatibilityDate = value.compatibilityDate;
+    else errors.push("compatibilityDate must be YYYY-MM-DD");
+  }
   if (
     errors.length ||
     schemaVersion === null ||
@@ -142,6 +161,7 @@ export function validateManifest(value: ManifestInput): ManifestValidation {
       binaryHash,
       binarySize,
       builtAt,
+      compatibilityDate,
     },
   };
 }

package/src/surface.ts

@@ -59,7 +59,7 @@ const storageCommands: readonly Command[] = STORAGE_PRODUCTS.map((product) => ({
   emoji: product.emoji,
   args: STORAGE_ARGS,
   brief: `<${STORAGE_VERBS.join(" | ")}>`,
-  summary: `${product.plural[0].toUpperCase()}${product.plural.slice(1)}. \`create\` prints the id to bind from sproutboat.jsonc${product.name === "queues" ? "; consumers are not implemented yet" : ""}.`,
+  summary: `${product.plural[0].toUpperCase()}${product.plural.slice(1)}. \`create\` prints the id to bind from sproutboat.jsonc${product.name === "queues" ? "; consumers deliver in batches with retries, and stop after 5 attempts" : ""}.`,
 }));
 
 export const COMMANDS: readonly Command[] = [

package/src/update-check.ts

@@ -28,7 +28,7 @@ function cachePath(): string {
 }
 
 /** Numeric x.y.z compare; a trailing `-tag` (prerelease) sorts before its release. */
-function isNewer(latest: string, current: string): boolean {
+export function isNewer(latest: string, current: string): boolean {
   const parts = (v: string) =>
     v
       .split("-")[0]

package/src/wrap.ts

@@ -17,6 +17,20 @@ export const preludePath = new URL("./native-fetch-prelude.js", import.meta.url)
 // value is only a fallback for a directly-run binary.
 const DEFAULT_PORT = 8080;
 
+/**
+ * What an artifact with no `compatibilityDate` means. Artifacts built before
+ * the field existed keep the semantics of that day forever, because the binary
+ * is immutable and `rollback` can reactivate it at any time.
+ *
+ * How to use it: when a runtime behaviour has to change in a way that would
+ * break a deployed handler, don't change it unconditionally — gate it in the
+ * prelude on `__sbCompat >= "YYYY-MM-DD"` (ISO dates compare correctly as
+ * strings) and document the flip date. Old binaries carry their old date and
+ * keep the old behaviour; a project opts in by moving `compatibility_date` in
+ * its `sproutboat.jsonc` and rebuilding.
+ */
+export const BASELINE_COMPATIBILITY_DATE = "2026-08-26";
+
 /**
  * Binding names a project declares. `do` maps a binding name to a Durable Object
  * class name; `crons` are schedule expressions with no name.
@@ -127,6 +141,7 @@ export function wrapNativeFetchHandler(
   vars: Record<string, string> = {},
   bindings: Bindings = EMPTY_BINDINGS,
   port: number = DEFAULT_PORT,
+  compatibilityDate: string = BASELINE_COMPATIBILITY_DATE,
 ): string {
   const neutralised = neutraliseExports(source);
   if (neutralised === null || !/\bfetch\s*\(/.test(source)) {
@@ -134,13 +149,16 @@ export function wrapNativeFetchHandler(
   }
 
   const env = `const env = ${JSON.stringify(vars)};\nglobalThis.env = env;\n`;
+  // Baked, not a binding: the date belongs to the artifact, and a handler must
+  // not be able to change the semantics it was compiled against at runtime.
+  const compat = `globalThis.__sbCompat = ${JSON.stringify(compatibilityDate)};\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}` +
+    `${prelude}\n${compat}${env}${wire}` +
     `${neutralised}\n` +
     `${registerDO}` +
     `export default {\n  port: ${port},\n  fetch(request) { return __sbEntry(__sbHandlers, request); }\n};\n`