@coreplane/switchboard 0.0.0 → 1.18.1

package/dist/assets/src/deploy/buildStamp.ts

@@ -0,0 +1,93 @@
+// What commit a Worker script is running (docs/reference/specs/execution.md item 13).
+//
+// The bot has always known this: `npm run deploy` writes `build.json`, the
+// image COPYs it, and `/healthz` serves `build: {commit, builtAt}` — which is
+// how `deploy all`'s live gate tells "deployed" from "live". The three Worker
+// SCRIPTS (resident, memory, sandbox) had no equivalent. The resident instead
+// carried a hand-edited `const BUILD_MARKER = "perf53"` whose comment said
+// "bump on every deploy-worthy change"; a marker bumped by hand goes unbumped
+// the first busy week. That costs twice over: a deploy cannot be proven from
+// outside (its receipt has to be assembled from `wrangler versions list` plus a
+// container digest), and the test-override guard rail that expires an override
+// when the build changes (resident-repos item 49(c), `ignored:"stale-build …"`)
+// silently stops expiring anything.
+//
+// A file cannot carry the stamp into a Worker script the way it does into the
+// bot's image: it would have to be either committed (so a deploy dirties the
+// tree, which `deploy all` then refuses) or gitignored (so `tsc` and a fresh
+// clone fail on the missing import). So the deploy SUBSTITUTES it —
+// `wrangler deploy --define` (see `deploy/bin/build-stamp.mjs`) — and this
+// module is the one place that reads it.
+//
+// `--define` and not `--var`: a CLI `--var` may replace the `vars` block a
+// Worker's wrangler.jsonc declares, and the resident's `STATE_WORKER_URL` var
+// is load-bearing (the watchdog records firings through it). A bundle-time
+// substitution cannot touch bindings.
+
+/** What a Worker reports as `build` on `/healthz`. Shaped like the bot's
+ *  `BuildInfo` (`src/channels/health.ts`) so both read the same to an
+ *  operator and to `src/deploy/liveGate.ts`. */
+export interface BuildStamp {
+  commit: string;
+  builtAt?: string;
+}
+
+/** The commit of a Worker nobody stamped — a bare `wrangler deploy`, `wrangler
+ *  dev`, or a test process. Never silently absent: an operator must be able to
+ *  tell "built without a stamp" from "built at this commit". */
+export const UNKNOWN_COMMIT = "unknown";
+
+/** The environment variable a deploy with no tree to read (the published package, src/deploy/run.ts) hands
+ *  the stamp scripts the commit through — the same name as the `--define` identifier below, so the two scripts
+ *  (`deploy/bin/build-stamp.mjs`, `deploy/cloudflare/write-build.mjs`) and the runner agree by construction.
+ *  Spelled here, not imported from the scripts: the bot image carries `src/` and not `deploy/`. */
+export const BUILD_COMMIT_ENV = "SWITCHBOARD_BUILD_COMMIT";
+
+// The identifiers `deploy/bin/build-stamp.mjs` substitutes. They are declared,
+// never defined: with no `--define` they do not exist at runtime at all, which
+// is why every read below goes through `typeof` first (see injectedBuildStamp).
+declare const SWITCHBOARD_BUILD_COMMIT: string;
+declare const SWITCHBOARD_BUILT_AT: string;
+
+/** Pure: the stamp for whatever the deploy injected. A commit that is missing,
+ *  blank, or not a string becomes `unknown`, and `builtAt` is dropped rather
+ *  than guessed — a made-up build time is worse than none. */
+export function resolveBuildStamp(commit: unknown, builtAt: unknown): BuildStamp {
+  const trimmed = typeof commit === "string" ? commit.trim() : "";
+  const at = typeof builtAt === "string" ? builtAt.trim() : "";
+  return { commit: trimmed === "" ? UNKNOWN_COMMIT : trimmed, ...(at === "" ? {} : { builtAt: at }) };
+}
+
+/** The identity a stored artifact compares itself against — the commit, plus
+ *  the build's own timestamp when there is one.
+ *
+ *  Not the commit alone: two builds of the same DIRTY tree carry the same
+ *  `<sha>-dirty` commit, and a redeploy of the same clean commit is still a
+ *  later build. The resident's test overrides (`gc.ts` `effectiveLimits`,
+ *  resident-repos item 49(c)) are expired by "a different build wrote this",
+ *  so a coarser identity leaves a forgotten admin cap alive across exactly the
+ *  deploys that were meant to clear it. `builtAt` is injected once per deploy,
+ *  so every isolate of one deployed version agrees — an override set through
+ *  one isolate is still honored by its siblings.
+ *
+ *  An UN-stamped bundle (`wrangler dev`, a bare `wrangler deploy`) therefore
+ *  shares one id across all of its builds, and an override does not expire
+ *  between them. That is deliberate, not an oversight: with nothing injected
+ *  there is no value that differs per build yet is stable per deployment —
+ *  anything generated at module load would differ per ISOLATE, so overrides
+ *  would vanish between siblings of one deployment, which is the worse
+ *  failure. Stamped deploys are the case the guard rail exists for. */
+export function buildId(stamp: BuildStamp): string {
+  return stamp.builtAt === undefined ? stamp.commit : `${stamp.commit}@${stamp.builtAt}`;
+}
+
+/** The stamp this bundle was built with. Reading an undeclared identifier is a
+ *  ReferenceError, and `typeof` is the one operator that tolerates one — so it
+ *  gates both reads, and an un-stamped bundle answers `unknown` instead of
+ *  throwing inside `/healthz`. */
+export function injectedBuildStamp(): BuildStamp {
+  return resolveBuildStamp(
+    typeof SWITCHBOARD_BUILD_COMMIT === "string" ? SWITCHBOARD_BUILD_COMMIT : null,
+    typeof SWITCHBOARD_BUILT_AT === "string" ? SWITCHBOARD_BUILT_AT : null,
+  );
+}

