@astralarium/repo-deploy-release 0.0.0-stage → 0.2.0

package/dist/src/status.js

@@ -0,0 +1,224 @@
+/** `status`: reads the deployment's facts, then checks its invariants. */
+import { buildOf, isSlot, otherSlot, SLOT_VAR, SLOTS, varOf, } from "@astralarium/repo-deploy-info";
+import { RUNNING, WAITING } from "./cloudflare.js";
+import { buildOfRun } from "./cutovers.js";
+import { describeLease } from "./lease.js";
+import { slotBuild } from "./web.js";
+/** A fact whose read failed. */
+export class Unreadable {
+    reason;
+    constructor(reason) {
+        this.reason = reason instanceof Error ? reason.message : String(reason);
+    }
+}
+/** `promise`'s value, or `Unreadable`. */
+const fact = (promise) => promise.catch((e) => new Unreadable(e));
+/** `value` in a message: `?` when unreadable, empty when absent. */
+const show = (value) => value instanceof Unreadable ? "?" : (value ?? "");
+/** Reads every fact, in parallel. */
+export async function readFacts(s) {
+    const { webScript, slotScripts, siteOrigin } = s.target.deployment;
+    const webAt = (percentage) => fact((async () => {
+        const id = await s.cf.versionAt(webScript, percentage);
+        if (!id)
+            return undefined;
+        const version = await s.cf.version(webScript, id);
+        return { id, slot: varOf(version, SLOT_VAR), build: buildOf(version) };
+    })());
+    const siteBuild = (path) => fact((async () => {
+        const url = new URL(path, siteOrigin);
+        url.searchParams.set("status", String(Date.now()));
+        const res = await s.fetch(url, {
+            headers: { "Cache-Control": "no-cache" },
+        });
+        if (!res.ok)
+            throw new Error(`${path}: ${res.status}`);
+        const { build } = (await res.json());
+        if (typeof build !== "string")
+            throw new Error(`${path}: no build`);
+        return build;
+    })());
+    const cutovers = (statuses) => Promise.all(statuses.map((status) => s.cf.instances(s.target.flows.cutover, status))).then((ids) => ids.flat());
+    const slotFacts = async (slot) => ({
+        build: await fact(slotBuild(s, slot)),
+        crons: await fact(s.cf.crons(slotScripts[slot])),
+    });
+    const { buildPaths } = s.target;
+    const [live, next, blue, green, site, waiting, running, errored, state] = await Promise.all([
+        webAt(100),
+        webAt(0),
+        slotFacts("blue"),
+        slotFacts("green"),
+        Promise.all(buildPaths.map(siteBuild)).then((builds) => Object.fromEntries(buildPaths.map((path, i) => [path, builds[i]]))),
+        fact(cutovers(WAITING)),
+        fact(cutovers(RUNNING)),
+        fact(cutovers(["errored"]).then((ids) => ids.length)),
+        s.hasDb ? fact(readState(s)) : undefined,
+    ]);
+    // An interrupt turns every pending read unreadable; report it instead.
+    s.signal.throwIfAborted();
+    return {
+        live,
+        next,
+        slots: { blue, green },
+        site,
+        waiting,
+        running,
+        errored,
+        state,
+    };
+}
+/** The deploy state row. */
+async function readState(s) {
+    const [row] = await s.sql `
+    SELECT live_build, update_at, update_at <= now() AS update_due,
+      update_run, lease_holder, lease_operation::text, lease_expires_at,
+      lease_expires_at > now() AS lease_valid
+    FROM deploy.state
+  `;
+    return {
+        liveBuild: row.live_build,
+        updateAt: row.update_at,
+        updateDue: row.update_due ?? false,
+        updateRun: row.update_run,
+        lease: row.lease_holder && row.lease_operation && row.lease_expires_at
+            ? describeLease({
+                holder: row.lease_holder,
+                operation: row.lease_operation,
+                expires_at: row.lease_expires_at,
+            })
+            : null,
+        leaseValid: row.lease_valid ?? false,
+    };
+}
+/** The facts' summary lines: web versions, then slots. */
+export function summarize(f, webScript) {
+    const web = (v) => v instanceof Unreadable
+        ? "?"
+        : v
+            ? `${v.id} (slot ${v.slot ?? "?"}, build ${v.build ?? "?"})`
+            : "(none)";
+    const slot = (name) => {
+        const { build, crons } = f.slots[name];
+        return `${name} ${build instanceof Unreadable ? "?" : (build ?? "(none)")} [${crons instanceof Unreadable ? "?" : crons.join(" ")}]`;
+    };
+    return [
+        `Web ${webScript}: live ${web(f.live)}${f.next === undefined ? "" : `; next ${web(f.next)}`}`,
+        `Slots: ${SLOTS.map(slot).join("; ")}`,
+    ];
+}
+/** Checks `f`; `cli` renders a fix command; `dbUrlVar` holds the
+ *  database URL. */
+export function checkFacts(f, cli, dbUrlVar) {
+    const checks = [];
+    const add = (level, text) => checks.push({ level, text });
+    const { live } = f;
+    if (live instanceof Unreadable) {
+        add("fail", `the live web version is unreadable (${live.reason}); if the web worker was never deployed, run ${cli("init")}`);
+        return checks;
+    }
+    if (!live || !isSlot(live.slot)) {
+        add("fail", `no slotted web version is live; fix: ${cli("init")}`);
+        return checks;
+    }
+    const slot = live.slot;
+    const build = live.build ?? "";
+    const other = otherSlot(slot);
+    const held = f.slots[slot].build;
+    if (held instanceof Unreadable)
+        add("warn", `the build of the live slot (${slot}) is unreadable`);
+    else if (held === build)
+        add("ok", `the live slot (${slot}) runs the live build`);
+    else
+        add("fail", `the live slot (${slot}) runs '${held ?? ""}' but the live web version is build '${build}'; fix: ${cli("rollback")}`);
+    const site = Object.entries(f.site);
+    if (site.every(([, served]) => served === build))
+        add("ok", `the public site serves the live build on ${site.map(([path]) => path).join(", ")}`);
+    else
+        add("fail", `the public site answers ${site.map(([path, served]) => `${path} '${show(served)}'`).join(", ")}; expected '${build}'`);
+    const liveCrons = f.slots[slot].crons;
+    if (liveCrons instanceof Unreadable)
+        add("warn", `crons of ${slot} unreadable`);
+    else if (liveCrons.length)
+        add("ok", "the live slot holds the crons");
+    else
+        add("fail", `the live slot holds no crons; fix: ${cli("settle")}`);
+    const { state } = f;
+    // Waiting runs of the live build are finishing their release.
+    const liveBuild = state instanceof Unreadable ? undefined : (state?.liveBuild ?? undefined);
+    const finishing = f.waiting instanceof Unreadable || liveBuild === undefined
+        ? []
+        : f.waiting.filter((run) => buildOfRun(run) === liveBuild);
+    const handing = [
+        ...(f.running instanceof Unreadable ? [] : f.running),
+        ...finishing,
+    ];
+    // A cutover hands the crons over add-before-remove: both slots hold
+    // them from before its web switch until after its release.
+    const otherCrons = f.slots[other].crons;
+    if (!(otherCrons instanceof Unreadable) && otherCrons.length) {
+        if (handing.length)
+            add("info", `the idle slot (${other}) holds crons too (gated off) while cutover run ${handing.join(" ")} hands them over`);
+        else
+            add("warn", `the idle slot (${other}) holds crons too (gated off); fix: ${cli("settle")}`);
+    }
+    if (state === undefined)
+        add("info", `deploy state unchecked: set ${dbUrlVar}`);
+    else if (state instanceof Unreadable)
+        add("fail", `the deploy state is unreadable: ${state.reason}`);
+    else {
+        if (!state.lease)
+            add("ok", "no deploy lease held");
+        else if (state.leaseValid)
+            add("info", `leased: ${state.lease}`);
+        else
+            add("warn", `expired lease: ${state.lease} (its command died; the next command takes it over)`);
+        if (state.liveBuild === build)
+            add("ok", "the deploy state names the live build");
+        else
+            add("fail", `the deploy state names '${state.liveBuild ?? ""}' but the live web version is build '${build}'; fix: ${cli("settle")}`);
+        if (state.updateAt) {
+            const at = state.updateAt.toISOString();
+            const run = state.updateRun ?? "";
+            if (f.waiting instanceof Unreadable || f.running instanceof Unreadable)
+                add("warn", `update at ${at}, owned by run ${run}: the cutover runs are unreadable`);
+            else if ([...f.waiting, ...f.running].includes(run))
+                add("ok", `update at ${at}, owned by cutover run ${run}`);
+            else if (state.updateDue)
+                add("fail", `update at ${at} is past and its run ${run} has ended; the app stays closed to new work; fix: ${cli("settle")}`);
+            else
+                add("fail", `update at ${at} belongs to ended run ${run}; the app will still close ahead of it; fix: ${cli("cancel")}`);
+        }
+        else {
+            add("ok", "no update scheduled");
+            if (finishing.length)
+                add("info", `cutover run ${finishing.join(" ")} finishes its release: the old slot's crons clear and the change publishes; ${cli("settle")} ends it early`);
+            const stale = f.waiting instanceof Unreadable
+                ? []
+                : f.waiting.filter((run) => !finishing.includes(run));
+            if (stale.length)
+                add("warn", `cutover run ${stale.join(" ")} is waiting with no update; it will fail at its next fence; fix: ${cli("cancel")}`);
+        }
+    }
+    if (f.running instanceof Unreadable)
+        add("warn", `the cutover runs are unreadable (${f.running.reason})`);
+    else if (f.running.length)
+        add("info", `a cutover runs now: ${f.running.join(" ")}`);
+    const { next } = f;
+    if (next instanceof Unreadable)
+        add("warn", "the 0% web version is unreadable");
+    else if (next) {
+        const idle = f.slots[other].build;
+        if (next.slot === other && idle === next.build)
+            add("ok", `next build ${next.build} is ready on ${other}`);
+        else
+            add("warn", `the 0% version (${next.build ?? ""} on ${next.slot ?? "?"}) no longer matches the idle slot (${show(idle)}); fix: ${cli("stage")}`);
+    }
+    else
+        add("info", "no next build staged");
+    if (!(f.errored instanceof Unreadable) && f.errored)
+        add("info", `${f.errored} errored cutover runs on record`);
+    return checks;
+}
+/** `check` as an output line. */
+export const formatCheck = ({ level, text }) => `  ${level.toUpperCase().padEnd(6)}${text}`;

