@intentius/chant-lexicon-terraform 0.124.76 → 0.124.77

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/state-ops.ts CHANGED
@@ -34,25 +34,24 @@
34
34
  * The exec is injectable (`./state/exec.ts`), and so is the gated-request
35
35
  * ledger, so a test runs no binary and writes no ledger.
36
36
  */
37
- import { createHash } from "node:crypto";
37
+ import { mkdtempSync, rmSync } from "node:fs";
38
+ import { tmpdir } from "node:os";
38
39
  import { join } from "node:path";
39
40
  import type { Capability, CapabilityPlan } from "@intentius/chant/components/capability";
40
41
  import type { ChangeSetPart } from "@intentius/chant/change-set";
41
42
  import { CHANT_EXIT } from "@intentius/chant/exit-codes";
42
- import {
43
- finishGatedRequest,
44
- gatedRequestDigest,
45
- readGatedRequests,
46
- requestGate,
47
- spendGatedRequest,
48
- type GatedRequest,
49
- type GatedRequestRules,
50
- type RequestGateInput,
51
- type RequestGateResult,
52
- } from "@intentius/chant/lifecycle/gated-request";
43
+ import { gatedRequestDigest, type GatedRequest, type GatedRequestRules } from "@intentius/chant/lifecycle/gated-request";
44
+ import { gatedOp } from "@intentius/chant/lifecycle/gated-op";
45
+ import { exportStateVersion, StateExportError, type StateExportInput, type StateExportOutcome } from "@intentius/chant/state-export";
46
+ import { parseLockInfo, releaseStateLock, StateUnlockError, type LockInfo, type StateLockSource, type StateUnlockInput, type StateUnlockOutcome } from "@intentius/chant/state-unlock";
53
47
  import { plannerForBinary, terraformChangeSetPart } from "./change-set";
54
48
  import { DEFAULT_LOCK_TIMEOUT, lockTimeoutArgs } from "./lock-timeout";
49
+ import { initialisedBackend, isRefused, stateObject, type StateObject } from "./state/backend";
55
50
  import { lastLines, runBinary, type BinaryExec } from "./state/exec";
51
+ import { gitlabState, gitlabStore, shownUrl, type GitLabFetch, type GitLabState } from "./state/gitlab";
52
+ import type { StoreFetch } from "./state/object-store";
53
+ import { stateStore } from "./state/store";
54
+ import { gitlabVersionSource, stateVersionSource } from "./state/versions";
56
55
 
57
56
  /** The ops the gated requests of this module wait at, one per kind, as terragucci named them. */
