@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/state/locks.test.ts

@@ -0,0 +1,84 @@
+// The source-workspace lock a state migration takes (terragucci#1274): a workspace a state is read from is locked
+// through its own API before any state lock, and released when a later lock cannot be taken.
+import { describe, expect, it } from "vitest";
+import { SourceLockedError, StateLockedError, takeLocksWithSources, takeSourceLocks, type LockStore, type SourceLock } from "./locks";
+
+const T = "2026-10-25T00:00:00Z";
+const op = { operation: "terragucci migrate", info: "a state migration is writing this state" };
+
+function store(location: string, held?: string): LockStore & { taken: string[]; released: number } {
+  const s = {
+    location,
+    lockLocation: `${location}.tflock`,
+    taken: [] as string[],
+    released: 0,
+    heldLock: async () => (held ? { id: "other", info: held } : undefined),
+    lock: async (info: string) => {
+      if (held) return false;
+      s.taken.push(info);
+      return true;
+    },
+    unlock: async () => {
+      s.released++;
+    },
+    adopt: () => {},
+  };
+  return s;
+}
+
+function source(root: string, location: string, refuse?: string): SourceLock & { reasons: string[]; released: number } {
+  const s = {
+    root,
+    location,
+    reasons: [] as string[],
+    released: 0,
+    lock: async (reason: string) => {
+      if (refuse) throw new Error(refuse);
+      s.reasons.push(reason);
+      return async () => {
+        s.released++;
+      };
+    },
+  };
+  return s;
+}
+
+describe("source-workspace locks", () => {
+  it("takes the source workspaces first, naming what reads them, then the states", async () => {
+    const src = source("envs/dev", "app.terraform.io/acme/dev");
+    const st = store("s3://b/envs/dev.tfstate");
+    const got = await takeLocksWithSources({ sources: [src], stores: [{ root: "envs/dev", store: st }], now: T, op, sourceOp: { operation: "terragucci migrate", info: "a state migration is reading this state" } });
+    expect(src.reasons).toEqual(["terragucci migrate: a state migration is reading this state"]);
+    expect(st.taken).toHaveLength(1);
+    expect(JSON.parse(st.taken[0]!)).toMatchObject({ Operation: "terragucci migrate", Created: T, Path: "b/envs/dev.tfstate" });
+    expect(got.sources.map((s) => s.root)).toEqual(["envs/dev"]);
+    expect(got.locks.map((l) => l.root)).toEqual(["envs/dev"]);
+    await got.sources[0]!.release();
+    expect(src.released).toBe(1);
+  });
+
+  it("names the operation's own info on a source lock without sourceOp", async () => {
+    const src = source("a", "ws");
+    await takeSourceLocks([src], op);
+    expect(src.reasons).toEqual(["terragucci migrate: a state migration is writing this state"]);
+  });
+
+  it("releases the source locks when a state is locked by another run", async () => {
+    const src = source("envs/dev", "ws");
+    const st = store("s3://b/k", JSON.stringify({ ID: "x", Operation: "OperationTypeApply", Who: "someone" }));
+    await expect(takeLocksWithSources({ sources: [src], stores: [{ root: "envs/dev", store: st }], now: T, op })).rejects.toBeInstanceOf(StateLockedError);
+    expect(src.released).toBe(1);
+  });
+
+  it("releases what it took and takes no state lock when a source workspace is locked", async () => {
+    const first = source("a", "ws-a");
+    const second = source("b", "ws-b", "its workspace ws-b is locked");
+    const st = store("s3://b/k");
+    const err = await takeLocksWithSources({ sources: [first, second], stores: [{ root: "a", store: st }], now: T, op }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(SourceLockedError);
+    expect((err as SourceLockedError).root).toBe("b");
+    expect((err as Error).message).toContain("ws-b is locked");
+    expect(first.released).toBe(1);
+    expect(st.taken).toEqual([]);
+  });
+});

package/src/state/locks.ts

@@ -0,0 +1,201 @@
+/**
+ * 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";
+import type { LockHolder, StateStore } from "./store";
+
+/** 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 function lockInfo(path: string, now: string, op: LockOperation, who = `chant@${hostname()}`): string {
+  return JSON.stringify({ ID: randomUUID(), Operation: op.operation, Info: op.info, Who: who, Version: "", Created: now, Path: path });
+}
+
+/** 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 function holderOf(held: LockHolder): LockHolderInfo {
+  let v: Record<string, unknown> = {};
+  try {
+    v = JSON.parse(held.info) as Record<string, unknown>;
+  } catch {
+    // Lock info that is not JSON names no one.
+  }
+  const s = (k: string): string | undefined => (typeof v[k] === "string" && v[k] !== "" ? (v[k] as string) : 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(
+    readonly root: string,
+    readonly lockLocation: string,
+    readonly holder?: LockHolderInfo,
+  ) {
+    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.name = "StateLockedError";
+  }
+}
+
+/** 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 async 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>[]> {
+  const held: HeldLock<S>[] = [];
+  const releaseAll = async (): Promise<void> => {
+    for (const h of held.reverse()) await h.release().catch(() => {});
+  };
+  for (const { root, store } of stores) {
+    let got: boolean;
+    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 as Error).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;
+}
+
+/**
+ * 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 class SourceLockedError extends Error {
+  constructor(
+    readonly root: string,
+    readonly location: string,
+    readonly reason: string,
+  ) {
+    super(`${root}: the lock of the workspace it is read from (${location}) could not be taken: ${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: LockOperation): string => `${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: readonly SourceLock[], op: LockOperation): Promise<HeldSourceLock[]> {
+  const held: HeldSourceLock[] = [];
+  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 as Error).message);
+    }
+  }
+  return held;
+}
+
+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 async function takeLocksWithSources<S extends LockStore = StateStore>(input: LocksWithSourcesInput<S>): Promise<{ sources: HeldSourceLock[]; locks: HeldLock<S>[] }> {
+  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/src/state/object-store.ts

@@ -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, type StoreCondition, type StoreFetch } from "@intentius/chant/object-store";

package/src/state/root-states-floci.e2e.test.ts

@@ -0,0 +1,66 @@
+/**
+ * An s3 state's lock against floci (#4437): a real lock object taken, a
+ * state written under it, and the lock released. Set CHANT_FLOCI_ENDPOINT to
+ * a running floci, for example `docker run -d -p 4611:4566 floci/floci` and
+ * `CHANT_FLOCI_ENDPOINT=http://localhost:4611`. Skipped without it.
+ *
+ * The binary is faked: its `state push` puts the state object in the bucket
+ * the way the s3 backend does, after checking the lock object is there.
+ */
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import type { BinaryExec, StateFile } from "./exec";
+import { RootStates, UNWRITTEN_SUFFIX } from "./root-states";
+import { S3Client, sign } from "./s3";
+
+const endpoint = process.env.CHANT_FLOCI_ENDPOINT?.replace(/\/+$/, "");
+
+describe.skipIf(!endpoint)("an s3 state's lock against floci (#4437)", () => {
+  const bucket = `chant-state-${process.pid}-${Date.now()}`;
+  const creds = { region: "us-east-1", accessKeyId: "test", secretAccessKey: "test" };
+  const env = { AWS_ACCESS_KEY_ID: "test", AWS_SECRET_ACCESS_KEY: "test", AWS_REGION: "us-east-1" };
+  const client = new S3Client({ bucket, endpoint: endpoint!, ...creds });
+  const state: StateFile = { version: 4, terraform_version: "1.10.0", serial: 3, lineage: "floci-lineage", outputs: {}, resources: [] };
+  let dir: string;
+
+  beforeAll(async () => {
+    const url = `${endpoint}/${bucket}`;
+    const res = await fetch(url, { method: "PUT", headers: sign(creds, "PUT", url, {}, createHash("sha256").update("").digest("hex"), new Date()) });
+    expect(res.ok).toBe(true);
+    dir = join(mkdtempSync(join(tmpdir(), "chant-floci-")), "app");
+    mkdirSync(join(dir, ".terraform"), { recursive: true });
+    writeFileSync(join(dir, ".terraform/terraform.tfstate"), JSON.stringify({ version: 3, backend: { type: "s3", config: { bucket, key: "app.tfstate", region: "us-east-1", use_lockfile: true, endpoints: { s3: endpoint } } } }));
+  });
+
+  afterAll(async () => {
+    for (const k of ["app.tfstate", "app.tfstate.tflock", `app.tfstate${UNWRITTEN_SUFFIX}`]) await client.remove(k).catch(() => {});
+  });
+
+  it("takes the lock object, writes the state under it, and releases it", async () => {
+    const lockAtPush: (string | undefined)[] = [];
+    const exec: BinaryExec = async (_bin, args) => {
+      if (args[0] === "state" && args[1] === "push") {
+        lockAtPush.push(await client.get("app.tfstate.tflock"));
+        await client.put("app.tfstate", readFileSync(args.at(-1)!, "utf-8"), "application/json");
+        return { code: 0, stdout: "", out: "" };
+      }
+      if (args[0] === "state" && args[1] === "pull") return { code: 0, stdout: (await client.get("app.tfstate")) ?? "", out: "" };
+      return { code: 1, stdout: "", out: "unexpected" };
+    };
+    const states = new RootStates({ roots: [{ root: "app", dir, env }], binary: "tofu", exec, work: mkdtempSync(join(tmpdir(), "chant-floci-work-")), reportDir: mkdtempSync(join(tmpdir(), "chant-floci-report-")), runId: "floci-1" });
+    await states.take();
+    const lock = await client.get("app.tfstate.tflock");
+    expect(JSON.parse(lock!)).toMatchObject({ Operation: "chant terraform.compose", Info: expect.stringContaining("(run floci-1)"), Path: `${bucket}/app.tfstate` });
+    // A second run finds the real lock object held.
+    const other = new RootStates({ roots: [{ root: "app", dir, env }], binary: "tofu", exec, work: mkdtempSync(join(tmpdir(), "chant-floci-work-")), reportDir: mkdtempSync(join(tmpdir(), "chant-floci-report-")) });
+    await expect(other.take()).rejects.toThrow("its state is locked at s3://");
+    expect(await states.write("app", state)).toEqual({ written: true, attempts: 1 });
+    expect(lockAtPush).toEqual([lock]);
+    expect(await states.pull("app")).toMatchObject({ lineage: "floci-lineage", serial: 3 });
+    await states.release();
+    expect(await client.get("app.tfstate.tflock")).toBeUndefined();
+  });
+});