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

package/dist/src/steps.js

@@ -0,0 +1,389 @@
+/** Steps the commands share: preflights, builds, workflow runs and the
+ *  cutover schedule. */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { BUILD_VAR, CUTOVER_TOKEN_BUDGET_MS, CUTOVER_TOKEN_MARGIN_MS, SLOT_VAR, } from "@astralarium/repo-deploy-info";
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+import { buildEnvOf } from "./app.js";
+import { requireReleaseBundle, workerBundleArgs } from "./bundle.js";
+import { epoch, } from "./cloudflare.js";
+import { describeCutover, parseCutoverSpec, resolveCutover, } from "./cutover-at.js";
+import { cutoverRunId, terminateCutovers, withdrawOrphan } from "./cutovers.js";
+import { writeDeployer } from "./deployer.js";
+import { abortReason } from "./process.js";
+import { setLiveBuild, updateOwnedBy } from "./state.js";
+import { secretsByScript } from "./target.js";
+import { uploadedVersionId } from "./web.js";
+import { ownWorkspaceRoot } from "./workspace.js";
+/** Between workflow status polls. */
+const FLOW_POLL_MS = 5_000;
+/** Max wait for a workflow run. */
+const FLOW_TIMEOUT_MS = 30 * 60_000;
+/** Consecutive unreadable statuses before giving up on a run. */
+const FLOW_UNREADABLE_LIMIT = 3;
+/** Runs wrangler on the target's generated deployer (`writeDeployer`),
+ *  from the slotted worker's package. */
+async function deployerWrangler(s, args, options = {}) {
+    const config = await writeDeployer(join(await s.tmpDir(), "deployer"), s.target);
+    await s.cf.wrangler(s.target.packages.worker, await args(config), {
+        ...options,
+        config,
+    });
+}
+/** Deploys the deployer as a release-checked bundle (`wranglerBundle`),
+ *  keeping its secrets; once per session. Requires a clean app checkout
+ *  (`Session.requireClean`). */
+export async function deployDeployer(s) {
+    if (s.deployerDeployed)
+        return;
+    await deployerWrangler(s, async (config) => [
+        "deploy",
+        ...(await wranglerBundle(s, s.target.packages.worker, {}, { config })),
+    ]);
+    s.deployerDeployed = true;
+}
+/** Throws unless every script of the target holds its secrets. */
+export async function preflightSecrets(s) {
+    for (const [script, keys] of secretsByScript(s.target)) {
+        const held = new Set(await s.cf.secretNames(script));
+        const missing = keys.filter((key) => !held.has(key));
+        if (missing.length)
+            throw new ExpectedError(`${script} lacks ${missing.join(", ")}. Run ${s.cli("secrets")} before deploying.`);
+    }
+}
+/** Builds workspace package `pkg` for the target's env as `build` says,
+ *  with `vars` in its env; resolves to the args naming the build to
+ *  `wrangler deploy` / `versions upload`, after the subcommand. */
+async function buildWorker(s, pkg, build, vars) {
+    if (build === "wrangler")
+        return wranglerBundle(s, pkg, vars);
+    await s.run("pnpm", ["--filter", pkg, "build"], {
+        cwd: ownWorkspaceRoot(),
+        env: {
+            ...vars,
+            // `vite build` compiles `import.meta.env.DEV` code out under production.
+            NODE_ENV: "production",
+            CLOUDFLARE_ENV: s.target.env,
+            CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV: "false",
+        },
+    });
+    return ["--minify"];
+}
+/** Builds `pkg`'s release-checked worker bundle for the target's env
+ *  (`wrangler deploy --dry-run`, `requireReleaseBundle`) with `vars` in
+ *  its env, baking `vars.DEPLOY_INFO` when set; resolves to the args
+ *  uploading that bundle after the `deploy` subcommand. */
+async function wranglerBundle(s, pkg, vars = {}, { config } = {}) {
+    const { env } = s.target;
+    // One build: the checked bundle is the uploaded one.
+    const bundle = join(await s.tmpDir(), `${config ? "deployer" : pkg}-bundle`);
+    await s.cf.wrangler(pkg, workerBundleArgs(bundle, { env, deployInfo: vars.DEPLOY_INFO }), { env: vars, config });
+    await requireReleaseBundle(bundle);
+    return [join(bundle, "index.js"), "--no-bundle", "--env", env];
+}
+/** Builds the next build with `buildEnv` (`buildEnvOf`), deploys its
+ *  release-checked worker bundle to `slot` (DO migrations included), then
+ *  uploads its web version. */
+export async function deployNext(s, slot, buildEnv) {
+    const { web, worker } = s.target.packages;
+    // Minted once: both bundles carry the same DeployInfo.
+    const info = s.mint();
+    const vars = {
+        ...buildEnvOf(s.app, buildEnv),
+        DEPLOY_INFO: JSON.stringify(info),
+    };
+    const webBuild = await buildWorker(s, web, "vite", vars);
+    const workerBuild = await buildWorker(s, worker, "wrangler", vars);
+    await s.cf.wrangler(worker, [
+        "deploy",
+        ...workerBuild,
+        "--name",
+        s.target.deployment.slotScripts[slot],
+        "--tag",
+        info.build,
+        "--var",
+        `${BUILD_VAR}:${info.build}`,
+    ]);
+    const out = join(await s.tmpDir(), "versions-upload.jsonl");
+    await s.cf.wrangler(web, [
+        "versions",
+        "upload",
+        ...webBuild,
+        "--tag",
+        info.build,
+        "--var",
+        `${SLOT_VAR}:${slot}`,
+        "--var",
+        `${BUILD_VAR}:${info.build}`,
+    ], 
+    // The build's redirected config targets the env.
+    { env: { ...vars, WRANGLER_OUTPUT_FILE_PATH: out }, redirected: true });
+    return {
+        build: info.build,
+        version: uploadedVersionId(await readFile(out, "utf8")),
+    };
+}
+/** 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 async function deployWorkers(s, buildEnv) {
+    const info = s.mint();
+    const vars = {
+        ...buildEnvOf(s.app, buildEnv),
+        DEPLOY_INFO: JSON.stringify(info),
+    };
+    // Every build first: a failing build leaves the site untouched.
+    const builds = [];
+    for (const { package: pkg, build } of s.target.workers)
+        builds.push(await buildWorker(s, pkg, build, vars));
+    const deployed = [];
+    for (const [i, worker] of s.target.workers.entries()) {
+        try {
+            await s.cf.wrangler(worker.package, [
+                "deploy",
+                ...builds[i],
+                "--tag",
+                info.build,
+                "--var",
+                `${BUILD_VAR}:${info.build}`,
+                ...Object.entries(worker.vars ?? {}).flatMap(([name, value]) => [
+                    "--var",
+                    `${name}:${value}`,
+                ]),
+            ], { env: vars, redirected: worker.build === "vite" });
+        }
+        catch (e) {
+            if (s.signal.aborted || !deployed.length)
+                throw e;
+            const pending = s.target.workers.slice(i).map((w) => w.script);
+            throw new ExpectedError(`${worker.script} failed to deploy after ${deployed.join(", ")} took build ${info.build}; ${pending.join(", ")} still ${pending.length === 1 ? "runs" : "run"} the previous build. Fix the cause, then rerun ${s.cli("deploy")}: it redeploys every worker.`, { cause: e });
+        }
+        deployed.push(worker.script);
+    }
+    return info.build;
+}
+/** 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 async function retireBuilds(s, kept) {
+    const { retireBuilds } = s.app;
+    if (!retireBuilds)
+        return;
+    await s.lease.fenced((tx) => retireBuilds(tx, kept));
+}
+/** Names `build` the live build in the deploy state, fenced on the held
+ *  lease: clients compare their build against it. */
+export async function recordLiveBuild(s, build) {
+    await s.lease.fenced((tx) => setLiveBuild(tx, build));
+}
+/** A web version override answers as soon as the upload lands. */
+const VERSION_SMOKE = { attempts: 5, retryMs: 3_000 };
+/** A deployed script: a first deploy's custom domain takes minutes to
+ *  serve (DNS, certificate). */
+const DEPLOYED_SMOKE = { attempts: 30, retryMs: 10_000 };
+/** 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 async function smokeTest(s, build, paths, version) {
+    const { siteOrigin } = s.target;
+    const headers = {
+        "Cache-Control": "no-cache",
+        ...(version && {
+            "Cloudflare-Workers-Version-Overrides": `${version.script}="${version.id}"`,
+        }),
+    };
+    /** The build `path` answers; undefined on a failed request. */
+    const servedAt = async (path) => {
+        const url = new URL(path, siteOrigin);
+        url.searchParams.set("smoke", String(Date.now()));
+        try {
+            const res = await s.fetch(url, { headers });
+            const { build: served } = (await res.json());
+            return res.ok ? served : undefined;
+        }
+        catch {
+            if (s.signal.aborted)
+                throw abortReason(s.signal);
+            return undefined;
+        }
+    };
+    const where = version ? `Web version ${version.id}` : siteOrigin;
+    const { attempts, retryMs } = version ? VERSION_SMOKE : DEPLOYED_SMOKE;
+    for (const path of paths) {
+        let served;
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            served = await servedAt(path);
+            if (served === build || attempt === attempts)
+                break;
+            log.info("deploy_release.smoke_retry", "{where} answered build {served} on {path}; retrying ({attempt}/{attempts})", { where, served: String(served), path, attempt, attempts });
+            await s.sleep(retryMs);
+        }
+        if (served !== build)
+            throw new ExpectedError(`${where} answered build '${String(served)}' on ${path}, expected '${build}' (${attempts} attempts over ${((attempts - 1) * retryMs) / 1000}s).`);
+    }
+}
+/** `wrangler` line describing instance `id` of `flow`. */
+const describeLine = (s, flow, id) => `see: pnpm --filter ${s.target.packages.worker} exec wrangler workflows instances describe ${flow} ${id}`;
+/** Polls instance `id` of `flow`: resolves to its output on completion,
+ *  undefined once `settled` holds mid-run. Throws on failure, a lasting
+ *  unreadable status, or timeout. */
+async function awaitFlow(s, flow, id, settled = () => Promise.resolve(false)) {
+    const see = describeLine(s, flow, id);
+    const deadline = Date.now() + FLOW_TIMEOUT_MS;
+    let unreadable = 0;
+    let status;
+    for (;;) {
+        let reason = "";
+        let output;
+        try {
+            ({ status, output } = await s.cf.instance(flow, id));
+        }
+        catch (e) {
+            if (s.signal.aborted)
+                throw abortReason(s.signal);
+            status = undefined;
+            reason = e instanceof Error ? e.message : String(e);
+        }
+        switch (status) {
+            case "complete":
+                return { output };
+            case "errored":
+            case "terminated":
+                throw new ExpectedError(`${flow} run ${id} ${status}; ${see}`);
+            case "queued":
+            case "running":
+            case "waiting":
+            case "paused":
+            case "waitingForPause":
+                unreadable = 0;
+                if (await settled())
+                    return undefined;
+                break;
+            default:
+                if (++unreadable >= FLOW_UNREADABLE_LIMIT)
+                    throw new ExpectedError(`${flow} run ${id}: unreadable status: ${reason || String(status)}; ${see}`);
+        }
+        if (Date.now() >= deadline)
+            throw new ExpectedError(`${flow} run ${id} still ${status ?? "unreadable"} after ${FLOW_TIMEOUT_MS / 60_000} minutes; ${see}`);
+        await s.sleep(FLOW_POLL_MS);
+    }
+}
+/** Starts workflow `flow` as instance `id` with `params` and waits for
+ *  it; throws when it fails. */
+export async function runFlow(s, flow, id, params) {
+    await s.cf.trigger(flow, id, params);
+    await awaitFlow(s, flow, id);
+}
+/** `CUTOVER_TOKEN_MARGIN_MS` for an operator. */
+export const TOKEN_MARGIN = `${CUTOVER_TOKEN_MARGIN_MS / (60 * 60_000)} hours`;
+/** When a token for a cutover at `at` expires: `TOKEN_MARGIN` past it. */
+export const tokenExpiry = (at) => at + CUTOVER_TOKEN_MARGIN_MS;
+/** Prompts for an API token valid until `expiresAt`. */
+export async function promptToken(s, expiresAt) {
+    const value = await s.secret(`API token (Workers Scripts: Edit; valid until ${new Date(expiresAt).toISOString()}): `);
+    if (!value)
+        throw new ExpectedError("No token given.");
+    return { value, expiresAt };
+}
+/** Deploys the deployer, then puts `token` on it: the deploy creates a
+ *  missing deployer, which a secret upload alone would ask about. */
+export async function installToken(s, token) {
+    await deployDeployer(s);
+    await deployerWrangler(s, () => ["secret", "bulk", "--env", s.target.env], {
+        input: JSON.stringify({ CLOUDFLARE_API_TOKEN: token.value }),
+    });
+}
+/** Throws unless `token` outlives a cutover at `cutoverAt` by the
+ *  token-bound steps' worst case (`CUTOVER_TOKEN_BUDGET_MS`). */
+export function requireTokenCovers(s, token, cutoverAt) {
+    const needed = cutoverAt + CUTOVER_TOKEN_BUDGET_MS;
+    if (needed <= token.expiresAt)
+        return;
+    throw new ExpectedError(`The token (valid until ${new Date(token.expiresAt).toISOString()}) expires before the cutover's budget (${new Date(needed).toISOString()}); the staged build stays staged: run ${s.cli("cutover")} with a fresh token.`);
+}
+/** Why a cutover run ended unchanged, per outcome. */
+const UNCHANGED = {
+    refused: "another cutover's update is due",
+    superseded: "a later cutover run took over its update",
+};
+/** Publishes the deploy state to clients through the settle workflow,
+ *  which names `live`'s build live again; a failure logs. */
+export async function publishState(s, live) {
+    await runFlow(s, s.target.flows.settle, `publish-${epoch()}`, {
+        slot: live.slot,
+        build: live.build,
+    }).catch((e) => log.warn("deploy_release.publish_failed", "the withdrawn update may still show on clients; {settle} publishes it", { settle: s.cli("settle"), exception: e }));
+}
+/** 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 async function triggerCutover(s, params, prepare = () => Promise.resolve()) {
+    const c = await terminateCutovers(s);
+    await withdrawOrphan(s, c);
+    // An in-flight owner refuses above, so any update read was an ended
+    // run's and is now withdrawn; clients drop it at the next publish.
+    const withdrew = c.state.update_run !== null;
+    const flow = s.target.flows.cutover;
+    const id = cutoverRunId(params.build);
+    try {
+        await prepare();
+        const full = {
+            accountId: await s.cf.accountId(),
+            buildPaths: s.target.buildPaths,
+            drain: s.target.flows.drain !== undefined,
+            ...params,
+        };
+        await s.cf.trigger(flow, id, full);
+    }
+    catch (e) {
+        if (withdrew)
+            await publishState(s, c.live);
+        throw e;
+    }
+    // The close landed once the deploy state names the run; an unreadable
+    // state waits for the run's status.
+    const ended = await awaitFlow(s, flow, id, () => updateOwnedBy(s.sql, id).catch(() => false));
+    if (!ended)
+        return false;
+    const { output } = ended;
+    if (output === "released")
+        return true;
+    const why = output === "refused" || output === "superseded"
+        ? `${output}: ${UNCHANGED[output]}`
+        : `unknown outcome ${JSON.stringify(output)}`;
+    throw new ExpectedError(`Cutover run ${id} ended without a change (${why}); ${s.cli("status")} shows the deployment. ${describeLine(s, flow, id)}`);
+}
+/** 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 function pinCutover(at, exact, now = Date.now()) {
+    const resolved = resolveCutover(parseCutoverSpec(at, now), now, exact);
+    log.info("deploy_release.cutover_time", "Cutover: {when}", { when: describeCutover(resolved, now) });
+    return resolved;
+}
+/** 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 async function scheduleCutover(s, { live, next }, at, token) {
+    const cutoverAt = Math.max(at, Date.now());
+    requireTokenCovers(s, token, cutoverAt);
+    await installToken(s, token);
+    const released = await triggerCutover(s, {
+        liveVersion: live.id,
+        nextVersion: next.id,
+        liveSlot: live.slot,
+        idleSlot: next.slot,
+        build: next.build,
+        cutoverAt: new Date(cutoverAt).toISOString(),
+    });
+    if (released)
+        log.info("deploy_release.released", "Released: build {build} is live", { build: next.build });
+    else
+        log.info("deploy_release.scheduled", "Scheduled: build {build} takes over {when}", {
+            build: next.build,
+            when: describeCutover(cutoverAt, Date.now()),
+        });
+}

package/dist/src/target.d.ts

@@ -0,0 +1,94 @@
+import { type Deployment } from "@astralarium/repo-deploy-info";
+import { type ReleaseApp, type SlotPackages, type SlotSecrets, type WorkerSpec } from "./app.ts";
+import { type Gap } from "./provision.ts";
+/** What every target shares. */
+interface TargetBase {
+    /** Minted into builds; wrangler's `--env` and `CLOUDFLARE_ENV`. */
+    env: string;
+    /** The public site; checked after each deploy. */
+    siteOrigin: string;
+    /** Secrets `secrets` uploads; copied from the `.tmpl` beside it. */
+    secretsFile: string;
+    /** Variable holding the database URL; absent for an env without a
+     *  database. */
+    dbUrlVar?: string;
+}
+/** The runtime a worker deploys on, from its wrangler config. */
+export interface WorkerRuntime {
+    compatibilityDate: string;
+    compatibilityFlags: readonly string[];
+}
+/** A blue/green env. */
+export interface SlotTarget extends TargetBase {
+    kind: "blue-green";
+    packages: SlotPackages;
+    /** Scripts and site: the deployer's `DEPLOYMENT` var. */
+    deployment: Deployment;
+    /** The generated deployer's script (`deployerConfig`). */
+    deployer: string;
+    /** The slotted worker's runtime; the deployer runs on it too. */
+    runtime: WorkerRuntime;
+    /** The deployer's workflows by name (`DEPLOYER_FLOWS`); `drain` with
+     *  `BlueGreenEnv.drain`. */
+    flows: {
+        cutover: string;
+        settle: string;
+        drain?: string;
+    };
+    /** Secrets the web and worker env blocks require. */
+    secrets: SlotSecrets;
+    /** Site paths answering `{ build }` from the web worker and the live
+     *  slot. */
+    buildPaths: readonly string[];
+    dbUrlVar: string;
+}
+/** A worker of an in-place env, as its wrangler config deploys it. */
+export interface ReleasedWorker extends WorkerSpec {
+    /** The deployed script. */
+    script: string;
+    /** Secrets its wrangler config requires. */
+    secrets: readonly string[];
+    /** Site path answering `{ build }` from this worker. */
+    buildPath: string;
+}
+/** An in-place env: its workers deploy at once, in order; its commands
+ *  are `deploy` and `secrets`. */
+export interface InPlaceTarget extends TargetBase {
+    kind: "in-place";
+    workers: readonly ReleasedWorker[];
+}
+/** An env's release target, by kind. */
+export type Target = SlotTarget | InPlaceTarget;
+/** A wrangler config block, the top level or an `env.<env>` block: the
+ *  keys targets read, typed. */
+export interface WranglerEnv {
+    readonly [key: string]: unknown;
+    name?: unknown;
+    vars?: Record<string, unknown>;
+    secrets?: {
+        required?: string[];
+    };
+    workflows?: {
+        binding: string;
+        name: string;
+    }[];
+    compatibility_date?: unknown;
+    compatibility_flags?: string[];
+}
+/** Workspace package `pkg`'s wrangler config path. */
+export declare const wranglerConfig: (app: ReleaseApp, pkg: string) => string;
+/** `pkg`'s `env.<env>` block as written; undefined while its config or
+ *  the block is missing. */
+export declare const readEnvBlock: (app: ReleaseApp, pkg: string, env: string) => WranglerEnv | undefined;
+/** `env`'s target as its wrangler configs declare it, and every gap in
+ *  those configs; the target is undefined while a gap leaves a piece of
+ *  it undeclared. Throws on an env outside `app.envs`. */
+export declare function resolveTarget(app: ReleaseApp, env: string): {
+    target?: Target;
+    gaps: Gap[];
+};
+/** Each script of `target` with the secrets it holds. */
+export declare function secretsByScript(target: Target): [script: string, secrets: readonly string[]][];
+/** The scripts of `target`. */
+export declare const scriptsOf: (target: Target) => string[];
+export {};