package/dist/src/steps.d.ts

@@ -0,0 +1,80 @@
+import { type CutoverParams, type Slot } from "@astralarium/repo-deploy-info";
+import { type BuildEnv } from "./app.ts";
+import type { InPlaceSession, Session, SlotSession } from "./session.ts";
+import { type Staged, type WebVersion } from "./web.ts";
+/** Deploys the deployer as a release-checked bundle (`wranglerBundle`),
+ *  keeping its secrets; once per session. Requires a clean app checkout
+ *  (`Session.requireClean`). */
+export declare function deployDeployer(s: SlotSession): Promise<void>;
+/** Throws unless every script of the target holds its secrets. */
+export declare function preflightSecrets(s: Session): Promise<void>;
+/** A deployed next build and its web version. */
+interface NextBuild {
+    build: string;
+    version: string;
+}
+/** Builds the next build with `buildEnv` (`buildEnvOf`), deploys its
+ *  release-checked worker bundle to `slot` (DO migrations included), then
+ *  uploads its web version. */
+export declare function deployNext(s: SlotSession, slot: Slot, buildEnv?: BuildEnv): Promise<NextBuild>;
+/** Builds the next build with `buildEnv` (`buildEnvOf`) for every worker
+ *  of the target, then deploys them in order; resolves to its build. A
+ *  deploy failing after another worker took the build throws naming the
+ *  split and the recovery. */
+export declare function deployWorkers(s: InPlaceSession, buildEnv?: BuildEnv): Promise<string>;
+/** Removes the app's state of builds outside `kept`
+ *  (`ReleaseApp.retireBuilds`), fenced on the held lease; an app without
+ *  the hook keeps every build's state. */
+export declare function retireBuilds(s: Session, kept: readonly string[]): Promise<void>;
+/** Names `build` the live build in the deploy state, fenced on the held
+ *  lease: clients compare their build against it. */
+export declare function recordLiveBuild(s: Session, build: string): Promise<void>;
+/** Throws unless the site answers `build` at every path of `paths`,
+ *  past caches: through a version override of `version` (`VERSION_SMOKE`),
+ *  else as deployed (`DEPLOYED_SMOKE`). */
+export declare function smokeTest(s: Session, build: string, paths: readonly string[], version?: {
+    script: string;
+    id: string;
+}): Promise<void>;
+/** Starts workflow `flow` as instance `id` with `params` and waits for
+ *  it; throws when it fails. */
+export declare function runFlow(s: SlotSession, flow: string, id: string, params: unknown): Promise<void>;
+/** `CUTOVER_TOKEN_MARGIN_MS` for an operator. */
+export declare const TOKEN_MARGIN = "6 hours";
+/** An API token the operator minted for one cutover. */
+export interface Token {
+    value: string;
+    /** Expiry (ms epoch) the prompt asked for. */
+    expiresAt: number;
+}
+/** When a token for a cutover at `at` expires: `TOKEN_MARGIN` past it. */
+export declare const tokenExpiry: (at: number) => number;
+/** Prompts for an API token valid until `expiresAt`. */
+export declare function promptToken(s: Session, expiresAt: number): Promise<Token>;
+/** Deploys the deployer, then puts `token` on it: the deploy creates a
+ *  missing deployer, which a secret upload alone would ask about. */
+export declare function installToken(s: SlotSession, token: Token): Promise<void>;
+/** Throws unless `token` outlives a cutover at `cutoverAt` by the
+ *  token-bound steps' worst case (`CUTOVER_TOKEN_BUDGET_MS`). */
+export declare function requireTokenCovers(s: Session, token: Token, cutoverAt: number): void;
+/** Publishes the deploy state to clients through the settle workflow,
+ *  which names `live`'s build live again; a failure logs. */
+export declare function publishState(s: SlotSession, live: WebVersion): Promise<void>;
+/** The versions, slots, build and time of one cutover; the target fills
+ *  the rest of its `CutoverParams`. */
+export type CutoverSpec = Omit<CutoverParams, "accountId" | "buildPaths" | "drain">;
+/** Runs the cutover workflow with `params` until its close lands or the
+ *  run ends. First, from a fresh read: ends terminable runs, withdraws an
+ *  orphaned update, runs `prepare`. Requires the deployer's token
+ *  (`installToken`). Resolves true when the run already released; throws
+ *  on an in-flight cutover or a run ending unchanged or failed. */
+export declare function triggerCutover(s: SlotSession, params: CutoverSpec, prepare?: () => Promise<void>): Promise<boolean>;
+/** Resolves `--at` and `--exact-time` at `now` (ms epoch) to the cutover
+ *  instant, printing it: intervals and `now` count from `now`. Throws on
+ *  a malformed, passed or too distant time. */
+export declare function pinCutover(at: string | undefined, exact: boolean, now?: number): number;
+/** Schedules the cutover from `live` to `next` at `at` (ms epoch; now
+ *  once passed) under `token`: throws unless the token covers it
+ *  (`requireTokenCovers`), then installs it and triggers the run. */
+export declare function scheduleCutover(s: SlotSession, { live, next }: Staged, at: number, token: Token): Promise<void>;
+export {};