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

package/dist/src/session.js

@@ -0,0 +1,275 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/** One invocation's resources against a target: the abort signal,
+ *  Cloudflare, the database, the deploy lease and a scratch dir. */
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout } from "node:timers/promises";
+import { componentDirs, mintDeployInfo, pullSiblings, requireCleanCheckouts, } from "@astralarium/repo-deploy-info/server";
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+import postgres from "postgres";
+import { wranglerConfigName } from "./app.js";
+import { provisionedTarget } from "./check.js";
+import { Cloudflare } from "./cloudflare.js";
+import { Lease } from "./lease.js";
+import { abortReason, INTERRUPT_EXIT, Interrupted, killChildren, reportFailure, run, sleep, } from "./process.js";
+import { confirm, readSecret } from "./prompt.js";
+import { databaseGap, unprovisioned } from "./provision.js";
+import { scriptsOf, } from "./target.js";
+/** Longest wait for the lease drop at disposal. */
+const RELEASE_TIMEOUT_MS = 5_000;
+/** Signals that stop a command: the first aborts the session, which then
+ *  drops the lease; the second kills children outright; the third exits
+ *  at once, leaving the lease to expire. */
+const STOP_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+/** A command function running `fn` in a session against `--env`'s
+ *  target, held up by its gaps in `needs` (`provisionedTarget`); `fn`
+ *  resolves to the exit status, void is 0. Failures log as
+ *  `deploy_release.failed`. */
+export function inSession(app, invocation, needs, fn) {
+    return (flags) => runSession(app, invocation, flags, needs, fn).catch(reportFailure);
+}
+/** `inSession` for a blue/green command: an in-place env refuses. */
+export function inSlots(app, invocation, needs, fn) {
+    return inSession(app, invocation, needs, (flags, s) => fn(flags, slotSession(s)));
+}
+/** `s` against its blue/green target; throws for an in-place env,
+ *  naming its commands. */
+export function slotSession(s) {
+    if (s.target.kind === "blue-green")
+        return s;
+    const own = [
+        "deploy",
+        "secrets",
+        ...(s.target.dbUrlVar ? ["unlock"] : []),
+        "check",
+    ];
+    const lines = own.map((command) => s.cli(command));
+    throw new ExpectedError(`${s.target.env} deploys at once (${scriptsOf(s.target).join(", ")}); its commands are ${lines.slice(0, -1).join(", ")} and ${lines.at(-1)}.`);
+}
+/** Runs `fn` in a session for `flags`, interrupts aborting it; throws what
+ *  `fn` throws. */
+async function runSession(app, invocation, flags, needs, fn) {
+    const session = new Session(app, invocation, provisionedTarget(app, invocation, flags.env, needs));
+    let interrupts = 0;
+    const onInterrupt = () => {
+        interrupts++;
+        if (interrupts === 1)
+            session.abort(new Interrupted());
+        else if (interrupts === 2) {
+            killChildren();
+            log.info("deploy_release.lease_dropping", "Dropping the deploy lease; interrupt again to exit now (the lease then holds until it expires, or {unlock})", { unlock: session.cli("unlock") });
+        }
+        else
+            process.exit(INTERRUPT_EXIT);
+    };
+    // Handlers outlive disposal, which drops the lease.
+    for (const signal of STOP_SIGNALS)
+        process.on(signal, onInterrupt);
+    try {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const owned = __addDisposableResource(env_1, session, true);
+            const status = await fn(flags, owned);
+            if (status)
+                process.exitCode = status;
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            const result_1 = __disposeResources(env_1);
+            if (result_1)
+                await result_1;
+        }
+    }
+    finally {
+        for (const signal of STOP_SIGNALS)
+            process.off(signal, onInterrupt);
+    }
+}
+/** Disposal drops the lease, closes the database and removes the scratch
+ *  dir. */
+export class Session {
+    app;
+    /** Starts each printed command line: the program and its `--app`. */
+    invocation;
+    target;
+    cf;
+    /** The deployer is up with this session's code (`deployDeployer`). */
+    deployerDeployed = false;
+    #abort = new AbortController();
+    #sql;
+    #lease;
+    #tmp;
+    constructor(app, invocation, target) {
+        this.app = app;
+        this.invocation = invocation;
+        this.target = target;
+        this.cf = new Cloudflare(this.signal, target.kind === "blue-green"
+            ? target.packages.worker
+            : target.workers[0].package, wranglerConfigName(app));
+    }
+    /** Aborts on Ctrl-C or a lost lease: children die, waits end. */
+    get signal() {
+        return this.#abort.signal;
+    }
+    /** Aborts with `reason`. */
+    abort(reason) {
+        this.#abort.abort(reason);
+    }
+    /** `command` as a runnable line for this target. */
+    cli(command) {
+        return `${this.invocation} ${command} --env ${this.target.env}`;
+    }
+    /** Runs `cmd` with `args` until it exits, aborting with the session;
+     *  resolves to its stdout when captured. */
+    run(cmd, args, options) {
+        return run(cmd, args, this.signal, options);
+    }
+    /** `fetch` aborting with the session. */
+    async fetch(input, init) {
+        try {
+            return await fetch(input, { ...init, signal: this.signal });
+        }
+        catch (e) {
+            throw this.signal.aborted ? abortReason(this.signal) : e;
+        }
+    }
+    /** Pauses `ms`, aborting with the session. */
+    sleep(ms) {
+        return sleep(ms, this.signal);
+    }
+    /** Reads a hidden line from the operator after `question`. */
+    secret(question) {
+        return readSecret(question, this.signal);
+    }
+    /** True when the operator answers yes to `question`. */
+    confirm(question) {
+        return confirm(question, this.signal);
+    }
+    /** Throws while the app checkout holds uncommitted or untracked
+     *  changes (the deployer bundles it). */
+    requireClean() {
+        const { app } = this.app.checkouts;
+        requireCleanCheckouts({ [app.name]: app.dir });
+    }
+    /** Readies the checkouts for a build: throws while any holds
+     *  uncommitted or untracked changes (builds bundle them), then
+     *  fast-forwards the `pull` siblings. */
+    ready() {
+        requireCleanCheckouts(componentDirs(this.app.checkouts));
+        pullSiblings(this.app.checkouts);
+    }
+    /** Fresh deploy info for the target: a build id and each checkout's
+     *  commit; throws on a dirty checkout. */
+    mint() {
+        return mintDeployInfo(this.target.env, componentDirs(this.app.checkouts));
+    }
+    /** Variable holding the target's database URL; throws for a target
+     *  without a database. */
+    get dbUrlVar() {
+        if (this.target.dbUrlVar)
+            return this.target.dbUrlVar;
+        throw new ExpectedError(`${this.target.env} has no database.`);
+    }
+    /** True while the target has a database and its URL is set. */
+    get hasDb() {
+        const { dbUrlVar } = this.target;
+        return dbUrlVar !== undefined && !!process.env[dbUrlVar];
+    }
+    /** The target's database; throws while its URL is unset. */
+    get sql() {
+        const url = process.env[this.dbUrlVar];
+        if (!url)
+            throw unprovisioned(this.invocation, this.target.env, [
+                databaseGap(this.target.env, this.dbUrlVar),
+            ]);
+        this.#sql ??= postgres(url, { max: 2 });
+        return this.#sql;
+    }
+    /** Takes the deploy lease for `operation`; a held lease keeps its
+     *  operation. Throws while another command holds it. */
+    async takeLease(operation) {
+        this.#lease ??= await Lease.take(this.sql, operation, {
+            onLost: (e) => this.abort(e),
+            unlock: this.cli("unlock"),
+        });
+        return this.#lease;
+    }
+    /** The held lease. */
+    get lease() {
+        if (!this.#lease)
+            throw new Error("The deploy lease is not held.");
+        return this.#lease;
+    }
+    /** A scratch dir, removed at disposal. */
+    tmpDir() {
+        this.#tmp ??= mkdtemp(join(tmpdir(), "deploy-release-"));
+        return this.#tmp;
+    }
+    async [Symbol.asyncDispose]() {
+        if (this.#lease)
+            await Promise.race([
+                this.#lease.release(),
+                setTimeout(RELEASE_TIMEOUT_MS, undefined, { ref: false }).then(() => {
+                    throw new Error(`no answer in ${RELEASE_TIMEOUT_MS / 1000}s`);
+                }),
+            ]).catch((e) => log.warn("deploy_release.lease_drop_failed", "could not drop the deploy lease (it expires within an hour, or run {unlock})", { unlock: this.cli("unlock"), exception: e }));
+        await this.#sql?.end({ timeout: 5 });
+        if (this.#tmp)
+            await rm(await this.#tmp, { recursive: true, force: true });
+    }
+}

package/dist/src/state.d.ts

@@ -0,0 +1,55 @@
+/** Deploy state (`deploy.state`) as the app's workers read and write
+ *  it: the live build and a scheduled update. One row; every write raises
+ *  its `version` under the row lock. Update leads compare on the database
+ *  clock. Workers-safe. */
+import { type Sql, type TransactionSql } from "@astralarium/repo-postgres/sql";
+/** The deploy state. */
+export interface DeployState {
+    /** Raised by every write. */
+    version: number;
+    /** The live build; null before the first release. */
+    live_build: string | null;
+    /** The scheduled update; null while none. */
+    update_at: Date | null;
+    /** The cutover run owning the update; null while none. */
+    update_run: string | null;
+    /** The database clock has reached the update's notice. */
+    noticed: boolean;
+}
+/** The deploy state from one snapshot; clients hear of the update
+ *  `noticeLeadMs` ahead of it. */
+export declare function readDeployState(sql: Sql, noticeLeadMs: number): Promise<DeployState>;
+/** The live build; null before the first release. */
+export declare function liveBuildOf(sql: Sql): Promise<string | null>;
+/** True while `run` owns the scheduled update. */
+export declare function updateOwnedBy(sql: Sql, run: string): Promise<boolean>;
+/** True while `run` owns the scheduled update and the database clock has
+ *  reached its notice, `noticeLeadMs` ahead of it. */
+export declare function updateNoticedBy(sql: Sql, run: string, noticeLeadMs: number): Promise<boolean>;
+/** True while `run` owns the scheduled update and the database clock has
+ *  reached it. */
+export declare function updateDueBy(sql: Sql, run: string): Promise<boolean>;
+/**
+ * Schedules `run`'s update at `update_at`, replacing the update; refused
+ * while another run's update is due (a cutover past its sleep). Resolves
+ * whether it landed.
+ */
+export declare function scheduleUpdate(sql: Sql, run: string, update_at: Date): Promise<boolean>;
+/**
+ * Withdraws the update, fenced: with `run`, only while no other run owns
+ * an update; null withdraws unconditionally. Resolves whether the fence
+ * held.
+ */
+export declare function withdrawUpdate(sql: Sql, run: string | null): Promise<boolean>;
+/**
+ * `withdrawUpdate` within `tx`: `withdrawn` once it withdrew `run`'s (or,
+ * with null, any) update; `none` while no update is scheduled; `fenced`
+ * while another run owns it.
+ */
+export declare function withdrawUpdateIn(tx: TransactionSql, run: string | null): Promise<"withdrawn" | "none" | "fenced">;
+/** Names `build` as live within `tx`. */
+export declare function setLiveBuild(tx: TransactionSql, build: string): Promise<void>;
+/** Names `build` as live and withdraws as `withdrawUpdate`, in one
+ *  transaction; the build lands whether the fence holds. Resolves whether
+ *  the fence held. */
+export declare function releaseBuild(sql: Sql, build: string, run: string | null): Promise<boolean>;

package/dist/src/state.js

@@ -0,0 +1,115 @@
+/** Deploy state (`deploy.state`) as the app's workers read and write
+ *  it: the live build and a scheduled update. One row; every write raises
+ *  its `version` under the row lock. Update leads compare on the database
+ *  clock. Workers-safe. */
+import { msInterval, } from "@astralarium/repo-postgres/sql";
+/** The deploy state from one snapshot; clients hear of the update
+ *  `noticeLeadMs` ahead of it. */
+export async function readDeployState(sql, noticeLeadMs) {
+    const [row] = await sql `
+    SELECT version::float8 AS version, live_build, update_at, update_run,
+      coalesce(update_at - ${msInterval(sql, noticeLeadMs)} <= clock_timestamp(), false)
+        AS noticed
+    FROM deploy.state
+  `;
+    return row;
+}
+/** The live build; null before the first release. */
+export async function liveBuildOf(sql) {
+    const [row] = await sql `
+    SELECT live_build FROM deploy.state
+  `;
+    return row.live_build;
+}
+/** True while `run` owns the scheduled update. */
+export async function updateOwnedBy(sql, run) {
+    const rows = await sql `
+    SELECT 1 FROM deploy.state WHERE update_run = ${run}
+  `;
+    return rows.length > 0;
+}
+/** True while `run` owns the scheduled update and the database clock has
+ *  reached its notice, `noticeLeadMs` ahead of it. */
+export async function updateNoticedBy(sql, run, noticeLeadMs) {
+    const rows = await sql `
+    SELECT 1 FROM deploy.state
+    WHERE update_run = ${run}
+      AND update_at - ${msInterval(sql, noticeLeadMs)} <= clock_timestamp()
+  `;
+    return rows.length > 0;
+}
+/** True while `run` owns the scheduled update and the database clock has
+ *  reached it. */
+export function updateDueBy(sql, run) {
+    return updateNoticedBy(sql, run, 0);
+}
+/**
+ * Schedules `run`'s update at `update_at`, replacing the update; refused
+ * while another run's update is due (a cutover past its sleep). Resolves
+ * whether it landed.
+ */
+export function scheduleUpdate(sql, run, update_at) {
+    return sql.begin(async (tx) => {
+        // A locking SELECT projects before its lock wait; the clock reads once
+        // the lock is held.
+        await tx `SELECT 1 FROM deploy.state FOR UPDATE`;
+        const [row] = await tx `
+      SELECT update_run IS NULL
+          OR update_run = ${run}
+          OR update_at > clock_timestamp() AS open
+      FROM deploy.state
+    `;
+        if (!row.open)
+            return false;
+        await tx `
+      UPDATE deploy.state
+      SET update_at = ${update_at}::timestamptz, update_run = ${run},
+        version = version + 1
+    `;
+        return true;
+    });
+}
+/**
+ * Withdraws the update, fenced: with `run`, only while no other run owns
+ * an update; null withdraws unconditionally. Resolves whether the fence
+ * held.
+ */
+export async function withdrawUpdate(sql, run) {
+    return (await sql.begin((tx) => withdrawUpdateIn(tx, run))) !== "fenced";
+}
+/**
+ * `withdrawUpdate` within `tx`: `withdrawn` once it withdrew `run`'s (or,
+ * with null, any) update; `none` while no update is scheduled; `fenced`
+ * while another run owns it.
+ */
+export async function withdrawUpdateIn(tx, run) {
+    const [row] = await tx `
+    SELECT update_run FROM deploy.state FOR UPDATE
+  `;
+    if (row.update_run === null)
+        return "none";
+    if (run !== null && row.update_run !== run)
+        return "fenced";
+    await tx `
+    UPDATE deploy.state
+    SET update_at = NULL, update_run = NULL, version = version + 1
+  `;
+    return "withdrawn";
+}
+/** Names `build` as live within `tx`. */
+export async function setLiveBuild(tx, build) {
+    await tx `
+    UPDATE deploy.state
+    SET live_build = ${build}, version = version + 1
+  `;
+}
+/** Names `build` as live and withdraws as `withdrawUpdate`, in one
+ *  transaction; the build lands whether the fence holds. Resolves whether
+ *  the fence held. */
+export async function releaseBuild(sql, build, run) {
+    const withdrawn = await sql.begin(async (tx) => {
+        await setLiveBuild(tx, build);
+        return withdrawUpdateIn(tx, run);
+    });
+    return withdrawn !== "fenced";
+}

package/dist/src/status.d.ts

@@ -0,0 +1,65 @@
+/** `status`: reads the deployment's facts, then checks its invariants. */
+import { type Slot } from "@astralarium/repo-deploy-info";
+import type { SlotSession } from "./session.ts";
+/** A fact whose read failed. */
+export declare class Unreadable {
+    readonly reason: string;
+    constructor(reason: unknown);
+}
+/** A fact, or why it is unreadable. */
+type Fact<T> = T | Unreadable;
+/** A web version's slot and build, as its vars name them. */
+interface WebFact {
+    id: string;
+    slot: string | undefined;
+    build: string | undefined;
+}
+/** The deploy state row. */
+interface StateFact {
+    liveBuild: string | null;
+    updateAt: Date | null;
+    /** The database clock has reached `updateAt`. */
+    updateDue: boolean;
+    updateRun: string | null;
+    /** `describeLease` of the lease; null while free. */
+    lease: string | null;
+    leaseValid: boolean;
+}
+/** What `status` checks. */
+export interface StatusFacts {
+    /** The 100% web version; undefined when none. */
+    live: Fact<WebFact | undefined>;
+    /** The 0% web version; undefined when none. */
+    next: Fact<WebFact | undefined>;
+    /** Each slot's 100% build (undefined when none) and crons. */
+    slots: Record<Slot, {
+        build: Fact<string | undefined>;
+        crons: Fact<string[]>;
+    }>;
+    /** Build the public site answers on each of the target's `buildPaths`. */
+    site: Record<string, Fact<string>>;
+    /** Cutover runs waiting for their time, and past it. */
+    waiting: Fact<string[]>;
+    running: Fact<string[]>;
+    /** Errored cutover runs on record. */
+    errored: Fact<number>;
+    /** Undefined while the database URL is unset. */
+    state: Fact<StateFact> | undefined;
+}
+/** A check's verdict: only `fail` fails `status`. */
+type Level = "ok" | "fail" | "warn" | "info";
+/** One verdict line. */
+export interface Check {
+    level: Level;
+    text: string;
+}
+/** Reads every fact, in parallel. */
+export declare function readFacts(s: SlotSession): Promise<StatusFacts>;
+/** The facts' summary lines: web versions, then slots. */
+export declare function summarize(f: StatusFacts, webScript: string): string[];
+/** Checks `f`; `cli` renders a fix command; `dbUrlVar` holds the
+ *  database URL. */
+export declare function checkFacts(f: StatusFacts, cli: (command: string) => string, dbUrlVar: string): Check[];
+/** `check` as an output line. */
+export declare const formatCheck: ({ level, text }: Check) => string;
+export {};