package/dist/assets/src/deploy/liveGate.ts

@@ -0,0 +1,203 @@
+import { COLD_START_ALLOWANCE_MS, DRAIN_DEADLINE_MS } from "../core/drain.js";
+
+// "Deployed" is not "live". `wrangler deploy` uploads a Worker version and
+// starts a container rollout, but the OLD bot container keeps serving while it
+// drains in-flight runs (up to DRAIN_DEADLINE_MS) — a `deploy:all` that trusted
+// the upload printed `bot … deployed`, exited 0, and the old container was
+// still draining (docs/decisions/0015-deploy-order-deployed-is-not-live.md).
+// This module is the pure half of the live gate
+// `deploy:all` runs after the bot step: read `/healthz`, decide whether the NEW
+// container — identified by the commit baked into its image (`build.commit`,
+// src/channels/health.ts) — is the one answering, and say why not otherwise.
+// No node:* imports; the CLI does the fetching and the clock.
+
+/** What the gate needs from a `/healthz` body (src/channels/health.ts `HealthPayload`). */
+export interface HealthzBody {
+  ok?: unknown;
+  inFlight?: unknown;
+  draining?: unknown;
+  drainStartedAt?: unknown;
+  build?: { commit?: unknown; builtAt?: unknown } | unknown;
+  /** ISO process start — `deploy restart`'s identity (the image, hence `build.commit`, is unchanged). */
+  startedAt?: unknown;
+}
+
+/** Parse a `/healthz` response body; undefined when it is not a JSON object
+ *  (a container mid-restart answers nothing, a pre-item-8 Worker answers `ok`). */
+export function parseHealthz(text: string): HealthzBody | undefined {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+      ? (parsed as HealthzBody)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** How long the gate waits for the new container: the drain deadline the old
+ *  one may use in full, plus the same cold-start allowance the reconnect
+ *  catch-up budgets (`COLD_START_ALLOWANCE_MS`, item 7) — one number for "how
+ *  long until the replacement is up", so the gate cannot time out a container
+ *  the catch-up still expects to arrive. */
+export const LIVE_GATE_DEADLINE_MS = DRAIN_DEADLINE_MS + COLD_START_ALLOWANCE_MS;
+/** `/healthz` poll interval while waiting to go live. */
+export const LIVE_GATE_POLL_MS = 15_000;
+
+/** One poll's verdict: `live` carrying the identity that proved it, or the
+ *  reason an operator would want to read — `waiting` until the deadline,
+ *  `timeout` after it (the CLI exits non-zero: never report success when not live). */
+export type ReadyDecision<Identity> =
+  ({ kind: "live" } & Identity) | { kind: "waiting"; reason: string } | { kind: "timeout"; reason: string };
+
+export type LiveDecision = ReadyDecision<{ commit: string }>;
+export type RestartDecision = ReadyDecision<{ startedAt: string }>;
+
+function servedCommit(body: HealthzBody): string | undefined {
+  const b = body.build;
+  if (typeof b !== "object" || b === null) return undefined;
+  const c = (b as { commit?: unknown }).commit;
+  return typeof c === "string" && c !== "" ? c : undefined;
+}
+
+/** The part of a live decision every gate shares: a non-JSON body is never
+ *  live; a JSON body is judged by `identify` — the identity that proves the NEW
+ *  container is answering, or the reason it is not. A draining body is judged
+ *  the same way (run-history item 39: a container that already serves the
+ *  deployed identity IS live, whatever is rolling it next); when the identity
+ *  is the old one, the reason names the drain — the more useful fact — unless
+ *  `identify` already judged the same identity draining (`sameIdentity`: a
+ *  same-commit rollout, decided by `startedAt`) and said why. Past
+ *  `deadlineMs` the reason becomes a timeout. */
+function decideReady<Identity>(
+  body: HealthzBody | undefined,
+  elapsedMs: number,
+  deadlineMs: number,
+  identify: (
+    body: HealthzBody,
+  ) => { live: true; identity: Identity } | { live: false; reason: string; sameIdentity?: true },
+): ReadyDecision<Identity> {
+  let reason: string;
+  if (!body) {
+    reason = "/healthz not answering with JSON (container restarting, or unreachable)";
+  } else {
+    const verdict = identify(body);
+    if (verdict.live) return { kind: "live", ...verdict.identity };
+    if (body.draining === true && !verdict.sameIdentity) {
+      const n = typeof body.inFlight === "number" ? body.inFlight : "?";
+      const since = typeof body.drainStartedAt === "string" ? ` since ${body.drainStartedAt}` : "";
+      reason = `old container still draining — ${n} run(s) in flight${since}`;
+    } else reason = verdict.reason;
+  }
+  return elapsedMs >= deadlineMs ? { kind: "timeout", reason } : { kind: "waiting", reason };
+}
+
+/** Two commit identities name the same commit when one is a prefix of the other
+ *  (≥7 chars) — `git rev-parse HEAD` vs. a short form; a `-dirty` suffix never matches. */
+export function sameCommit(a: string, b: string): boolean {
+  const x = a.trim();
+  const y = b.trim();
+  if (x.length < 7 || y.length < 7) return false;
+  if (x.endsWith("-dirty") || y.endsWith("-dirty")) return false;
+  return x.startsWith(y) || y.startsWith(x);
+}
+
+/**
+ * The decision for one poll. `live` only when the body is JSON and carries the
+ * expected commit — and, when that container is DRAINING, only if it is provably
+ * the new one: a rollout of the SAME commit (a Worker recovered with
+ * `--only bot`, a forced `all` with no code change) drains an old container
+ * that serves the deployed commit too, so the commit alone would call it live the
+ * moment SIGTERM landed. The runner reads `startedAt` before the upload
+ * (`opts.previousStartedAt`) and a draining same-commit container counts only
+ * with a later one; without a pre-upload reading, a draining same-commit
+ * container waits. Everything else is `waiting` with the reason an operator
+ * would want to read — until `elapsedMs` reaches `deadlineMs`, when the same
+ * reason becomes a `timeout` (the CLI exits non-zero: never report success when
+ * not live).
+ */
+export function decideLive(
+  body: HealthzBody | undefined,
+  expectedCommit: string,
+  elapsedMs: number,
+  deadlineMs: number = LIVE_GATE_DEADLINE_MS,
+  opts: { previousStartedAt?: string } = {},
+): LiveDecision {
+  return decideReady(body, elapsedMs, deadlineMs, (b) => {
+    const commit = servedCommit(b);
+    if (!commit)
+      return {
+        live: false,
+        reason: "/healthz carries no build identity — a container that predates the live gate is answering",
+      };
+    if (commit === "unknown")
+      return { live: false, reason: 'serving a build with commit "unknown" (image built without build.json)' };
+    if (!sameCommit(commit, expectedCommit))
+      return {
+        live: false,
+        reason: `serving commit ${commit.slice(0, 7)}, expected ${expectedCommit.slice(0, 7)} (old container still up)`,
+      };
+    if (b.draining === true) {
+      const started = servedStartedAt(b);
+      const newer =
+        started !== undefined &&
+        opts.previousStartedAt !== undefined &&
+        Date.parse(started) > Date.parse(opts.previousStartedAt);
+      if (!newer)
+        return {
+          live: false,
+          sameIdentity: true,
+          reason: `the deployed commit answers but is draining${started ? ` (started ${started})` : ""} — a same-commit rollout replaces it; waiting for the new container`,
+        };
+    }
+    return { live: true, identity: { commit } };
+  });
+}
+
+/** A parseable ISO `startedAt` from a body, else undefined. */
+export function servedStartedAt(body: HealthzBody): string | undefined {
+  const s = body.startedAt;
+  return typeof s === "string" && Number.isFinite(Date.parse(s)) ? s : undefined;
+}
+
+/**
+ * The live decision after `deploy restart`: the image is unchanged, so the
+ * restarted container is recognised by a `startedAt` LATER than
+ * `previousStartedAt` (what `/healthz` said before the restart was requested).
+ * With no previous value (the old container predated `startedAt`), any
+ * non-draining container that reports one counts. Same waiting/timeout
+ * vocabulary as `decideLive`.
+ */
+export function decideRestarted(
+  body: HealthzBody | undefined,
+  previousStartedAt: string | undefined,
+  elapsedMs: number,
+  deadlineMs: number = LIVE_GATE_DEADLINE_MS,
+): RestartDecision {
+  return decideReady(body, elapsedMs, deadlineMs, (b) => {
+    const startedAt = servedStartedAt(b);
+    if (!startedAt)
+      return {
+        live: false,
+        reason: "/healthz carries no startedAt — a container that predates `deploy restart` is answering",
+      };
+    if (previousStartedAt !== undefined && Date.parse(startedAt) <= Date.parse(previousStartedAt))
+      return { live: false, reason: `old container still answering (started ${startedAt})` };
+    return { live: true, identity: { startedAt } };
+  });
+}
+
+/** The line printed on every preflight retry, so a long wait is never silent.
+ *  `tag` names the command waiting (`deploy:all`, `deploy:restart`). */
+export function heartbeatLine(
+  step: string,
+  body: HealthzBody | undefined,
+  elapsedMs: number,
+  waitMaxMs: number,
+  tag = "deploy:all",
+): string {
+  const waited = `waited ${Math.floor(elapsedMs / 60_000)}m of ${Math.round(waitMaxMs / 60_000)}m`;
+  if (!body) return `[${tag}] ${step}: still waiting — /healthz not answering, ${waited}`;
+  const n = typeof body.inFlight === "number" ? body.inFlight : "?";
+  return `[${tag}] ${step}: still waiting — ${n} run(s) in flight (draining: ${body.draining === true ? "yes" : "no"}), ${waited}`;
+}

package/dist/assets/src/deploy/profile.ts

@@ -0,0 +1,162 @@
+// The deployment profile: everything about WHERE an installation runs that the
+// code must not know. Cloudflare account, the zone the Workers sit under, each
+// Worker's script name and hostname, where the runtime config comes from, and
+// where secrets come from. The product is installed, not forked: this file is
+// the operator's, the code reads it, and nothing under src/ or deploy/ names
+// an account or a hostname of its own.
+//
+// Two files: `deploy/profile.json` (an installation's own; today the
+// repository's own production values, gitignored once they move to the
+// infrastructure repo) and `deploy/profile.example.json` (checked in, the
+// shape with placeholders). `deploy plan` falls back to the example so the
+// plan can be read anywhere — CI on a pull request, a fresh clone — but the
+// plan says so, and `deploy all` refuses a plan computed from the example: a
+// placeholder account is not a place to deploy to.
+//
+// Pure: parsing, validation, and the URLs derived from the profile. Reading
+// the file is the runner's job (src/deploy/run.ts).
+
+import { z } from "zod";
+
+/** The Workers an installation may run, in deploy order. The project's docs
+ *  site (deploy/cloudflare-docs/) is not one of them: it is the project's
+ *  website, deployed by the project's own CI from project.json's facts, never
+ *  a copy an installation runs (src/deploy/wranglerTemplate.ts `siteView`). */
+export const WORKER_KINDS = ["memory", "bot", "resident", "sandbox"] as const;
+export type WorkerKind = (typeof WORKER_KINDS)[number];
+
+export const PROFILE_PATH = "deploy/profile.json";
+export const PROFILE_EXAMPLE_PATH = "deploy/profile.example.json";
+/** Overrides the profile's location — a second installation's profile, a test fixture. */
+export const PROFILE_ENV = "SWITCHBOARD_DEPLOY_PROFILE";
+
+const hostname = z
+  .string()
+  .regex(
+    /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/,
+    "a bare DNS hostname, no scheme, no path",
+  );
+
+const endpoint = z.object({
+  /** The Cloudflare Worker script name (what `wrangler deployments list` shows). */
+  script: z.string().regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, "a Worker script name: lowercase, digits, hyphens"),
+  /** The hostname the Worker's custom domain route serves. */
+  hostname,
+  /** The zone that hostname lives in, when it is not the profile's `zone` — one
+   *  Worker on a second domain the account also owns. Must be a zone in the
+   *  same account. */
+  zone: hostname.optional(),
+});
+
+/** `path` | `github://owner/repo/path@ref` | `op://Vault/Item/field` — parsed by src/deploy/configSource.ts. */
+const source = z.string().min(1);
+
+/** Where a Worker's container image comes from (src/deploy/images.ts): `build` —
+ *  each Worker's `image` is its Dockerfile and wrangler builds it at deploy time
+ *  (a checkout; this project's own production); `registry` — the release's
+ *  published images, copied into the account registry by `deploy all` (or
+ *  `deploy images` ahead of it) and referenced as
+ *  `registry.cloudflare.com/<account>/<name>:<version>`. */
+export const IMAGE_MODES = ["build", "registry"] as const;
+export type ImageMode = (typeof IMAGE_MODES)[number];
+
+export const profileSchema = z.object({
+  /** The Cloudflare account every Worker deploys to (32 hex characters). */
+  account: z.string().regex(/^[0-9a-f]{32}$/, "a Cloudflare account id: 32 hex characters"),
+  /** The zone the hostnames live under; every hostname must be in it unless its
+   *  Worker names its own `zone`. */
+  zone: hostname,
+  /** The Workers this installation runs. The bot is the one every installation
+   *  has; the state Worker (memory), the resident and the sandbox are optional —
+   *  a profile without one has no step for it (`deploy plan` iterates what is
+   *  here) and no URL derived for it. */
+  workers: z.object({
+    memory: endpoint.optional(),
+    bot: endpoint,
+    resident: endpoint.optional(),
+    sandbox: endpoint.optional(),
+  }),
+  /** Where the bot's runtime config comes from at deploy time; `deploy all`
+   *  materializes it into the image's build context. */
+  configSource: source,
+  /** Where `secrets put` reads values from: a directory of `<NAME>` files, or
+   *  `op://Vault/Item` with the secret's name as the field. Optional: the
+   *  secrets tooling has its own default directory. */
+  secretsSource: source.optional(),
+  /** How the bot, resident and sandbox images reach wrangler (`IMAGE_MODES`).
+   *  Absent means `build` — the checkout deploys what it builds. */
+  images: z.enum(IMAGE_MODES).default("build"),
+  /** The Cloudflare Access application in front of the bot's dashboards, when
+   *  there is one: the team domain the JWT is issued by and the app's AUD. */
+  access: z.object({ teamDomain: hostname, aud: z.string().regex(/^[0-9a-f]{64}$/) }).optional(),
+});
+
+export type DeploymentProfile = z.infer<typeof profileSchema>;
+
+/** Pure: a parsed, validated profile, or the problems that make it unusable —
+ *  each naming the field, never the value. A hostname outside the zone is a
+ *  problem: the custom-domain route would be for a zone the account does not own. */
+export function parseProfile(
+  raw: unknown,
+): { ok: true; profile: DeploymentProfile } | { ok: false; problems: string[] } {
+  const parsed = profileSchema.safeParse(raw);
+  if (!parsed.success) {
+    return { ok: false, problems: parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`) };
+  }
+  const p = parsed.data;
+  const problems: string[] = [];
+  for (const [kind, ep] of Object.entries(p.workers)) {
+    if (!ep) continue;
+    const zone = ep.zone ?? p.zone;
+    if (ep.hostname !== zone && !ep.hostname.endsWith(`.${zone}`))
+      problems.push(`workers.${kind}.hostname: not under zone ${zone}`);
+  }
+  const scripts = Object.values(p.workers)
+    .filter((e): e is z.infer<typeof endpoint> => !!e)
+    .map((e) => e.script);
+  if (new Set(scripts).size !== scripts.length) problems.push("workers: two Workers share a script name");
+  return problems.length > 0 ? { ok: false, problems } : { ok: true, profile: p };
+}
+
+/** Where the profile came from — `deploy all` refuses the example. */
+export type ProfileOrigin = "profile" | "example";
+
+export interface LoadedProfile {
+  profile: DeploymentProfile;
+  origin: ProfileOrigin;
+  /** The path that was read, repo-relative or as the env var gave it. */
+  path: string;
+}
+
+/** Pure: the URLs the tooling derives — never stored twice, never typed by hand.
+ *  A Worker the profile does not have has no URL (`undefined`); the bot's are
+ *  always there, the bot being the one required Worker. */
+export function profileUrls(p: DeploymentProfile) {
+  const origin = (kind: WorkerKind): string | undefined => {
+    const worker = p.workers[kind];
+    return worker ? `https://${worker.hostname}` : undefined;
+  };
+  const bot = `https://${p.workers.bot.hostname}`;
+  return {
+    /** A Worker's origin — what its deploy preflight is pointed at; undefined when the profile lacks it. */
+    baseUrl: origin,
+    /** `GET /healthz` of a Worker; undefined when the profile lacks it. */
+    healthUrl: (kind: WorkerKind): string | undefined => {
+      const o = origin(kind);
+      return o === undefined ? undefined : `${o}/healthz`;
+    },
+    /** The bot's public origin — live-view links, the dashboards. */
+    publicBaseUrl: bot,
+    /** The state Worker other Workers record firings on and the bot reads its config from; undefined without one. */
+    stateWorkerUrl: origin("memory"),
+    /** The bot Worker's restart route (`deploy restart`). */
+    botAdminRestartUrl: `${bot}/admin/restart`,
+  };
+}
+
+/** Pure: is this the example profile? The example's account is the one
+ *  placeholder that can never be a real Cloudflare account. */
+export const EXAMPLE_ACCOUNT = "00000000000000000000000000000000";
+export function isExampleProfile(p: DeploymentProfile): boolean {
+  return p.account === EXAMPLE_ACCOUNT;
+}