sproutboat 0.54.0 → 0.55.0

package/src/cloud-bindings.ts

@@ -0,0 +1,227 @@
+/**
+ * `sproutboat.jsonc` bindings as the Sproutboat Cloud's app record carries them (sproutboat-cloud `src/record.ts`,
+ * `bindings`, `crons`, `queue_consumers`). The Cloud validates the same shape again on `PUT /v1/apps/<app>` and
+ * `POST /v1/apps/<app>/builds`; checking here means a mistake fails before anything is uploaded, in the CLI's words.
+ *
+ * Where a resource id comes from: on the Cloud each app's storage is private to it, so the binding is the name
+ * (`d1_databases: ["DB"]` is `d1/DB`, the name `d1 execute --remote` and `r2 object` address). A binding that needs a
+ * `resource_id` (kv, d1, r2, queue) gets its own name in lowercase, because the record's resource ids are lowercase;
+ * a queue gets its queue name. Nothing is provisioned: the host creates the storage on first use.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { queueSettings, resourceRefs, type SproutboatConfig } from "./config";
+import { CloudError } from "./cloud";
+
+export type RecordBinding = {
+  name: string;
+  kind: "kv" | "d1" | "r2" | "queue" | "do" | "ae" | "ratelimit" | "assets" | "secret";
+  resource_id: string | null;
+  config: Record<string, string | number>;
+};
+export type RecordQueueConsumer = {
+  queue: string;
+  max_batch_size: number;
+  max_batch_timeout_ms: number;
+  max_retries: number;
+  dead_letter_queue: string | null;
+};
+export type CloudBindings = {
+  bindings: RecordBinding[];
+  crons: string[];
+  queue_consumers: RecordQueueConsumer[];
+  /** Things the Cloud ignores, said once before the deploy. */
+  warnings: string[];
+};
+
+/** The record's own limits (sproutboat-cloud `src/record.ts`). */
+export const MAX_BINDINGS = 64;
+export const MAX_CRONS = 16;
+export const MAX_QUEUE_CONSUMERS = 16;
+const RESOURCE_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const CRON_CHARS_RE = /^[0-9A-Za-z*,/ -]+$/;
+
+/** Cloudflare's defaults for a queue consumer, which the runtime applies when sproutboat.jsonc leaves a setting out. */
+const QUEUE_DEFAULTS = { maxBatchSize: 10, maxBatchTimeout: 0, maxRetries: 3 };
+
+/** `resource_id` for a binding or queue name: lowercase, so `DB` is `db` and `EMAILS` is `emails`. */
+function resourceIdFor(what: string, name: string): string {
+  const id = name.toLowerCase();
+  if (!RESOURCE_ID_RE.test(id))
+    throw new CloudError(
+      `${what} "${name}" cannot be a Cloud resource name: lowercased it must be 1 to 64 characters, start with a letter or digit, and use only letters, digits, "_" and "-"`,
+    );
+  return id;
+}
+
+/** A cron as the Cloud stores it: single spaces, five fields, at most 128 characters of the allowed set. */
+function normalizeCron(expression: string): string {
+  const cron = expression.trim().split(/\s+/).join(" ");
+  if (cron.length > 128 || !CRON_CHARS_RE.test(cron) || cron.split(" ").length !== 5)
+    throw new CloudError(
+      `triggers.crons: "${expression}" is not a cron the Cloud accepts (5 fields of digits, letters and * , / -, at most 128 characters)`,
+    );
+  return cron;
+}
+
+type Mappable = Pick<
+  SproutboatConfig,
+  | "kv_namespaces"
+  | "d1_databases"
+  | "r2_buckets"
+  | "queues"
+  | "analytics_engine_datasets"
+  | "durable_objects"
+  | "ratelimiters"
+  | "secrets"
+  | "assets"
+  | "triggers"
+>;
+
+/**
+ * Every binding kind in sproutboat.jsonc as a record entry, plus `crons` and one `queue_consumers` entry per queue
+ * (the worker consumes every queue it binds). `serviceBindings` is how many service bindings the deploy adds, so the
+ * 64-binding limit counts them. Throws CloudError for anything the Cloud would refuse.
+ */
+export function mapCloudBindings(config: Mappable, serviceBindings = 0): CloudBindings {
+  const bindings: RecordBinding[] = [];
+  const warnings: string[] = [];
+  const pinned: string[] = [];
+
+  for (const [kind, field] of [
+    ["kv", "kv_namespaces"],
+    ["d1", "d1_databases"],
+    ["r2", "r2_buckets"],
+  ] as const)
+    for (const ref of resourceRefs(config[field])) {
+      if (ref.id !== undefined) pinned.push(`${field}.${ref.binding}`);
+      bindings.push({
+        name: ref.binding,
+        kind,
+        resource_id: resourceIdFor(`${field} binding`, ref.binding),
+        config: {},
+      });
+    }
+
+  const queue_consumers: RecordQueueConsumer[] = [];
+  const queueNames = new Set<string>();
+  for (const queue of queueSettings(config.queues)) {
+    const resource = resourceIdFor("queue", queue.queue);
+    if (queueNames.has(resource))
+      throw new CloudError(
+        `queues: two bindings name the queue "${resource}" (queue names are lowercase on the Cloud)`,
+      );
+    queueNames.add(resource);
+    const settings: RecordBinding["config"] = { queue: queue.queue };
+    if (queue.retryDelay !== undefined) settings.retry_delay = queue.retryDelay;
+    bindings.push({ name: queue.binding, kind: "queue", resource_id: resource, config: settings });
+    queue_consumers.push({
+      queue: resource,
+      max_batch_size: queue.maxBatchSize ?? QUEUE_DEFAULTS.maxBatchSize,
+      max_batch_timeout_ms: Math.round((queue.maxBatchTimeout ?? QUEUE_DEFAULTS.maxBatchTimeout) * 1000),
+      max_retries: queue.maxRetries ?? QUEUE_DEFAULTS.maxRetries,
+      dead_letter_queue:
+        queue.deadLetterQueue === undefined ? null : resourceIdFor("dead_letter_queue", queue.deadLetterQueue),
+    });
+  }
+  for (const ref of resourceRefs(config.queues)) if (ref.id !== undefined) pinned.push(`queues.${ref.binding}`);
+
+  for (const name of config.analytics_engine_datasets ?? [])
+    bindings.push({ name, kind: "ae", resource_id: null, config: {} });
+  for (const [name, className] of Object.entries(config.durable_objects ?? {}))
+    bindings.push({ name, kind: "do", resource_id: null, config: { class_name: className } });
+  for (const limiter of config.ratelimiters ?? [])
+    bindings.push({
+      name: limiter.binding,
+      kind: "ratelimit",
+      resource_id: null,
+      config: { limit: limiter.limit, period: limiter.period },
+    });
+  if (config.assets?.binding)
+    bindings.push({ name: config.assets.binding, kind: "assets", resource_id: null, config: {} });
+  for (const name of config.secrets ?? []) bindings.push({ name, kind: "secret", resource_id: null, config: {} });
+
+  if (bindings.length + serviceBindings > MAX_BINDINGS)
+    throw new CloudError(
+      `sproutboat.jsonc declares ${bindings.length + serviceBindings} bindings (secrets, services and assets count); the Cloud takes at most ${MAX_BINDINGS} per app`,
+    );
+  if (queue_consumers.length > MAX_QUEUE_CONSUMERS)
+    throw new CloudError(
+      `sproutboat.jsonc binds ${queue_consumers.length} queues, and each one is consumed by the app; the Cloud takes at most ${MAX_QUEUE_CONSUMERS} queue consumers per app`,
+    );
+  const crons = (config.triggers?.crons ?? []).map(normalizeCron);
+  if (crons.length > MAX_CRONS)
+    throw new CloudError(`triggers.crons lists ${crons.length} crons; the Cloud takes at most ${MAX_CRONS} per app`);
+
+  if (pinned.length > 0)
+    warnings.push(
+      `${pinned.join(", ")} pin${pinned.length === 1 ? "s" : ""} an account-level id; on the Cloud each app's storage is private to it, so the id is ignored and the app gets its own`,
+    );
+  return { bindings, crons, queue_consumers, warnings };
+}
+
+/** The names a module exports, as far as its source says. `null` when an `export *` hides some. */
+function exportedNames(source: string): Set<string> | null {
+  const code = source
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[^:])\/\/.*$/gm, "$1")
+    .replace(/"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'/g, '""');
+  if (/\bexport\s*\*\s*(?!as\b)from\b/.test(code)) return null;
+  const names = new Set<string>();
+  for (const m of code.matchAll(
+    /\bexport\s+(?:default\s+)?(?:async\s+)?(?:class|function\*?|const|let|var)\s+([A-Za-z_$][\w$]*)/g,
+  ))
+    names.add(m[1]!);
+  for (const m of code.matchAll(/\bexport\s*(?:type\s*)?\{([^}]*)\}/g))
+    for (const part of m[1]!.split(",")) {
+      const exported = part
+        .trim()
+        .split(/\s+as\s+/)
+        .at(-1)
+        ?.trim();
+      if (exported) names.add(exported);
+    }
+  for (const m of code.matchAll(/\bexport\s*\*\s*as\s+([A-Za-z_$][\w$]*)\s+from\b/g)) names.add(m[1]!);
+  return names;
+}
+
+/**
+ * Every class named in `durable_objects` must be exported by the entry module, or the app starts and then fails at the
+ * first Durable Object call. Checked from the source text: a source with an `export *` cannot be judged and passes, and so
+ * does an entry the CLI cannot read (the build reports that itself).
+ */
+export function checkDurableObjectExports(config: Mappable & Pick<SproutboatConfig, "main">, directory: string): void {
+  const classes = Object.entries(config.durable_objects ?? {});
+  if (classes.length === 0) return;
+  const entry = resolve(directory, config.main);
+  if (!existsSync(entry)) return;
+  const exported = exportedNames(readFileSync(entry, "utf8"));
+  if (exported === null) return;
+  for (const [binding, className] of classes)
+    if (!exported.has(className))
+      throw new CloudError(
+        `durable_objects ${binding} names the class "${className}", which ${config.main} does not export; add \`export class ${className}\` (or re-export it) so the Cloud can run it`,
+      );
+}
+
+/** The plan as lines, for `deploy` and `--dry-run`: what each binding becomes on the Cloud. */
+export function describeCloudBindings(plan: CloudBindings): string[] {
+  const lines: string[] = [];
+  for (const b of plan.bindings) {
+    const target =
+      b.kind === "do"
+        ? `class ${String(b.config.class_name)}`
+        : b.kind === "ratelimit"
+          ? `${String(b.config.limit)} per ${String(b.config.period)} s`
+          : b.resource_id !== null
+            ? `-> ${b.resource_id}`
+            : "";
+    lines.push(`${b.kind.padEnd(9)} ${b.name}${target ? `  ${target}` : ""}`);
+  }
+  for (const c of plan.queue_consumers)
+    lines.push(
+      `consumer  ${c.queue}  batch ${c.max_batch_size} / ${c.max_batch_timeout_ms} ms, ${c.max_retries} retries${c.dead_letter_queue ? `, dead letters to ${c.dead_letter_queue}` : ""}`,
+    );
+  for (const cron of plan.crons) lines.push(`cron      ${cron}`);
+  return lines;
+}

