@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/dist/state/locks.d.ts

@@ -0,0 +1,105 @@
+import type { LockHolder, StateStore } from "./store.js";
+/** What a lock says holds it: the operation and a line of info, as the binary prints them when it finds the lock held. */
+export interface LockOperation {
+    operation: string;
+    info: string;
+}
+/** The lock info a run writes, in the shape the binary writes and prints when it finds a lock held. */
+export declare function lockInfo(path: string, now: string, op: LockOperation, who?: string): string;
+/** Who holds a lock, from the lock info it left: what is there of it. */
+export interface LockHolderInfo {
+    id: string;
+    who?: string;
+    operation?: string;
+    info?: string;
+    created?: string;
+}
+/** The holder a lock info names. */
+export declare function holderOf(held: LockHolder): LockHolderInfo;
+/** A lock held by another run stopped the take; nothing was pulled. */
+export declare class StateLockedError extends Error {
+    readonly root: string;
+    readonly lockLocation: string;
+    readonly holder?: LockHolderInfo | undefined;
+    constructor(root: string, lockLocation: string, holder?: LockHolderInfo | undefined);
+}
+/** What taking a lock needs of a store: a caller with a store of its own (terragucci's, which also reads versions) passes that. */
+export type LockStore = Pick<StateStore, "location" | "lockLocation" | "heldLock" | "lock" | "unlock" | "adopt">;
+/** A lock taken, on one root's state. */
+export interface HeldLock<S extends LockStore = StateStore> {
+    root: string;
+    store: S;
+    /** The lock was another run's, kept on purpose with a state it could not write, and this take took it over. */
+    adopted: boolean;
+    release: () => Promise<void>;
+}
+/**
+ * Take the lock of each state, in the order given. Releases what it took and
+ * throws StateLockedError when one is held and `adopt` does not take it over.
+ * `adopt` sees a held lock and says whether this take takes it over (a lock
+ * an earlier run of the same operation left held on purpose).
+ */
+export declare function takeLocks<S extends LockStore = StateStore>(stores: readonly {
+    root: string;
+    store: S;
+}[], now: string, op: LockOperation, adopt?: (root: string, store: S, held: LockHolder) => Promise<boolean>, who?: string): Promise<HeldLock<S>[]>;
+/**
+ * The lock of a workspace a state is read from, taken through the
+ * workspace's own API (Terraform Cloud's `actions/lock`), not a lock object
+ * beside a state. `lock` takes it with a reason the workspace shows, and
+ * returns its release; it throws when another run holds it.
+ */
+export interface SourceLock {
+    root: string;
+    /** The workspace, for messages. */
+    location: string;
+    lock(reason: string): Promise<() => Promise<void>>;
+}
+/** A source workspace's lock, taken. */
+export interface HeldSourceLock {
+    root: string;
+    location: string;
+    release: () => Promise<void>;
+}
+/** A source workspace's lock could not be taken: another run holds it, or the API refused. Nothing was read. */
+export declare class SourceLockedError extends Error {
+    readonly root: string;
+    readonly location: string;
+    readonly reason: string;
+    constructor(root: string, location: string, reason: string);
+}
+/** The reason a source workspace's lock shows: the operation and its info, as a state lock's info names them. */
+export declare const sourceLockReason: (op: LockOperation) => string;
+/**
+ * Take each source workspace's lock, in the order given, so no run writes a
+ * state while it is read. Releases what it took and throws SourceLockedError
+ * when one cannot be taken.
+ */
+export declare function takeSourceLocks(sources: readonly SourceLock[], op: LockOperation): Promise<HeldSourceLock[]>;
+export interface LocksWithSourcesInput<S extends LockStore> {
+    /** The workspaces states are read from, locked first. */
+    sources: readonly SourceLock[];
+    /** The states written, locked after the sources, in the order given. */
+    stores: readonly {
+        root: string;
+        store: S;
+    }[];
+    now: string;
+    /** What the state locks name. */
+    op: LockOperation;
+    /** What a source workspace's lock names; default `op`. A run that only reads the source says so here. */
+    sourceOp?: LockOperation;
+    adopt?: (root: string, store: S, held: LockHolder) => Promise<boolean>;
+    who?: string;
+}
+/**
+ * Every lock a run that reads from source workspaces and writes states
+ * holds: the source workspaces' first, then the states'. When any cannot be
+ * taken, every lock taken so far is released, and the error is
+ * SourceLockedError or StateLockedError.
+ */
+export declare function takeLocksWithSources<S extends LockStore = StateStore>(input: LocksWithSourcesInput<S>): Promise<{
+    sources: HeldSourceLock[];
+    locks: HeldLock<S>[];
+}>;
+//# sourceMappingURL=locks.d.ts.map