58
57
  export const STATE_OPS = {
@@ -201,140 +200,143 @@ export async function applyPlanFile(r: RootRun & { planFile: string; lockTimeout
201
200
 
202
201
  // ── the gate around them ────────────────────────────────────────────────────
203
202
 
204
- /** The gated-request ledger, injectable for tests. Default chant's on `chant/lifecycle`. */
205
- export interface GatedRequestLedger {
206
- requestGate: typeof requestGate;
207
- spendGatedRequest: typeof spendGatedRequest;
208
- finishGatedRequest: typeof finishGatedRequest;
209
- readGatedRequests: typeof readGatedRequests;
203
+ // The walk itself is chant core's since #4762 (`@intentius/chant/lifecycle/gated-op`), engine-neutral; these names stay for the products written against them.
204
+ export { attachmentDigest, requestedAt, type GatedRequestLedger } from "@intentius/chant/lifecycle/gated-op";
205
+ export type { GatedOpInput as GatedStateOpInput, GatedOpResult as GatedStateOpResult } from "@intentius/chant/lifecycle/gated-op";
206
+ /** Run `act` once its request is approved: chant core's {@link gatedOp}. */
207
+ export const gatedStateOp = gatedOp;
208
+
209
+ /** The digest a request binds, for a caller that prints it before it asks. */
210
+ export const stateOpDigest = (op: string, request: GatedRequest): string => gatedRequestDigest(op, request);
211
+
212
+ // ── export and release (#4762) ───────────────────────────────────────────────
213
+
214
+ /** A root's backend, read the way export and release read it. */
215
+ export interface RootBackendRun extends RootRun {
216
+ /**
217
+ * Run `init` in a data dir of its own (a new temp dir as `TF_DATA_DIR`,
218
+ * removed after), so the checkout's `.terraform` is left alone. Default
219
+ * true. Pass false for a root another tool initialised in `dir` with `env`,
220
+ * such as a Terragrunt unit.
221
+ */
222
+ init?: boolean;
223
+ /** The backend's HTTP calls, for tests. */
224
+ fetch?: StoreFetch;
210
225
  }
211
226
 
212
- const chantLedger: GatedRequestLedger = { requestGate, spendGatedRequest, finishGatedRequest, readGatedRequests };
227
+ /**
228
+ * Where a root's state is: init (in a data dir of its own unless `init` is
229
+ * false), then the backend init recorded. `act` runs while the data dir is
230
+ * there, with the env that names it, so a binary run inside it finds the
231
+ * root initialised; the data dir is removed after.
232
+ */
233
+ async function withBackend<T>(r: RootBackendRun, act: (object: RootStateAt, env: NodeJS.ProcessEnv) => Promise<T>, readOnly = false): Promise<T> {
234
+ const env = r.env ?? process.env;
235
+ if (r.init === false) return act(objectOf(r.dir, env, r.binary, readOnly), env);
236
+ const data = mkdtempSync(join(tmpdir(), "chant-state-data-"));
237
+ try {
238
+ const benv = { ...env, TF_DATA_DIR: data };
239
+ await initRoot({ ...r, env: benv });
240
+ return await act(objectOf(r.dir, benv, r.binary, readOnly), benv);
241
+ } finally {
242
+ rmSync(data, { recursive: true, force: true });
243
+ }
244
+ }
245
+
246
+ /** Where a root's state is: a state object, or a GitLab-managed state (./state/gitlab.ts), which the lock verdict refuses and export and release read. */
247
+ type RootStateAt = StateObject | GitLabState;
248
+
249
+ const isGitLab = (o: RootStateAt): o is GitLabState => "address" in o;
213
250
 
214
251
  /**
215
- * The time a request was first asked, so asking again binds the same
216
- * digest: chant's digest covers `at`, and a run that asked anew each time
217
- * would never meet the approval of the last one. The newest standing,
218
- * unspent request with the same kind, subject, requester and fields gives
219
- * its `at`; with none, `now`.
252
+ * The root's state. A read needs no lock file, so an s3 backend that locks
253
+ * with DynamoDB is read as one that takes the lock file: the refusal is
254
+ * about holding its lock, which a read never does. An http backend whose
255
+ * address is GitLab's state API is that state.
220
256
  */
221
- export async function requestedAt(
222
- op: string,
223
- request: Omit<GatedRequest, "at">,
224
- options: { now?: string; cwd?: string; ledger?: Pick<GatedRequestLedger, "readGatedRequests"> } = {},
225
- ): Promise<string> {
226
- const now = options.now ?? new Date().toISOString();
227
- const read = await (options.ledger ?? chantLedger).readGatedRequests(op, options.cwd ? { cwd: options.cwd } : undefined).catch(() => []);
228
- const same = JSON.stringify(Object.entries(request.fields).sort());
229
- const standing = read
230
- .filter((g) => !g.applied && g.request.kind === request.kind && g.request.subject === request.subject && g.request.by === request.by)
231
- .filter((g) => JSON.stringify(Object.entries(g.request.fields).sort()) === same)
232
- .filter((g) => !g.pending.expiresAt || g.pending.expiresAt > now)
233
- .at(-1);
234
- return standing?.request.at ?? now;
257
+ function objectOf(dir: string, env: NodeJS.ProcessEnv, binary: string, readOnly: boolean): RootStateAt {
258
+ const o = stateObject(dir, env, undefined, binary);
259
+ if (!isRefused(o)) return o;
260
+ const recorded = initialisedBackend(dir, env);
261
+ if (o.backend === "http" && recorded?.type === "http") return gitlabState(recorded.config, env) ?? o;
262
+ if (!readOnly || o.refused !== "no-lockfile") return o;
263
+ return stateObject(dir, env, recorded ? { ...recorded, config: { ...recorded.config, use_lockfile: true } } : undefined, binary, { backendConfig: { use_lockfile: "true" } });
235
264
  }
236
265
 
237
- /** The digest `requestGate` puts in `fields.proof` for an attachment. */
238
- export const attachmentDigest = (attachment: string): string => `sha256:${createHash("sha256").update(attachment).digest("hex")}`;
239
-
240
- export interface GatedStateOpInput {
241
- op: string;
242
- /** The request, less `at`, which {@link requestedAt} fills. */
243
- request: Omit<GatedRequest, "at"> & { at?: string };
244
- rules: GatedRequestRules;
245
- description?: string;
246
- expiry?: string;
247
- base?: string;
248
- /** A document the request carries, such as a migration's proof; its digest joins the request. */
249
- attachment?: string;
250
- cwd?: string;
251
- now?: string;
252
- runId?: string;
253
- commit?: string;
254
- ledger?: GatedRequestLedger;
255
- gates?: RequestGateInput["gates"];
256
- /**
257
- * A last check just before the spend, for a fact that can change while the
258
- * request waited (a run that may hold the lock came back). A string refuses
259
- * the operation with that reason, and the approval is not spent.
260
- */
261
- beforeSpend?: () => Promise<string | undefined>;
262
- /**
263
- * The flat facts of a failed act's finished line, beside its `error`, such
264
- * as the binary's exit code and last lines (#4653). Default none.
265
- */
266
- failedDetail?: (error: Error) => Record<string, string | number | boolean>;
266
+ export interface TerraformStateExportInput extends Omit<StateExportInput, "source" | "subject">, RootBackendRun {}
267
+
268
+ /**
269
+ * chant core's state export (`exportStateVersion`) of one root: its backend
270
+ * read by an init of its own, its versions read from the bucket or container
271
+ * (`./state/versions.ts`). Throws `StateExportError` for a backend that keeps
272
+ * no versions chant reads.
273
+ */
274
+ export async function terraformStateExport(input: TerraformStateExportInput): Promise<StateExportOutcome> {
275
+ const source = await withBackend(input, async (object) => (isGitLab(object) ? gitlabVersionSource(gitlabStore(object, input.fetch as GitLabFetch | undefined)) : stateVersionSource(object, input.fetch)), true);
276
+ if ("refused" in source) throw new StateExportError(`${input.root}: ${source.refused}`);
277
+ return exportStateVersion({ ...input, subject: input.root, source });
267
278
  }
268
279
 
269
- /** How a gated operation ended. */
270
- export type GatedStateOpResult<T> =
271
- | Exclude<RequestGateResult, { status: "approved" }>
272
- | { status: "held"; digest: string; request: GatedRequest; reason: string }
273
- | { status: "done"; digest: string; request: GatedRequest; approvedBy: string; output: T; recorded: boolean }
274
- | { status: "failed"; digest: string; request: GatedRequest; approvedBy: string; error: Error; recorded: boolean };
280
+ /** What a state lock release reads and releases. */
281
+ const RELEASES = "a lock release reads the lock of an s3 backend's lock file, a gcs backend, an azurerm backend and a GitLab-managed state";
275
282
 
276
283
  /**
277
- * Run `act` once its request is approved: ask (or read) the request, spend
278
- * the approval, act, and record how it ended. `act` returns its output and
279
- * the flat facts that go on the finished line. A spend that cannot be pushed
280
- * throws before `act` runs, so no approval acts twice. A finished line that
281
- * cannot be written is reported as `recorded: false`; the act already ran.
284
+ * A root's lock as chant core's lock release reads it: the lock its store
285
+ * holds (`StateStore.heldLock`: the s3 lock file, the gcs lock object, whose
286
+ * generation is the ID the binary takes, the azurerm lease), released with
287
+ * the binary's fixed `force-unlock` of that ID. A GitLab-managed state's lock
288
+ * is read by asking for it and released by its ID on the unlock address,
289
+ * which GitLab refuses for any other lock. A local state's lock goes with
290
+ * the process that took it, so it is refused.
282
291
  */
283
- export async function gatedStateOp<T>(
284
- input: GatedStateOpInput,
285
- act: (approved: { digest: string; request: GatedRequest; approvedBy: string }) => Promise<{ output: T; detail?: Record<string, string | number | boolean> }>,
286
- ): Promise<GatedStateOpResult<T>> {
287
- const ledger = input.ledger ?? chantLedger;
288
- // The proof's digest is a field of the stored request, so the standing request is matched with it.
289
- const fields = input.attachment !== undefined ? { ...input.request.fields, proof: attachmentDigest(input.attachment) } : input.request.fields;
290
- const at = input.request.at ?? (await requestedAt(input.op, { ...input.request, fields }, { ...(input.now ? { now: input.now } : {}), ...(input.cwd ? { cwd: input.cwd } : {}), ledger }));
291
- const request: GatedRequest = { kind: input.request.kind, subject: input.request.subject, by: input.request.by, at, fields };
292
- const asked = await ledger.requestGate({
293
- op: input.op,
294
- request,
295
- rules: input.rules,
296
- ...(input.description ? { description: input.description } : {}),
297
- ...(input.expiry ? { expiry: input.expiry } : {}),
298
- ...(input.base ? { base: input.base } : {}),
299
- ...(input.attachment !== undefined ? { attachment: input.attachment } : {}),
300
- ...(input.cwd ? { cwd: input.cwd } : {}),
301
- ...(input.now ? { now: input.now } : {}),
302
- ...(input.gates ? { gates: input.gates } : {}),
303
- });
304
- if (asked.status !== "approved") return asked;
305
- const { digest } = asked;
306
- const approvedBy = asked.approval.resolvedBy;
307
- const held = await input.beforeSpend?.();
308
- if (held) return { status: "held", digest, request: asked.request, reason: held };
309
- const spent = await ledger.spendGatedRequest({
310
- op: input.op,
311
- gate: request.subject,
312
- digest,
313
- approval: asked.approval,
314
- ...(input.runId ? { runId: input.runId } : {}),
315
- ...(input.commit ? { commit: input.commit } : {}),
316
- ...(input.cwd ? { cwd: input.cwd } : {}),
317
- ...(input.now ? { now: input.now } : {}),
318
- });
319
- const finish = async (result: "applied" | "failed", detail?: Record<string, string | number | boolean>): Promise<boolean> => {
320
- try {
321
- const f = await ledger.finishGatedRequest({ op: input.op, gate: request.subject, digest, applied: spent.timestamp, result, ...(detail ? { detail } : {}), ...(input.cwd ? { cwd: input.cwd } : {}) });
322
- return f.pushed;
323
- } catch {
324
- return false;
325
- }
292
+ export function terraformLockSource(r: RootRun & { object: RootStateAt; fetch?: StoreFetch }): StateLockSource | { refused: string } {
293
+ const o = r.object;
294
+ const parsed = (text: string, where: string, id?: string): LockInfo => {
295
+ const info = parseLockInfo(text);
296
+ if (!info) throw new StateOpError(r.root, "a lock read", 0, `${where} holds no lock ID the binary wrote; read it, and remove it by hand if it is not a lock`);
297
+ return id ? { ...info, ID: id } : info;
326
298
  };
327
- try {
328
- const { output, detail } = await act({ digest, request: asked.request, approvedBy });
329
- return { status: "done", digest, request: asked.request, approvedBy, output, recorded: await finish("applied", detail) };
330
- } catch (e) {
331
- const error = e instanceof Error ? e : new Error(String(e));
332
- return { status: "failed", digest, request: asked.request, approvedBy, error, recorded: await finish("failed", { ...(input.failedDetail?.(error) ?? {}), error: error.message.slice(0, 400) }) };
299
+ if (isGitLab(o)) {
300
+ if (!o.lockAddress || !o.unlockAddress) return { refused: `its http backend names no ${o.lockAddress ? "unlock_address (TF_HTTP_UNLOCK_ADDRESS)" : "lock_address (TF_HTTP_LOCK_ADDRESS)"}, so no lock it takes can be read and released` };
301
+ const store = gitlabStore(o, r.fetch as GitLabFetch | undefined);
302
+ const location = shownUrl(o.lockAddress);
303
+ return {
304
+ location,
305
+ read: async () => {
306
+ const text = await store.probeLock();
307
+ return text === undefined ? undefined : parsed(text, location);
308
+ },
309
+ release: (id) => store.releaseLock(id),
310
+ };
333
311
  }
312
+ if (isRefused(o)) return { refused: `${o.reason}; ${RELEASES}` };
313
+ if (o.backend === "local") return { refused: `the state is a local file, whose lock goes with the process that took it; ${RELEASES}` };
314
+ const store = stateStore(o, r.dir, r.fetch);
315
+ return {
316
+ location: store.lockLocation,
317
+ async read() {
318
+ const held = await store.heldLock();
319
+ return held ? parsed(held.info, store.lockLocation, held.id || undefined) : undefined;
320
+ },
321
+ release: (id) => forceUnlockState({ ...r, id }),
322
+ };
334
323
  }
335
324
 
336
- /** The digest a request binds, for a caller that prints it before it asks. */
337
- export const stateOpDigest = (op: string, request: GatedRequest): string => gatedRequestDigest(op, request);
325
+ export interface TerraformStateUnlockInput extends Omit<StateUnlockInput, "lock" | "subject">, RootBackendRun {}
326
+
327
+ /**
328
+ * chant core's lock release (`releaseStateLock`) of one root's state: its
329
+ * backend read by an init of its own, the lock read from the store, released
330
+ * by `force-unlock` in the same data dir. Throws `StateUnlockError` for a
331
+ * backend whose lock chant does not read.
332
+ */
333
+ export async function terraformStateUnlock(input: TerraformStateUnlockInput): Promise<StateUnlockOutcome> {
334
+ return withBackend(input, async (object, env) => {
335
+ const lock = terraformLockSource({ ...input, env, object, ...(input.fetch ? { fetch: input.fetch } : {}) });
336
+ if ("refused" in lock) throw new StateUnlockError(`${input.root}: ${lock.refused}`);
337
+ return releaseStateLock({ ...input, subject: input.root, lock });
338
+ });
339
+ }
338
340
 
339
341
  // ── capabilities ────────────────────────────────────────────────────────────
340
342