package/src/cloud-deploy.ts

@@ -7,6 +7,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { readAssetRules, walkAssets, type AssetManifest } from "./assets";
 import type { SproutboatConfig } from "./config";
+import { MAX_BINDINGS, type CloudBindings, type RecordBinding, type RecordQueueConsumer } from "./cloud-bindings";
 import { authHeaders, CloudError, explainApiFailure, parseBody, type CloudIo } from "./cloud";
 import { isSafeInteger, isString, jsonObject, type JsonObject, type JsonValue } from "./json";
 import { dim, ok } from "./style";
@@ -87,6 +88,8 @@ export type ServiceWiring = { bindings: ServiceBindingEntry[]; services: Record<
 export type SpecExtras = {
   /** Service bindings from sproutboat.jsonc (`services`), resolved against the team's Cloud apps before anything is written. */
   services?: ServiceRef[];
+  /** Every other binding in sproutboat.jsonc, mapped by `mapCloudBindings`: sent as `bindings`, `crons` and `queue_consumers`. */
+  cloudBindings?: CloudBindings;
   compatibilityDate?: string;
   /**
    * Merged into the app's secrets, never replacing the set. A module deploy sends them as `secrets_patch.set` in its PUT;
@@ -139,11 +142,15 @@ function applyExtras(
   spec: AppSpec | BuildSpec,
   wiring: ServiceWiring | undefined,
   secrets: Record<string, string> | undefined,
+  mapped: CloudBindings | undefined,
 ) {
-  if (wiring) {
-    spec.bindings = wiring.bindings;
-    spec.services = wiring.services;
-  }
+  const bindings: (RecordBinding | ServiceBindingEntry)[] = [...(mapped?.bindings ?? []), ...(wiring?.bindings ?? [])];
+  if (bindings.length > MAX_BINDINGS)
+    throw new CloudError(`the app has ${bindings.length} bindings; the Cloud takes at most ${MAX_BINDINGS}`);
+  if (bindings.length > 0) spec.bindings = bindings;
+  if (wiring) spec.services = wiring.services;
+  if (mapped && mapped.crons.length > 0) spec.crons = mapped.crons;
+  if (mapped && mapped.queue_consumers.length > 0) spec.queue_consumers = mapped.queue_consumers;
   if (secrets && Object.keys(secrets).length > 0) spec.secrets_patch = { set: secrets };
 }
 
@@ -169,11 +176,14 @@ export type CloudDeployResult = {
 };
 
 type SpecAdditions = {
-  bindings?: ServiceBindingEntry[];
+  bindings?: (RecordBinding | ServiceBindingEntry)[];
   services?: Record<string, string>;
+  crons?: string[];
+  queue_consumers?: RecordQueueConsumer[];
   secrets_patch?: { set: Record<string, string> };
 };
-type AppSpec = { module: { sha256: string }; hosts: string[]; assets_manifest_ref?: string } & SpecAdditions;
+type HostsField = { hosts_patch: { add: string[] } } | { hosts: string[] };
+type AppSpec = { module: { sha256: string }; assets_manifest_ref?: string } & HostsField & SpecAdditions;
 type Call = { method: string; path: string; body?: BodyInit; json?: object; ok?: number[] };
 type CallResult = { status: number; text: string; body?: JsonObject; headers: Headers };
 type CallFn = (c: Call) => Promise<CallResult>;
@@ -201,14 +211,41 @@ export function makeCall(plan: CloudCredentials): CallFn {
   };
 }
 
-/** What the app holds now: tells a first deploy from an update, and keeps its assets when this deploy has none. */
+/**
+ * Send an app spec that adds the deploy's own hosts (the `<project>.<team>.sproutboat.app` name) to the app's routes and
+ * removes none. `hosts` on the Cloud is the whole list, so sending only the default host would unroute every custom domain an
+ * operator added; `hosts_patch` leaves the others alone, as `wrangler deploy` leaves dashboard routes when the config declares
+ * none. A Cloud that predates `hosts_patch` refuses the key by name; then the live routes (read at the start of this deploy)
+ * are merged here and sent as `hosts`.
+ */
+async function sendWithHosts(
+  plan: CloudCredentials,
+  call: CallFn,
+  wanted: string[],
+  live: string[],
+  io: CloudIo,
+  request: (hosts: HostsField) => Call,
+): Promise<CallResult> {
+  const first = request({ hosts_patch: { add: wanted } });
+  const answer = await call({ ...first, ok: [...(first.ok ?? []), 400] });
+  if (answer.status !== 400) return answer;
+  const body = answer.body;
+  if (body?.path !== "hosts_patch" || !String(body.error).startsWith("unknown key"))
+    throw new CloudError(explainApiFailure(400, answer.text, plan.tokenFromEnv));
+  io.log(dim("  hosts   this Cloud has no hosts_patch yet; sending its current routes back with this deploy's"));
+  return call(request({ hosts: [...live, ...wanted.filter((host) => !live.includes(host))] }));
+}
+
+/** What the app holds now: tells a first deploy from an update, keeps its assets when this deploy has none, and lists its routes. */
 async function resolveAssets(
   call: CallFn,
   plan: { project: string; assets?: AssetBundle },
   io: CloudIo,
-): Promise<{ created: boolean; assetsRef: string | undefined }> {
+): Promise<{ created: boolean; assetsRef: string | undefined; hosts: string[] }> {
   const current = await call({ method: "GET", path: `/v1/apps/${plan.project}`, ok: [404] });
   const created = current.status === 404;
+  const live = jsonObject(current.body?.spec ?? null)?.hosts;
+  const hosts = Array.isArray(live) ? live.filter(isString) : [];
   let assetsRef: string | undefined;
   if (plan.assets) {
     await pushAssets(call, plan.assets, io);
@@ -221,7 +258,7 @@ async function resolveAssets(
       io.log(`  assets  keeping the current ${ref.slice(0, 19)}`);
     }
   }
-  return { created, assetsRef };
+  return { created, assetsRef, hosts };
 }
 
 /** Wait for a host to apply `generation`; false at the deadline. */
@@ -255,17 +292,19 @@ export async function deployToCloud(plan: CloudDeployPlan, io: CloudIo): Promise
   const call = makeCall(plan);
   checkServiceBindings(plan.project, plan.services ?? [], plan.compatibilityDate);
   const wiring = await resolveServiceBindings(call, plan.project, plan.services ?? []);
-  const { created, assetsRef } = await resolveAssets(call, plan, io);
+  const { created, assetsRef, hosts: liveHosts } = await resolveAssets(call, plan, io);
 
   const bytes = new Uint8Array(readFileSync(plan.modulePath));
   const sha = createHash("sha256").update(bytes).digest("hex");
   io.log(`  module  ${sha.slice(0, 12)} (${(bytes.byteLength / 1024).toFixed(0)} KiB)`);
   await call({ method: "PUT", path: `/v1/modules/${sha}`, body: bytes });
 
-  const spec: AppSpec = { module: { sha256: sha }, hosts: plan.hosts };
-  if (assetsRef !== undefined) spec.assets_manifest_ref = assetsRef;
-  applyExtras(spec, wiring, plan.secrets);
-  const put = await call({ method: "PUT", path: `/v1/apps/${plan.project}`, json: spec });
+  const put = await sendWithHosts(plan, call, plan.hosts, liveHosts, io, (hosts) => {
+    const spec: AppSpec = { module: { sha256: sha }, ...hosts };
+    if (assetsRef !== undefined) spec.assets_manifest_ref = assetsRef;
+    applyExtras(spec, wiring, plan.secrets, plan.cloudBindings);
+    return { method: "PUT", path: `/v1/apps/${plan.project}`, json: spec };
+  });
   const generation = put.body?.record_generation;
   if (!isSafeInteger(generation)) throw new CloudError("the Cloud's reply carried no record generation");
   const url = plan.hosts[0] === undefined ? undefined : `https://${plan.hosts[0]}`;
@@ -352,7 +391,7 @@ export const SOURCE_MAX_BYTES = 8 * 1024 * 1024;
 /** Ctrl-C while the build runs: the build was asked to cancel (exit 130). */
 export class Interrupted extends CloudError {}
 
-type BuildSpec = { hosts: string[]; assets_manifest_ref?: string } & SpecAdditions;
+type BuildSpec = { assets_manifest_ref?: string } & HostsField & SpecAdditions;
 type BuildCli = { version: string; runtime?: string; toolchain?: string };
 
 export type BuildPlan = CloudCredentials &
@@ -674,7 +713,7 @@ export async function buildAndDeploy(plan: BuildPlan, io: CloudIo, signal?: Abor
       "--secrets-file is applied once the build is ready, so it cannot be combined with --no-wait; drop --no-wait, or set the secrets afterwards with `sproutboat secrets put`",
     );
   const wiring = await resolveServiceBindings(call, plan.project, plan.services ?? []);
-  const { created, assetsRef } = await resolveAssets(call, plan, io);
+  const { created, assetsRef, hosts: liveHosts } = await resolveAssets(call, plan, io);
 
   const missingBody = (await call({ method: "POST", path: "/v1/sources/missing", json: { sha256: [sha] } })).body
     ?.missing;
@@ -685,19 +724,22 @@ export async function buildAndDeploy(plan: BuildPlan, io: CloudIo, signal?: Abor
     await call({ method: "PUT", path: `/v1/sources/${sha}`, body: bytes });
   } else io.log(`${label}  unchanged`);
 
-  const spec: BuildSpec = { hosts: plan.hosts };
-  if (assetsRef !== undefined) spec.assets_manifest_ref = assetsRef;
-  // The build spec is stored in plaintext by the Cloud: secrets never go in it (they follow the build, below).
-  applyExtras(spec, wiring, undefined);
   const cli: BuildCli = { version: plan.cli.version };
   if (plan.cli.runtime) cli.runtime = plan.cli.runtime;
   if (plan.cli.toolchain) cli.toolchain = plan.cli.toolchain;
   const build = { v: 1, name: plan.project, cli };
-  const accepted = await call({
-    method: "POST",
-    path: `/v1/apps/${plan.project}/builds`,
-    json: { source_sha256: sha, kind: "generated", build, spec },
-    ok: [429, 503],
+  // The routes are merged when the build is applied, minutes from now, so one added meanwhile is kept too.
+  const accepted = await sendWithHosts(plan, call, plan.hosts, liveHosts, io, (hosts) => {
+    const spec: BuildSpec = { ...hosts };
+    if (assetsRef !== undefined) spec.assets_manifest_ref = assetsRef;
+    // The build spec is stored in plaintext by the Cloud: secrets never go in it (they follow the build, below).
+    applyExtras(spec, wiring, undefined, plan.cloudBindings);
+    return {
+      method: "POST",
+      path: `/v1/apps/${plan.project}/builds`,
+      json: { source_sha256: sha, kind: "generated", build, spec },
+      ok: [429, 503],
+    };
   });
   if (accepted.status === 429 || accepted.status === 503) throw new CloudError(explainBuildRefusal(accepted));
   let view = parseBuildView(accepted.body);

package/src/cloud-domains.ts

@@ -0,0 +1,55 @@
+/**
+ * `sproutboat domains` on the Sproutboat Cloud. The Cloud has no domains resource: an app's routes are the `hosts` of its
+ * spec. `list` reads them. Adding or removing a custom domain is an operator step for now (it needs a DNS record and a
+ * route on the Cloud's edge as well as the entry in the spec), so the other verbs say so instead of calling a route the
+ * Cloud does not have.
+ */
+import { CloudError } from "./cloud";
+import { makeCall, type CloudCredentials } from "./cloud-deploy";
+import { isSafeInteger, isString, jsonObject } from "./json";
+
+/** Names under this zone belong to the platform: `<project>.<team>.sproutboat.app` is every app's own route. */
+export const PLATFORM_ZONE = ".sproutboat.app";
+
+export type CloudRoute = { route: string; custom: boolean };
+export type CloudRoutes = { routes: CloudRoute[]; applied: boolean | undefined; generation: number | undefined };
+
+/** The routes of a deployed app, in the order the spec holds them, each marked custom when it is not under sproutboat.app. */
+export async function listCloudRoutes(credentials: CloudCredentials, project: string): Promise<CloudRoutes> {
+  const result = await makeCall(credentials)({ method: "GET", path: `/v1/apps/${project}`, ok: [404] });
+  if (result.status === 404)
+    throw new CloudError(`${project} is not deployed yet, so it has no routes: run \`sproutboat deploy\` first`);
+  const hosts = jsonObject(result.body?.spec ?? null)?.hosts;
+  const routes = (Array.isArray(hosts) ? hosts.filter(isString) : []).map((route) => ({
+    route,
+    custom: !route.split("/")[0]!.endsWith(PLATFORM_ZONE),
+  }));
+  const apply = jsonObject(result.body?.apply ?? null);
+  const generation = result.body?.record_generation;
+  return {
+    routes,
+    applied: apply ? apply.state === "applied" : undefined,
+    generation: isSafeInteger(generation) ? generation : undefined,
+  };
+}
+
+/** The sentence for `add`, `verify` and `delete` against a Cloud. */
+export function cloudDomainsUnsupported(sub: string, host: string): string {
+  const verb = sub === "delete" ? "removed" : "added";
+  return [
+    `custom domains on the Cloud are ${verb} by a Sproutboat operator for now, so \`domains ${sub}\` changes nothing here.`,
+    `Ask for ${host} to be routed to this app; \`sproutboat domains list\` shows what is routed, and \`sproutboat deploy\``,
+    "keeps every route it did not add itself, so a domain an operator routed stays through later deploys.",
+  ].join("\n");
+}
+
+/** The lines `domains list` prints for a Cloud app. */
+export function describeCloudRoutes(project: string, listed: CloudRoutes): string[] {
+  if (listed.routes.length === 0) return [`${project} has no routes yet`];
+  const width = Math.max(...listed.routes.map((entry) => entry.route.length));
+  const lines = listed.routes.map((entry) =>
+    `${(entry.custom ? "custom" : "built-in").padEnd(9)} ${entry.route.padEnd(width)}`.trimEnd(),
+  );
+  if (listed.applied === false) lines.push("(the newest record is not applied on a host yet)");
+  return lines;
+}

package/src/cloud-fake.ts

@@ -3,7 +3,7 @@ import { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
 
 import { parseBody } from "./cloud";
-import { isString, jsonObject, type JsonObject } from "./json";
+import { isSafeInteger, isString, jsonObject, type JsonObject, type JsonValue } from "./json";
 import { splitSql } from "./sql-split";
 
 export const FAKE_KEY = "sbk_fakekey0123456789";
@@ -14,6 +14,10 @@ export type FakeOptions = {
   role?: string;
   applyStates?: string[];
   existingAssetsRef?: string;
+  /** Hosts the app already routes (an operator added them): the app exists with these in its spec. */
+  existingHosts?: string[];
+  /** A Cloud that predates `hosts_patch`: a spec carrying it is a 400 naming the key, as the real one answered. */
+  legacyHosts?: boolean;
   appExists?: boolean;
   /** Fail every authenticated call with this status. */
   failWith?: { status: number; body: JsonObject };
@@ -58,6 +62,55 @@ const MiB = 1048576;
 export const FAKE_OWNER_SUFFIX = "0123456789ab";
 export const fakeAppId = (project: string) => `${project}_${FAKE_OWNER_SUFFIX}`;
 
+/** The Cloud's record rules for bindings, crons and queue consumers (sproutboat-cloud src/record.ts), as the first error or null. */
+function invalidRecordReason(sent: JsonObject): string | null {
+  const resourceId = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+  const kinds = ["kv", "d1", "r2", "queue", "do", "ae", "ratelimit", "assets", "secret", "service"];
+  const bindings = Array.isArray(sent.bindings) ? sent.bindings : [];
+  if (bindings.length > 64) return "bindings must be an array of at most 64 entries";
+  const names = new Set<string>();
+  for (const [i, entry] of bindings.entries()) {
+    const b = jsonObject(entry);
+    if (!b) return `bindings[${i}] must be an object`;
+    if (!isString(b.name) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(b.name)) return `invalid bindings[${i}].name`;
+    if (names.has(b.name)) return "duplicate binding name";
+    names.add(b.name);
+    if (!isString(b.kind) || !kinds.includes(b.kind)) return "unknown binding kind";
+    if (b.resource_id === null) {
+      if (["kv", "d1", "r2", "queue"].includes(b.kind)) return `${b.kind} binding needs a resource_id`;
+    } else if (!isString(b.resource_id) || !resourceId.test(b.resource_id)) return `invalid bindings[${i}].resource_id`;
+    if (!jsonObject(b.config ?? null)) return "config must be an object";
+  }
+  const crons = sent.crons ?? [];
+  if (!Array.isArray(crons) || crons.length > 16) return "crons must be an array of at most 16 entries";
+  for (const c of crons)
+    if (
+      !isString(c) ||
+      c.length > 128 ||
+      !/^[0-9A-Za-z*,/ -]+$/.test(c) ||
+      c.split(" ").length !== 5 ||
+      c.split(" ").some((f) => f === "")
+    )
+      return "invalid cron expression";
+  const consumers = sent.queue_consumers ?? [];
+  if (!Array.isArray(consumers) || consumers.length > 16)
+    return "queue_consumers must be an array of at most 16 entries";
+  const within = (v: JsonValue | undefined, lo: number, hi: number) => isSafeInteger(v) && v >= lo && v <= hi;
+  for (const entry of consumers) {
+    const q = jsonObject(entry);
+    if (!q || !isString(q.queue) || !resourceId.test(q.queue)) return "invalid queue_consumers.queue";
+    if (
+      !within(q.max_batch_size, 1, 100) ||
+      !within(q.max_batch_timeout_ms, 0, 60000) ||
+      !within(q.max_retries, 0, 100)
+    )
+      return "queue consumer settings out of range";
+    if (q.dead_letter_queue !== null && (!isString(q.dead_letter_queue) || !resourceId.test(q.dead_letter_queue)))
+      return "invalid queue_consumers.dead_letter_queue";
+  }
+  return null;
+}
+
 export function startFakeCloud(options: FakeOptions = {}) {
   const calls: { method: string; path: string; body: string; auth: string | null }[] = [];
   const modules = new Set<string>();
@@ -80,14 +133,30 @@ export function startFakeCloud(options: FakeOptions = {}) {
   const dataDenied = (need: string) =>
     Response.json({ error: "forbidden", reason: "forbidden", need }, { status: 403 });
   const permissionDenied = (need: string) => Response.json({ error: "forbidden", need }, { status: 403 });
+  /** The Cloud's rules for `hosts` and `hosts_patch` (apps.ts normalizeSpec), as an error reply or null. */
+  const checkHosts = (sent: JsonObject): Response | null => {
+    const refuse = (error: string, path: string) => Response.json({ error, reason: "invalid", path }, { status: 400 });
+    if (sent.hosts_patch === undefined) return null;
+    if (options.legacyHosts) return refuse("unknown key hosts_patch", "hosts_patch");
+    if (sent.hosts !== undefined) return refuse("hosts and hosts_patch are mutually exclusive", "hosts_patch");
+    const add = jsonObject(sent.hosts_patch)?.add;
+    for (const [i, host] of (Array.isArray(add) ? add : []).entries())
+      if (!isString(host) || !/^(?=.{1,253}$)[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(\/.*)?$/.test(host))
+        return refuse(`hosts_patch.add[${i}]: ${JSON.stringify(host)} is not a valid route`, `hosts_patch.add[${i}]`);
+    return null;
+  };
   /** The Cloud's spec rules for service bindings and secrets, then the merge. Returns an error reply or null. */
   const checkAndStore = (sent: JsonObject, project: string): Response | null => {
+    const refusedHosts = checkHosts(sent);
+    if (refusedHosts) return refusedHosts;
     const patch = jsonObject(sent.secrets_patch ?? null);
     if (sent.secrets !== undefined && patch)
       return Response.json({ error: "secrets and secrets_patch are exclusive" }, { status: 400 });
     if ((patch || sent.secrets !== undefined) && denied.has("secret:write")) return permissionDenied("secret:write");
     const bindings = Array.isArray(sent.bindings) ? sent.bindings.map((b) => jsonObject(b)) : [];
     const services = jsonObject(sent.services ?? null) ?? {};
+    const invalidRecord = invalidRecordReason(sent);
+    if (invalidRecord) return Response.json({ error: invalidRecord, reason: "invalid" }, { status: 400 });
     for (const b of bindings)
       if (b?.kind === "service" && !(String(b.name) in services))
         return Response.json({ error: `service binding ${String(b.name)} has no services entry` }, { status: 400 });
@@ -111,10 +180,22 @@ export function startFakeCloud(options: FakeOptions = {}) {
     return null;
   };
   const stored = (sent: JsonObject): JsonObject => {
-    const { secrets: _a, secrets_patch: _b, ...rest } = sent;
-    return rest;
+    const { secrets: _a, secrets_patch: _b, hosts_patch: patch, ...rest } = sent;
+    const edit = jsonObject(patch ?? null);
+    if (!edit) return rest;
+    // hosts_patch merges into the live routes (an app that does not exist yet starts with none): removals first, then additions.
+    const live = Array.isArray(spec.hosts) ? spec.hosts.filter(isString) : [];
+    const drop = new Set(Array.isArray(edit.remove) ? edit.remove : []);
+    const hosts = live.filter((host) => !drop.has(host));
+    for (const host of Array.isArray(edit.add) ? edit.add : [])
+      if (isString(host) && !hosts.includes(host)) hosts.push(host);
+    return { ...rest, hosts };
   };
   if (options.existingAssetsRef) spec.assets_manifest_ref = options.existingAssetsRef;
+  if (options.existingHosts) {
+    spec.hosts = options.existingHosts;
+    appExists = true;
+  }
 
   const databases = new Map<string, Database>((options.d1 ?? []).map((name) => [name, new Database(":memory:")]));
   const d1Requests: JsonObject[] = [];
@@ -165,7 +246,10 @@ export function startFakeCloud(options: FakeOptions = {}) {
     error: b.error,
     module_sha256: b.state === "ready" ? "f".repeat(64) : null,
     record_generation: b.generation,
-    hosts: jsonObject(b.body.spec ?? null)?.hosts ?? [],
+    hosts:
+      jsonObject(b.body.spec ?? null)?.hosts ??
+      jsonObject(jsonObject(b.body.spec ?? null)?.hosts_patch ?? null)?.add ??
+      [],
     input_hash: "1".repeat(64),
     queued_at: `2026-11-11T10:00:0${b.id.slice(-1)}.000Z`,
     finished_at:
@@ -317,6 +401,8 @@ export function startFakeCloud(options: FakeOptions = {}) {
         const buildSpec = jsonObject(sent.spec ?? null) ?? {};
         if ("secrets" in buildSpec || "secrets_patch" in buildSpec)
           return Response.json({ error: "secrets do not belong in a build spec" }, { status: 400 });
+        const refusedHosts = checkHosts(buildSpec);
+        if (refusedHosts) return refusedHosts;
         if (!sources.has(sent.source_sha256))
           return Response.json({ error: "source not uploaded", reason: "source-missing" }, { status: 409 });
         buildRequests.push(sent);