package/dist/state/locks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locks.d.ts","sourceRoot":"","sources":["../../src/state/locks.ts"],"names":[],"mappings":"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"}

package/dist/state/locks.js

@@ -0,0 +1,130 @@
+/**
+ * Taking a set of state locks in one order, each the way its backend takes
+ * it, with lock info that names the operation and the run. A lock another
+ * run holds stops the take: every lock taken so far is released, and the
+ * error names the holder from the lock info it left.
+ *
+ * A run can also hold the lock of a workspace a state is read from, which
+ * no backend block of the root names (a Terraform Cloud or Enterprise
+ * workspace a state migration moves from, terragucci#1274): the workspace's
+ * own lock, taken through its API before any state lock (`takeSourceLocks`,
+ * `takeLocksWithSources`).
+ *
+ * Lifted from terragucci's `migrate.ts` (c493e0e): `lockInfo`,
+ * `LockOperation`, `HeldLock` and `takeLocks`, and the source-workspace lock
+ * of its `takeLocks` (lines 1045 to 1056).
+ */
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+/** The lock info a run writes, in the shape the binary writes and prints when it finds a lock held. */
+export function lockInfo(path, now, op, who = `chant@${hostname()}`) {
+    return JSON.stringify({ ID: randomUUID(), Operation: op.operation, Info: op.info, Who: who, Version: "", Created: now, Path: path });
+}
+/** The holder a lock info names. */
+export function holderOf(held) {
+    let v = {};
+    try {
+        v = JSON.parse(held.info);
+    }
+    catch {
+        // Lock info that is not JSON names no one.
+    }
+    const s = (k) => (typeof v[k] === "string" && v[k] !== "" ? v[k] : undefined);
+    return { id: held.id, ...(s("Who") ? { who: s("Who") } : {}), ...(s("Operation") ? { operation: s("Operation") } : {}), ...(s("Info") ? { info: s("Info") } : {}), ...(s("Created") ? { created: s("Created") } : {}) };
+}
+/** A lock held by another run stopped the take; nothing was pulled. */
+export class StateLockedError extends Error {
+    constructor(root, lockLocation, holder) {
+        const by = holder ? [holder.who && `by ${holder.who}`, holder.operation, holder.info && `(${holder.info})`, holder.created && `since ${holder.created}`].filter(Boolean).join(" ") : "";
+        super(`${root}: its state is locked at ${lockLocation}${by ? ` ${by}` : ""}, so nothing was pulled`);
+        this.root = root;
+        this.lockLocation = lockLocation;
+        this.holder = holder;
+        this.name = "StateLockedError";
+    }
+}
+/**
+ * Take the lock of each state, in the order given. Releases what it took and
+ * throws StateLockedError when one is held and `adopt` does not take it over.
+ * `adopt` sees a held lock and says whether this take takes it over (a lock
+ * an earlier run of the same operation left held on purpose).
+ */
+export async function takeLocks(stores, now, op, adopt, who) {
+    const held = [];
+    const releaseAll = async () => {
+        for (const h of held.reverse())
+            await h.release().catch(() => { });
+    };
+    for (const { root, store } of stores) {
+        let got;
+        try {
+            got = await store.lock(lockInfo(store.location.replace(/^[a-z0-9]+:\/\//, ""), now, op, who));
+        }
+        catch (e) {
+            await releaseAll();
+            throw new Error(`${root}: the lock ${store.lockLocation} could not be taken: ${e.message}`);
+        }
+        if (got) {
+            held.push({ root, store, adopted: false, release: () => store.unlock() });
+            continue;
+        }
+        const info = await store.heldLock().catch(() => undefined);
+        if (info && adopt && (await adopt(root, store, info).catch(() => false))) {
+            store.adopt(info);
+            held.push({ root, store, adopted: true, release: () => store.unlock() });
+            continue;
+        }
+        await releaseAll();
+        throw new StateLockedError(root, store.lockLocation, info ? holderOf(info) : undefined);
+    }
+    return held;
+}
+/** A source workspace's lock could not be taken: another run holds it, or the API refused. Nothing was read. */
+export class SourceLockedError extends Error {
+    constructor(root, location, reason) {
+        super(`${root}: the lock of the workspace it is read from (${location}) could not be taken: ${reason}`);
+        this.root = root;
+        this.location = location;
+        this.reason = reason;
+        this.name = "SourceLockedError";
+    }
+}
+/** The reason a source workspace's lock shows: the operation and its info, as a state lock's info names them. */
+export const sourceLockReason = (op) => `${op.operation}: ${op.info}`;
+/**
+ * Take each source workspace's lock, in the order given, so no run writes a
+ * state while it is read. Releases what it took and throws SourceLockedError
+ * when one cannot be taken.
+ */
+export async function takeSourceLocks(sources, op) {
+    const held = [];
+    for (const s of sources) {
+        try {
+            held.push({ root: s.root, location: s.location, release: await s.lock(sourceLockReason(op)) });
+        }
+        catch (e) {
+            for (const h of held.reverse())
+                await h.release().catch(() => { });
+            throw new SourceLockedError(s.root, s.location, e.message);
+        }
+    }
+    return held;
+}
+/**
+ * Every lock a run that reads from source workspaces and writes states
+ * holds: the source workspaces' first, then the states'. When any cannot be
+ * taken, every lock taken so far is released, and the error is
+ * SourceLockedError or StateLockedError.
+ */
+export async function takeLocksWithSources(input) {
+    const sources = await takeSourceLocks(input.sources, input.sourceOp ?? input.op);
+    try {
+        const locks = await takeLocks(input.stores, input.now, input.op, input.adopt, input.who);
+        return { sources, locks };
+    }
+    catch (e) {
+        for (const h of sources.reverse())
+            await h.release().catch(() => { });
+        throw e;
+    }
+}

package/dist/state/object-store.d.ts

@@ -0,0 +1,8 @@
+/**
+ * What the state stores share: the fetch they call, their errors, and how a
+ * key goes into a URL. Since #4554 these are chant core's object-store
+ * definitions (`@intentius/chant/object-store`), so a store error thrown by
+ * a core client is the one a state caller catches.
+ */
+export { defaultFetch, encodePath, encodeStrict, StoreConflict, StoreError, xmlText, type StoreCondition, type StoreFetch } from "@intentius/chant/object-store";
+//# sourceMappingURL=object-store.d.ts.map

package/dist/state/object-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-store.d.ts","sourceRoot":"","sources":["../../src/state/object-store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/state/object-store.js

@@ -0,0 +1,7 @@
+/**
+ * What the state stores share: the fetch they call, their errors, and how a
+ * key goes into a URL. Since #4554 these are chant core's object-store
+ * definitions (`@intentius/chant/object-store`), so a store error thrown by
+ * a core client is the one a state caller catches.
+ */
+export { defaultFetch, encodePath, encodeStrict, StoreConflict, StoreError, xmlText } from "@intentius/chant/object-store";

package/dist/state/root-states.d.ts

@@ -0,0 +1,131 @@
+import { type LockableState, type StateObject, type StateRefusalKind } from "./backend.js";
+import { type BinaryExec, type StateFile } from "./exec.js";
+import { type LockOperation } from "./locks.js";
+import type { StoreFetch } from "./object-store.js";
+import { type StateStore } from "./store.js";
+/** The suffix of the object beside a root's state that holds a state a run could not write. */
+export declare const UNWRITTEN_SUFFIX = ".chant-unwritten";
+/** The suffix terragucci keeps an unwritten state under: read and removed, never written. */
+export declare const LEGACY_UNWRITTEN_SUFFIX = ".terragucci-unwritten";
+/** The operation terragucci's composed run names in its locks. */
+export declare const LEGACY_COMPOSE_OPERATION = "terragucci compose";
+/** Where a kept state goes under the job's report directory when its own backend could not take it. */
+export declare const UNWRITTEN_DIR = "unwritten";
+/** The operation a composed run's locks name. */
+export declare const COMPOSE_LOCK: LockOperation;
+/** How long to wait before each retry of a state's write: five retries, inside the lock timeout of 5 minutes. */
+export declare const DEFAULT_RETRY_DELAYS: number[];
+/** One root whose state the run holds. */
+export interface RootState {
+    root: string;
+    /** The root's directory, where the binary runs. */
+    dir: string;
+    /** The root's environment for the binary. */
+    env: NodeJS.ProcessEnv;
+    /** Where its state is; read from what `init` recorded, compared with the root's code, when absent. */
+    object?: StateObject;
+    /** `terraform.roots.<name>.backendConfig`, which the comparison with what init recorded reads (chant#4478). */
+    backendConfig?: Readonly<Record<string, string>>;
+    /** `terraform.roots.<name>.backendConfigFiles`, whose keys the same comparison reads (chant#4459). */
+    backendConfigFiles?: readonly string[];
+}
+export interface RootStatesOptions {
+    /** The roots, in the order their locks are taken. */
+    roots: RootState[];
+    /** The binary's path. */
+    binary: string;
+    exec?: BinaryExec;
+    /** The operation the locks name. Default COMPOSE_LOCK. */
+    op?: LockOperation;
+    /** Names the run in the locks it takes. */
+    runId?: string;
+    /** A directory of the job's own for the state files `state push` reads. */
+    work: string;
+    /** The job's report directory, where a kept state goes when its backend cannot take it. */
+    reportDir: string;
+    retryDelays?: number[];
+    sleep?: (ms: number) => Promise<void>;
+    fetch?: StoreFetch;
+    /** Opens a root's store; a test's fake stands in here. */
+    openStore?: (root: RootState, object: LockableState) => StateStore;
+    now?: () => string;
+    /** Who the lock info names. */
+    who?: string;
+    log?: (line: string) => void;
+}
+/** Why a root's state is not locked. */
+export interface RootRefusal {
+    root: string;
+    backend: string;
+    refused: StateRefusalKind;
+    reason: string;
+}
+/** The roots whose state chant does not lock: the take stops before any lock. */
+export declare class StateRefusedError extends Error {
+    readonly refusals: RootRefusal[];
+    constructor(refusals: RootRefusal[]);
+}
+/** How a write ended: written, or kept with the lock held. */
+export type WriteOutcome = {
+    written: true;
+    attempts: number;
+} | {
+    written: false;
+    attempts: number;
+    error: string;
+    kept: string;
+    lockHeld: true;
+};
+export declare class RootStates {
+    private readonly o;
+    private readonly exec;
+    private readonly op;
+    private readonly objects;
+    private locks;
+    private readonly heldOnPurpose;
+    constructor(o: RootStatesOptions);
+    private log;
+    private rootOf;
+    /** Where a root's state is, or why it is not locked. */
+    object(root: string): StateObject;
+    /** Every root whose state chant does not lock, with why. */
+    refusals(): RootRefusal[];
+    /** The locks held now, by root. */
+    held(): string[];
+    private lockOf;
+    /**
+     * Take every root's lock, in order. A root chant does not lock stops the
+     * take before any lock (StateRefusedError); a lock another run holds
+     * releases what was taken and throws StateLockedError, naming the holder.
+     * A lock an earlier run of this operation left held with a kept state is
+     * taken over, and every kept state is written before this returns.
+     */
+    take(): Promise<void>;
+    /** The state kept beside a store's state and the suffix it is under, chant's name first; undefined when none is kept. */
+    private kept;
+    /** A state an earlier run kept beside a root's state: write it, then remove what was kept. */
+    private writeKept;
+    /** A root's state as `state pull` gives it, or null when it has none. */
+    pull(root: string): Promise<StateFile | null>;
+    /** Write one root's state under its lock: the store's own write (azurerm's lease), else `state push -lock=false`. */
+    private writeState;
+    /**
+     * Write one root's state, retrying after each delay while the lock is
+     * held. A state still unwritten after the last retry is kept, and its lock
+     * stays held: `release` leaves it.
+     */
+    write(root: string, state: StateFile): Promise<WriteOutcome>;
+    /** Keep a state that could not be written: beside it in its own backend, else as a file of the job's report directory. Returns where. */
+    private keep;
+    /**
+     * Keep a root's lock held past {@link release}, as a kept state's is: for a
+     * root whose state the run could neither write nor keep, so no other run
+     * plans against a state that may not hold what applied.
+     */
+    hold(root: string): void;
+    /** The roots whose lock stays held past {@link release}. */
+    heldOnPurposeRoots(): string[];
+    /** Release a root's lock, or every lock but those held on purpose for a kept state. */
+    release(root?: string): Promise<void>;
+}
+//# sourceMappingURL=root-states.d.ts.map

package/dist/state/root-states.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-states.d.ts","sourceRoot":"","sources":["../../src/state/root-states.ts"],"names":[],"mappings":"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"}

package/dist/state/root-states.js

@@ -0,0 +1,241 @@
+/**
+ * The states of a set of roots, held for one run: take every lock (in the
+ * order given), pull each state, write each state back with retries, and
+ * release each lock.
+ *
+ * A state whose write still fails after the retries is kept beside the state
+ * in its own backend as `<key>.chant-unwritten`, and its lock stays held,
+ * naming the run. The next take of that lock finds the kept state, takes
+ * the lock over, writes the kept state, removes it, and only then returns.
+ * When the backend cannot take the kept copy either, it goes under the job's
+ * report directory (`<reportDir>/unwritten/<root>.tfstate`), never the
+ * reports bucket.
+ *
+ * A take also reads a state terragucci kept as `<key>.terragucci-unwritten`
+ * under a terragucci composed run's lock, so a repo that moves to chant
+ * mid-incident keeps it. That name is read and removed, never written.
+ *
+ * Lifted from terragucci's `compose.ts` (c493e0e): `ComposedRun.plan`'s lock
+ * take and kept write, `writeState`, `writeWithRetries`, `keep`,
+ * `releaseOne` and `release`.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isRefused, stateObject } from "./backend.js";
+import { lastLines, pullState, runBinary } from "./exec.js";
+import { takeLocks } from "./locks.js";
+import { stateStore } from "./store.js";
+/** The suffix of the object beside a root's state that holds a state a run could not write. */
+export const UNWRITTEN_SUFFIX = ".chant-unwritten";
+/** The suffix terragucci keeps an unwritten state under: read and removed, never written. */
+export const LEGACY_UNWRITTEN_SUFFIX = ".terragucci-unwritten";
+/** The operation terragucci's composed run names in its locks. */
+export const LEGACY_COMPOSE_OPERATION = "terragucci compose";
+/** Where a kept state goes under the job's report directory when its own backend could not take it. */
+export const UNWRITTEN_DIR = "unwritten";
+/** The operation a composed run's locks name. */
+export const COMPOSE_LOCK = { operation: "chant terraform.compose", info: "a composed run holds this state while it plans, applies and writes it" };
+/** How long to wait before each retry of a state's write: five retries, inside the lock timeout of 5 minutes. */
+export const DEFAULT_RETRY_DELAYS = [5000, 15000, 30000, 60000, 120000];
+/** The roots whose state chant does not lock: the take stops before any lock. */
+export class StateRefusedError extends Error {
+    constructor(refusals) {
+        super(refusals.map((r) => `${r.root}: ${r.reason}`).join("\n"));
+        this.refusals = refusals;
+        this.name = "StateRefusedError";
+    }
+}
+const sleepMs = (ms) => new Promise((r) => setTimeout(r, ms));
+const safeName = (root) => (root === "." ? "root" : root.replace(/[^\w.-]/g, "_"));
+const body = (s) => JSON.stringify(s, null, 2) + "\n";
+export class RootStates {
+    constructor(o) {
+        this.o = o;
+        this.objects = new Map();
+        this.locks = [];
+        this.heldOnPurpose = new Set();
+        this.exec = o.exec ?? runBinary;
+        this.op = o.op ?? COMPOSE_LOCK;
+        if (o.runId)
+            this.op = { operation: this.op.operation, info: `${this.op.info} (run ${o.runId})` };
+    }
+    log(line) {
+        this.o.log?.(line);
+    }
+    rootOf(root) {
+        const r = this.o.roots.find((x) => x.root === root);
+        if (!r)
+            throw new Error(`${root} is not one of this run's roots`);
+        return r;
+    }
+    /** Where a root's state is, or why it is not locked. */
+    object(root) {
+        let o = this.objects.get(root);
+        if (!o) {
+            const r = this.rootOf(root);
+            o = r.object ?? stateObject(r.dir, r.env, undefined, this.o.binary, {
+                ...(r.backendConfig ? { backendConfig: r.backendConfig } : {}),
+                ...(r.backendConfigFiles ? { backendConfigFiles: r.backendConfigFiles } : {}),
+            });
+            this.objects.set(root, o);
+        }
+        return o;
+    }
+    /** Every root whose state chant does not lock, with why. */
+    refusals() {
+        return this.o.roots.flatMap((r) => {
+            const o = this.object(r.root);
+            return isRefused(o) ? [{ root: r.root, backend: o.backend, refused: o.refused, reason: o.reason }] : [];
+        });
+    }
+    /** The locks held now, by root. */
+    held() {
+        return this.locks.map((l) => l.root);
+    }
+    lockOf(root) {
+        return this.locks.find((l) => l.root === root);
+    }
+    /**
+     * Take every root's lock, in order. A root chant does not lock stops the
+     * take before any lock (StateRefusedError); a lock another run holds
+     * releases what was taken and throws StateLockedError, naming the holder.
+     * A lock an earlier run of this operation left held with a kept state is
+     * taken over, and every kept state is written before this returns.
+     */
+    async take() {
+        const refused = this.refusals();
+        if (refused.length)
+            throw new StateRefusedError(refused);
+        const stores = this.o.roots.map((r) => {
+            const object = this.object(r.root);
+            return { root: r.root, store: this.o.openStore ? this.o.openStore(r, object) : stateStore(object, r.dir, this.o.fetch) };
+        });
+        const now = this.o.now?.() ?? new Date().toISOString();
+        this.locks = await takeLocks(stores, now, this.op, async (root, store, held) => {
+            // A lock an earlier composed run left held for a state it could not write: this run writes that state first.
+            const ours = held.info.includes(this.op.operation) || held.info.includes(LEGACY_COMPOSE_OPERATION);
+            if (!ours || !(await this.kept(store)))
+                return false;
+            this.log(`${root}: its lock is held by an earlier run that kept a state it could not write; this run takes the lock over and writes that state first`);
+            return true;
+        }, this.o.who);
+        for (const l of this.locks) {
+            try {
+                await this.writeKept(l);
+            }
+            catch (e) {
+                // The kept state is still unwritten: its lock stays held, the others are released.
+                this.heldOnPurpose.add(l.root);
+                await this.release();
+                throw new Error(`${l.root}: the state an earlier run kept for it could not be written: ${e.message}`);
+            }
+        }
+    }
+    /** The state kept beside a store's state and the suffix it is under, chant's name first; undefined when none is kept. */
+    async kept(store) {
+        for (const suffix of [UNWRITTEN_SUFFIX, LEGACY_UNWRITTEN_SUFFIX]) {
+            const text = await store.readBeside(suffix).catch(() => undefined);
+            if (text?.trim())
+                return { suffix, text };
+        }
+        return undefined;
+    }
+    /** A state an earlier run kept beside a root's state: write it, then remove what was kept. */
+    async writeKept(lock) {
+        const kept = await this.kept(lock.store);
+        if (!kept)
+            return;
+        await this.writeState(lock.root, JSON.parse(kept.text));
+        await lock.store.removeBeside(kept.suffix);
+        this.log(`${lock.root}: wrote the state an earlier run kept at ${lock.store.besideLocation(kept.suffix)}`);
+    }
+    /** A root's state as `state pull` gives it, or null when it has none. */
+    pull(root) {
+        const r = this.rootOf(root);
+        return pullState(this.exec, this.o.binary, root, r.dir, r.env);
+    }
+    /** Write one root's state under its lock: the store's own write (azurerm's lease), else `state push -lock=false`. */
+    async writeState(root, state) {
+        const lock = this.lockOf(root);
+        if (!lock)
+            throw new Error(`${root}: its state is written under its lock, and none is held`);
+        if (lock.store.write) {
+            await lock.store.write(body(state));
+            return;
+        }
+        const r = this.rootOf(root);
+        const file = join(this.o.work, `${safeName(root)}.tfstate`);
+        mkdirSync(this.o.work, { recursive: true });
+        writeFileSync(file, body(state));
+        const push = await this.exec(this.o.binary, ["state", "push", "-lock=false", file], r.dir, r.env);
+        if (push.code !== 0)
+            throw new Error(`state push failed: ${lastLines(push.out, 3)}`);
+    }
+    /**
+     * Write one root's state, retrying after each delay while the lock is
+     * held. A state still unwritten after the last retry is kept, and its lock
+     * stays held: `release` leaves it.
+     */
+    async write(root, state) {
+        const delays = this.o.retryDelays ?? DEFAULT_RETRY_DELAYS;
+        const sleep = this.o.sleep ?? sleepMs;
+        let last = "";
+        for (let i = 0; i <= delays.length; i++) {
+            try {
+                await this.writeState(root, state);
+                return { written: true, attempts: i + 1 };
+            }
+            catch (e) {
+                last = e.message;
+                if (i < delays.length) {
+                    this.log(`${root}: the write of its state failed (${last}); trying again in ${Math.round(delays[i] / 1000)}s`);
+                    await sleep(delays[i]);
+                }
+            }
+        }
+        const kept = await this.keep(root, state);
+        this.heldOnPurpose.add(root);
+        this.log(`${root}: its state could not be written (${last}); kept at ${kept}, and its lock stays held until a later run writes it`);
+        return { written: false, attempts: delays.length + 1, error: last, kept, lockHeld: true };
+    }
+    /** Keep a state that could not be written: beside it in its own backend, else as a file of the job's report directory. Returns where. */
+    async keep(root, state) {
+        const lock = this.lockOf(root);
+        try {
+            if (lock) {
+                await lock.store.writeBeside(UNWRITTEN_SUFFIX, body(state));
+                return lock.store.besideLocation(UNWRITTEN_SUFFIX);
+            }
+        }
+        catch (e) {
+            this.log(`${root}: the state could not be kept beside its backend's state either (${e.message}); it is kept under the job's report directory`);
+        }
+        const file = join(this.o.reportDir, UNWRITTEN_DIR, `${safeName(root)}.tfstate`);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, body(state));
+        return file;
+    }
+    /**
+     * Keep a root's lock held past {@link release}, as a kept state's is: for a
+     * root whose state the run could neither write nor keep, so no other run
+     * plans against a state that may not hold what applied.
+     */
+    hold(root) {
+        if (this.lockOf(root))
+            this.heldOnPurpose.add(root);
+    }
+    /** The roots whose lock stays held past {@link release}. */
+    heldOnPurposeRoots() {
+        return [...this.heldOnPurpose].filter((r) => this.lockOf(r)).sort();
+    }
+    /** Release a root's lock, or every lock but those held on purpose for a kept state. */
+    async release(root) {
+        const which = root ? [root] : [...new Set(this.locks.map((l) => l.root))].filter((r) => !this.heldOnPurpose.has(r));
+        for (const r of which) {
+            const mine = this.locks.filter((l) => l.root === r);
+            this.locks = this.locks.filter((l) => l.root !== r);
+            for (const l of mine)
+                await l.release().catch((e) => this.log(`${r}: its lock could not be released: ${e.message}`));
+        }
+    }
+}

package/dist/state/s3.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The S3 client a state's lock and write use: chant core's (#4554,
+ * `@intentius/chant/object-store`), which signs with chant's one AWS
+ * signer. Get, put, put only when absent, head and delete one object; with
+ * no static keys, a role is assumed with the job's OIDC token through STS
+ * AssumeRoleWithWebIdentity.
+ */
+import { type S3Target } from "@intentius/chant/object-store";
+export { assumeRoleWithWebIdentity, S3Client, sign, type S3Credentials, type S3Location, type S3Target, type S3WebIdentity } from "@intentius/chant/object-store";
+/**
+ * The target for `bucket` from the AWS environment variables. Credentials,
+ * first match wins: static keys in `AWS_ACCESS_KEY_ID` and
+ * `AWS_SECRET_ACCESS_KEY`; `AWS_ROLE_ARN` assumed with the token in
+ * `AWS_WEB_IDENTITY_TOKEN_FILE`, in a session named `chant-state` unless
+ * AWS_ROLE_SESSION_NAME names one.
+ */
+export declare function s3FromEnv(where: {
+    bucket: string;
+    endpoint?: string;
+}, env?: NodeJS.ProcessEnv): S3Target;
+//# sourceMappingURL=s3.d.ts.map