@intentius/chant-lexicon-terraform 0.124.84 → 0.124.86

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.
Files changed (65) hide show
  1. package/dist/ci-setup.d.ts +11 -2
  2. package/dist/ci-setup.d.ts.map +1 -1
  3. package/dist/ci-setup.js +11 -6
  4. package/dist/components/capability-plugin.d.ts +12 -0
  5. package/dist/components/capability-plugin.d.ts.map +1 -1
  6. package/dist/components/capability-plugin.js +22 -4
  7. package/dist/compose.d.ts.map +1 -1
  8. package/dist/compose.js +1 -1
  9. package/dist/estate-migration.d.ts +101 -0
  10. package/dist/estate-migration.d.ts.map +1 -0
  11. package/dist/estate-migration.js +471 -0
  12. package/dist/integrity.json +2 -2
  13. package/dist/manifest.json +1 -1
  14. package/dist/op/activities/terraform.d.ts +65 -0
  15. package/dist/op/activities/terraform.d.ts.map +1 -1
  16. package/dist/op/activities/terraform.js +94 -1
  17. package/dist/state/backend.d.ts +46 -9
  18. package/dist/state/backend.d.ts.map +1 -1
  19. package/dist/state/backend.js +84 -31
  20. package/dist/state/gitlab.d.ts +1 -1
  21. package/dist/state/gitlab.d.ts.map +1 -1
  22. package/dist/state/gitlab.js +27 -14
  23. package/dist/state/index.d.ts +1 -0
  24. package/dist/state/index.d.ts.map +1 -1
  25. package/dist/state/index.js +1 -0
  26. package/dist/state/s3.d.ts +9 -3
  27. package/dist/state/s3.d.ts.map +1 -1
  28. package/dist/state/s3.js +4 -3
  29. package/dist/state/source.d.ts +92 -0
  30. package/dist/state/source.d.ts.map +1 -0
  31. package/dist/state/source.js +254 -0
  32. package/dist/state/store.d.ts +41 -4
  33. package/dist/state/store.d.ts.map +1 -1
  34. package/dist/state/store.js +125 -10
  35. package/dist/state/versions.d.ts +77 -10
  36. package/dist/state/versions.d.ts.map +1 -1
  37. package/dist/state/versions.js +118 -64
  38. package/dist/state-migration.d.ts +43 -1
  39. package/dist/state-migration.d.ts.map +1 -1
  40. package/dist/state-migration.js +251 -20
  41. package/dist/state-ops.d.ts +2 -3
  42. package/dist/state-ops.d.ts.map +1 -1
  43. package/dist/state-ops.js +4 -7
  44. package/package.json +2 -2
  45. package/src/ci-setup.test.ts +20 -0
  46. package/src/ci-setup.ts +11 -6
  47. package/src/components/capability-plugin.ts +36 -3
  48. package/src/components/terraform-apply-command-hook.test.ts +157 -0
  49. package/src/compose.ts +1 -0
  50. package/src/estate-migration.test.ts +186 -0
  51. package/src/estate-migration.ts +563 -0
  52. package/src/op/activities/terraform.ts +153 -3
  53. package/src/state/backend-verdict.test.ts +4 -3
  54. package/src/state/backend.test.ts +3 -1
  55. package/src/state/backend.ts +108 -33
  56. package/src/state/gitlab.ts +25 -12
  57. package/src/state/index.ts +1 -0
  58. package/src/state/s3.ts +5 -4
  59. package/src/state/source.ts +289 -0
  60. package/src/state/store.ts +145 -11
  61. package/src/state/versions.test.ts +365 -0
  62. package/src/state/versions.ts +148 -68
  63. package/src/state-migration-backends.test.ts +277 -0
  64. package/src/state-migration.ts +265 -23
  65. package/src/state-ops.ts +6 -8
@@ -39,6 +39,7 @@
39
39
  * {@link MIN_CHOUDOUFU_VERSION}.
40
40
  */
41
41
 
42
+ import { AsyncLocalStorage } from "node:async_hooks";
42
43
  import { exec } from "node:child_process";
43
44
  import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
44
45
  import { tmpdir } from "node:os";
@@ -1042,7 +1043,125 @@ interface ExecFailure {
1042
1043
  stderr?: string;
1043
1044
  }
1044
1045
 
1046
+ /**
1047
+ * One engine command as a product's {@link TerraformCommandHook} sees it
1048
+ * before it runs (chant#4865).
1049
+ */
1050
+ export interface TerraformCommand {
1051
+ /** The step's root the command runs for. */
1052
+ root: string;
1053
+ /** The upstream root whose state the command reads for `root`'s `reads`, when it runs for one. */
1054
+ upstream?: string;
1055
+ /** The step method that runs it: `plan`, `run` (the apply) or `outputs`. */
1056
+ method: string;
1057
+ /** The binary, as the command line names it. */
1058
+ binary: string;
1059
+ /** The subcommand, the first argument that is not a flag: `init`, `plan`, `show`, `apply`, `output`, `workspace`, `live-plan-set`. */
1060
+ name: string;
1061
+ /** The arguments after the binary, unquoted. */
1062
+ args: string[];
1063
+ /** The command line as the shell runs it. */
1064
+ line: string;
1065
+ /** The directory it runs in. */
1066
+ cwd: string;
1067
+ /** The variables chant sets for it over the job's environment, such as `TF_IN_AUTOMATION`, `TF_WORKSPACE` and the run hook's `processEnv`. */
1068
+ env: Record<string, string>;
1069
+ }
1070
+
1071
+ /** How a {@link TerraformCommand} came out, for the hook's `after` (chant#4865). */
1072
+ export interface TerraformCommandResult {
1073
+ /** The exit code; null when the command did not exit on its own (a signal, an abort, a spawn failure). */
1074
+ code: number | null;
1075
+ /** How long it ran, in seconds. */
1076
+ seconds: number;
1077
+ stdout: string;
1078
+ stderr: string;
1079
+ }
1080
+
1081
+ /** What a {@link TerraformCommandHook} answers for one command (chant#4865). */
1082
+ export interface TerraformCommandRun {
1083
+ /** Variables laid over the command's own, such as a span receiver's exporter or a trace parent. */
1084
+ env?: Record<string, string>;
1085
+ /** Called once the command ends, on a failure too, before the step reads its result. */
1086
+ after?: (result: TerraformCommandResult) => void | Promise<void>;
1087
+ }
1088
+
1089
+ /**
1090
+ * A product's hook around each engine command a `terraform-apply` step runs
1091
+ * for a root (chant#4865), `terraformApplyCapabilityWith({ onCommand })`:
1092
+ * called before the command with what it is, and its answer's `after` once
1093
+ * it ends. terragucci times each root's plan and apply with it and sets its
1094
+ * span receiver's variables, as its own runs of the binary did.
1095
+ */
1096
+ export type TerraformCommandHook = (command: TerraformCommand) => TerraformCommandRun | void | Promise<TerraformCommandRun | void>;
1097
+
1098
+ /** The hook, and the root and method it is for, that the commands run in an async call see (chant#4865). */
1099
+ interface CommandScope {
1100
+ hook: TerraformCommandHook;
1101
+ root: string;
1102
+ upstream?: string;
1103
+ method: string;
1104
+ }
1105
+
1106
+ /**
1107
+ * The command scope of the step call that runs the engine (chant#4865). An
1108
+ * async-local store, so each root a wave runs at once (chant#4864) sees its
1109
+ * own, and the activities need no hook argument threaded through.
1110
+ */
1111
+ const commandScope = new AsyncLocalStorage<CommandScope>();
1112
+
1113
+ /**
1114
+ * Run `fn` with every engine command it runs going through `hook`, as
1115
+ * commands for `scope.root` (chant#4865). Inside another scope, a field this
1116
+ * one leaves out (`upstream`) is not kept from the outer.
1117
+ */
1118
+ export function withTerraformCommandHook<T>(hook: TerraformCommandHook | undefined, scope: Omit<CommandScope, "hook">, fn: () => Promise<T>): Promise<T> {
1119
+ if (!hook) return fn();
1120
+ return commandScope.run({ hook, ...scope }, fn);
1121
+ }
1122
+
1123
+ /** Run `fn` with the commands it runs marked as a read of `upstream`'s state for the scope's root (chant#4865). Outside a scope, `fn` as it is. */
1124
+ export function asUpstreamCommands<T>(upstream: string, fn: () => Promise<T>): Promise<T> {
1125
+ const scope = commandScope.getStore();
1126
+ return scope ? commandScope.run({ ...scope, upstream }, fn) : fn();
1127
+ }
1128
+
1129
+ /** The words of a command line the builders here wrote: plain words, and `quoteArg`'s single-quoted ones. */
1130
+ export function commandWords(line: string): string[] {
1131
+ const words: string[] = [];
1132
+ let word: string | undefined;
1133
+ for (let i = 0; i < line.length; i++) {
1134
+ const c = line[i]!;
1135
+ if (c === " ") {
1136
+ if (word !== undefined) words.push(word);
1137
+ word = undefined;
1138
+ } else if (c === "'") {
1139
+ const end = line.indexOf("'", i + 1);
1140
+ const stop = end < 0 ? line.length : end;
1141
+ word = (word ?? "") + line.slice(i + 1, stop);
1142
+ i = stop;
1143
+ } else if (c === "\\" && i + 1 < line.length) {
1144
+ word = (word ?? "") + line[++i];
1145
+ } else {
1146
+ word = (word ?? "") + c;
1147
+ }
1148
+ }
1149
+ if (word !== undefined) words.push(word);
1150
+ return words;
1151
+ }
1152
+
1045
1153
  /** Run `cmd` in `dir`, forwarding the signal so an abort kills the child. */
1154
+ function runPlain(cmd: string, dir: string, env: Record<string, string>, signal?: AbortSignal, unset: readonly string[] = []): Promise<{ stdout: string; stderr: string }> {
1155
+ const merged: NodeJS.ProcessEnv = { ...process.env, ...env };
1156
+ for (const name of unset) delete merged[name];
1157
+ return execAsync(cmd, { cwd: dir, env: merged, signal, maxBuffer: MAX_BUFFER });
1158
+ }
1159
+
1160
+ /**
1161
+ * Run `cmd` in `dir` ({@link runPlain}), through the command hook of the
1162
+ * step call it runs in (chant#4865): the hook's variables over `env`, still
1163
+ * less `unset`, and its `after` with the exit code, time and output.
1164
+ */
1046
1165
  async function run(
1047
1166
  cmd: string,
1048
1167
  dir: string,
@@ -1050,9 +1169,40 @@ async function run(
1050
1169
  signal?: AbortSignal,
1051
1170
  unset: readonly string[] = [],
1052
1171
  ): Promise<{ stdout: string; stderr: string }> {
1053
- const merged: NodeJS.ProcessEnv = { ...process.env, ...env };
1054
- for (const name of unset) delete merged[name];
1055
- return execAsync(cmd, { cwd: dir, env: merged, signal, maxBuffer: MAX_BUFFER });
1172
+ const scope = commandScope.getStore();
1173
+ if (!scope) return runPlain(cmd, dir, env, signal, unset);
1174
+ const words = commandWords(cmd);
1175
+ const args = words.slice(1);
1176
+ const command: TerraformCommand = {
1177
+ root: scope.root,
1178
+ ...(scope.upstream !== undefined ? { upstream: scope.upstream } : {}),
1179
+ method: scope.method,
1180
+ binary: words[0] ?? "",
1181
+ name: args.find((a) => !a.startsWith("-")) ?? "",
1182
+ args,
1183
+ line: cmd,
1184
+ cwd: dir,
1185
+ env: { ...env },
1186
+ };
1187
+ const given = (await scope.hook(command)) ?? {};
1188
+ const start = performance.now();
1189
+ const took = () => (performance.now() - start) / 1000;
1190
+ let out: { stdout: string; stderr: string };
1191
+ try {
1192
+ out = await runPlain(cmd, dir, given.env ? { ...env, ...given.env } : env, signal, unset);
1193
+ } catch (err) {
1194
+ const failure = err as ExecFailure;
1195
+ const seconds = took();
1196
+ await given.after?.({
1197
+ code: typeof failure.code === "number" ? failure.code : null,
1198
+ seconds,
1199
+ stdout: failure.stdout ?? "",
1200
+ stderr: failure.stderr ?? (err instanceof Error ? err.message : String(err)),
1201
+ });
1202
+ throw err;
1203
+ }
1204
+ await given.after?.({ code: 0, seconds: took(), stdout: out.stdout, stderr: out.stderr });
1205
+ return out;
1056
1206
  }
1057
1207
 
1058
1208
  /**
@@ -125,9 +125,10 @@ describe("compose and state give one verdict per root (chant#4478)", () => {
125
125
 
126
126
  describe("the parts of the verdict", () => {
127
127
  test("the lockable list is the one LOCKS spells", () => {
128
- expect(LOCKABLE_BACKENDS).toEqual(["s3", "gcs", "azurerm", "local"]);
129
- expect(LOCKS).toBe("chant locks and writes s3 (with use_lockfile = true), gcs, azurerm and local states");
130
- for (const type of LOCKABLE_BACKENDS) expect(lockRefusal({ backend: { type, config: { use_lockfile: true } } })).toBeUndefined();
128
+ expect(LOCKABLE_BACKENDS).toEqual(["s3", "gcs", "azurerm", "local", "http"]);
129
+ expect(LOCKS).toBe("chant locks and writes s3 (with use_lockfile = true), gcs, azurerm, local and GitLab-managed http states");
130
+ const gitlab = "https://gitlab.example.test/api/v4/projects/7/terraform/state/net";
131
+ for (const type of LOCKABLE_BACKENDS) expect(lockRefusal({ backend: { type, config: { use_lockfile: true, address: gitlab } } })).toBeUndefined();
131
132
  });
132
133
 
133
134
  test("TF_CLI_ARGS and TF_CLI_ARGS_init -backend-config flags, pairs and files, later over earlier", () => {
@@ -104,11 +104,13 @@ describe("a state chant does not lock", () => {
104
104
  });
105
105
 
106
106
  it("is any other backend, named by its type", () => {
107
- for (const type of ["pg", "kubernetes", "consul", "http", "remote", "cos"]) {
107
+ for (const type of ["pg", "kubernetes", "consul", "remote", "cos"]) {
108
108
  const o = stateObject(initialised(type, {}), ENV);
109
109
  expect(isRefused(o)).toBe(true);
110
110
  expect(o).toMatchObject({ backend: type, refused: "backend", reason: expect.stringContaining(`backend is ${type}`) });
111
111
  }
112
+ // An http backend is locked at a GitLab project's state API only (#4793).
113
+ expect(stateObject(initialised("http", {}), ENV)).toMatchObject({ backend: "http", refused: "backend", reason: expect.stringContaining("http backend names no address") });
112
114
  });
113
115
 
114
116
  it("is an s3 backend without its bucket or key, or without credentials", () => {
@@ -6,9 +6,15 @@
6
6
  * `-backend-config` file or the job's flags supplied it. Nothing here reads
7
7
  * a state's contents.
8
8
  *
9
- * chant locks and writes four backends: s3 with `use_lockfile`, gcs, azurerm
10
- * and local. Every other backend, and a root with a `cloud` block, comes back
11
- * as a {@link StateRefusal} naming why, and is never locked.
9
+ * chant locks and writes five backends: s3 with `use_lockfile`, gcs, azurerm,
10
+ * local, and an http backend whose address is a GitLab project's state API
11
+ * (./gitlab.ts, #4793). Every other backend, and a root with a `cloud` block,
12
+ * comes back as a {@link StateRefusal} naming why, and is never locked.
13
+ *
14
+ * A read of the state's versions holds no lock, so it is not held to the lock
15
+ * verdict: {@link readableStateObject} reads an s3 backend without
16
+ * `use_lockfile` all the same, and goes by what `init` recorded alone
17
+ * (./versions.ts, #4793).
12
18
  *
13
19
  * This is also the one place that answers which backend a root has and
14
20
  * whether chant can lock it (chant#4478). Before `init` the answer comes
@@ -25,8 +31,10 @@
25
31
  */
26
32
  import { existsSync, readFileSync } from "node:fs";
27
33
  import { isAbsolute, join } from "node:path";
34
+ import type { StoreHints } from "@intentius/chant/object-store";
28
35
  import { AZURE_AUTHORITY, type AzureOidc } from "./azure-blob";
29
36
  import { GCS_ENDPOINT, type GcsTarget } from "./gcs";
37
+ import { gitlabState, isGitLabAddress, shownUrl, type GitLabState } from "./gitlab";
30
38
  import { s3FromEnv, type S3Target } from "./s3";
31
39
  import { isJsonConfigFile, listConfigFilesSafe } from "../hcl/files";
32
40
  import { blockBody, jsonBlocks, rootTexts } from "../compose/hcl";
@@ -70,8 +78,14 @@ export interface AzureState {
70
78
  key: string;
71
79
  /** The backend snapshots the blob before each write (`snapshot = true`). */
72
80
  snapshot: boolean;
73
- /** The account's blob endpoint. */
74
- endpoint: string;
81
+ /** The account's blob endpoint, when the cloud is one chant knows; else `metadataHost` names it. */
82
+ endpoint?: string;
83
+ /**
84
+ * The host of the cloud's metadata (`metadata_host`), whose storage suffix
85
+ * names the endpoint, for a cloud other than public, china or
86
+ * usgovernment. The store reads it when it first calls the account (#4793).
87
+ */
88
+ metadataHost?: string;
75
89
  auth: AzureAuth;
76
90
  }
77
91
 
@@ -90,29 +104,48 @@ export interface StateRefusal {
90
104
  reason: string;
91
105
  }
92
106
 
93
- /** Where a root's state lives, or why chant does not lock it. */
94
- export type StateObject = S3State | GcsState | AzureState | LocalState | StateRefusal;
107
+ /** Where a root's state lives, or why chant does not lock it. An http backend's is a GitLab-managed state (./gitlab.ts). */
108
+ export type StateObject = S3State | GcsState | AzureState | LocalState | GitLabState | StateRefusal;
95
109
 
96
110
  /** A state in a bucket or a container. */
97
111
  export type StoredState = S3State | GcsState | AzureState;
98
112
 
99
113
  /** A state chant locks and writes. */
100
- export type LockableState = StoredState | LocalState;
114
+ export type LockableState = StoredState | LocalState | GitLabState;
101
115
 
102
116
  export const isRefused = (o: StateObject): o is StateRefusal => "refused" in o;
103
117
 
104
118
  /** Whether the state is in a bucket or a container: s3, gcs or azurerm. */
105
- export const isStored = (o: StateObject): o is StoredState => !isRefused(o) && o.backend !== "local";
119
+ export const isStored = (o: StateObject): o is StoredState => !isRefused(o) && o.backend !== "local" && o.backend !== "http";
120
+
121
+ /** Whether the state is a GitLab-managed one, an http backend's (#4793). */
122
+ export const isGitLabState = (o: StateObject): o is GitLabState => !isRefused(o) && o.backend === "http";
106
123
 
107
- /** The backend types whose state chant locks and writes itself, s3 only with `use_lockfile = true` (#4437). The one list (chant#4478). */
108
- export const LOCKABLE_BACKENDS: readonly string[] = ["s3", "gcs", "azurerm", "local"];
124
+ /**
125
+ * The backend types whose state chant locks and writes itself (#4437), s3
126
+ * only with `use_lockfile = true` and http only at a GitLab project's state
127
+ * API (#4793). The one list (chant#4478).
128
+ */
129
+ export const LOCKABLE_BACKENDS: readonly string[] = ["s3", "gcs", "azurerm", "local", "http"];
109
130
 
110
131
  /** What a refusal says chant locks, spelled from {@link LOCKABLE_BACKENDS}. */
111
132
  export const LOCKS = (() => {
112
- const names = LOCKABLE_BACKENDS.map((b) => (b === "s3" ? "s3 (with use_lockfile = true)" : b));
133
+ const names = LOCKABLE_BACKENDS.map((b) => (b === "s3" ? "s3 (with use_lockfile = true)" : b === "http" ? "GitLab-managed http" : b));
113
134
  return `chant locks and writes ${names.slice(0, -1).join(", ")} and ${names.at(-1)} states`;
114
135
  })();
115
136
 
137
+ /**
138
+ * A product's words for the messages a state's credentials refusal gives: what
139
+ * the bucket and role are called, the STS session name, and the keys that
140
+ * give the job an identity (#4793). Default chant's.
141
+ */
142
+ export interface StateStoreWords {
143
+ setting?: string;
144
+ roleSetting?: string;
145
+ sessionName?: string;
146
+ hints?: StoreHints;
147
+ }
148
+
116
149
  const str = (v: unknown): string | undefined => (typeof v === "string" && v !== "" ? v : undefined);
117
150
 
118
151
  /** The root's data dir: `TF_DATA_DIR` (relative to the root, as the binary run with `-chdir` reads it), else `.terraform`. */
@@ -342,13 +375,17 @@ export function readBackend(dir: string, input: ReadBackendInput = {}): BackendR
342
375
  * Whether chant can lock the root's state, from one {@link BackendReading}:
343
376
  * undefined when it can, else the refusal and why. The one verdict the
344
377
  * composition's `backend` fallback (#4438) and the state refusals (#4437)
345
- * both give (chant#4478).
378
+ * both give (chant#4478). An http backend's address is the configuration's,
379
+ * else `env`'s TF_HTTP_ADDRESS, as the binary reads it.
346
380
  */
347
- export function lockRefusal(reading: BackendReading): StateRefusal | undefined {
381
+ export function lockRefusal(reading: BackendReading, env: NodeJS.ProcessEnv = {}): StateRefusal | undefined {
348
382
  const b = reading.backend;
349
383
  if (reading.disagreement) return { backend: b.type, refused: "disagree", reason: `${reading.disagreement}, so chant cannot tell which state to lock; run init again with the configuration the root means; ${LOCKS}` };
350
384
  if (b.type === "cloud") return { backend: b.type, refused: "cloud", reason: `${CLOUD_REASON}; ${LOCKS}` };
351
385
  if (!LOCKABLE_BACKENDS.includes(b.type)) return { backend: b.type, refused: "backend", reason: `the root's backend is ${b.type}; ${LOCKS}` };
386
+ if (b.type === "http" && !isGitLabAddress(str(b.config.address) ?? str(env.TF_HTTP_ADDRESS))) {
387
+ return { backend: "http", refused: "backend", reason: `the root's http backend ${httpAddressNamed(b, env)}; ${LOCKS}` };
388
+ }
352
389
  if (b.type === "s3" && b.config.use_lockfile !== true && b.config.use_lockfile !== "true") {
353
390
  return { backend: "s3", refused: "no-lockfile", reason: `the s3 backend takes no lock file (use_lockfile = true is unset), so chant cannot hold its lock; ${LOCKS}` };
354
391
  }
@@ -375,17 +412,47 @@ export function stateObject(
375
412
  ...(flags.backendConfig ? { backendConfig: flags.backendConfig } : {}),
376
413
  ...(flags.backendConfigFiles ? { backendConfigFiles: flags.backendConfigFiles } : {}),
377
414
  });
378
- const refusal = lockRefusal(reading);
415
+ const refusal = lockRefusal(reading, env);
379
416
  if (refusal) return refusal;
380
- const chosen = reading.backend;
381
- const ws = workspaceOf(dir, env);
417
+ return backendObject(reading.backend, workspaceOf(dir, env), env);
418
+ }
419
+
420
+ /** How an http backend's address reads in a refusal: which address, or that it names none. */
421
+ function httpAddressNamed(b: InitialisedBackend, env: NodeJS.ProcessEnv): string {
422
+ const address = str(b.config.address) ?? str(env.TF_HTTP_ADDRESS);
423
+ return address ? `address ${shownUrl(address)} is not a GitLab project's state API (.../projects/<id>/terraform/state/<name>)` : "names no address";
424
+ }
425
+
426
+ /**
427
+ * Where the root's state is for a read of its versions (#4793), from what
428
+ * `init` recorded (`backend` stands in for it): a read holds no lock, so the
429
+ * lock verdict's refusals that are about holding one do not apply. An s3
430
+ * backend without `use_lockfile` is read all the same (`lockfile: false`),
431
+ * and a root's code is not compared with the record, since the record is
432
+ * where the binary wrote. A `cloud` backend and any type chant reads no
433
+ * versions of is refused (`backend`). No backend recorded reads as a local
434
+ * one. `words` names the product's settings in a credentials refusal.
435
+ */
436
+ export function readableStateObject(dir: string, env: NodeJS.ProcessEnv = process.env, backend: InitialisedBackend | undefined = initialisedBackend(dir, env), words: StateStoreWords = {}): StateObject {
437
+ const b = backend ?? { type: "local", config: {} };
438
+ if (b.type === "http" && !gitlabState(b.config, env)) return { backend: "http", refused: "backend", reason: `the root's http backend ${httpAddressNamed(b, env)}; ${READS}` };
439
+ if (!LOCKABLE_BACKENDS.includes(b.type)) return { backend: b.type, refused: "backend", reason: `the root's backend is ${b.type}; ${READS}` };
440
+ return backendObject(b, workspaceOf(dir, env), env, words);
441
+ }
442
+
443
+ /** What a read refusal says chant reads. */
444
+ const READS = "chant reads the state of s3, gcs, azurerm, local and GitLab-managed http backends";
445
+
446
+ /** The state a backend of a type chant reads names, in workspace `ws`, or why it names none. */
447
+ function backendObject(chosen: InitialisedBackend, ws: string, env: NodeJS.ProcessEnv, words: StateStoreWords = {}): StateObject {
382
448
  if (chosen.type === "local") {
383
449
  const c = chosen.config;
384
450
  const path = ws === "default" ? (str(c.path) ?? "terraform.tfstate") : join(str(c.workspace_dir) ?? "terraform.tfstate.d", ws, "terraform.tfstate");
385
451
  return { backend: "local", path };
386
452
  }
387
- if (chosen.type === "gcs") return gcsObject(chosen.config, ws, env);
388
- if (chosen.type === "azurerm") return azureObject(chosen.config, ws, env);
453
+ if (chosen.type === "http") return gitlabState(chosen.config, env) ?? { backend: "http", refused: "backend", reason: `the root's http backend ${httpAddressNamed(chosen, env)}; ${LOCKS}` };
454
+ if (chosen.type === "gcs") return gcsObject(chosen.config, ws, env, words);
455
+ if (chosen.type === "azurerm") return azureObject(chosen.config, ws, env, words);
389
456
  const c = chosen.config;
390
457
  const bucket = str(c.bucket);
391
458
  const key = str(c.key);
@@ -398,7 +465,7 @@ export function stateObject(
398
465
  const jobEnv = { ...env, AWS_REGION: region, ...(access && secret ? { AWS_ACCESS_KEY_ID: access, AWS_SECRET_ACCESS_KEY: secret, AWS_SESSION_TOKEN: str(c.token) ?? "" } : {}) };
399
466
  let target: S3Target;
400
467
  try {
401
- target = s3FromEnv({ bucket, ...(endpoint ? { endpoint } : {}) }, jobEnv);
468
+ target = s3FromEnv({ bucket, ...(endpoint ? { endpoint } : {}) }, jobEnv, words);
402
469
  } catch (e) {
403
470
  return { backend: "s3", refused: "credentials", reason: `the job has no credentials to read s3://${bucket}: ${(e as Error).message}` };
404
471
  }
@@ -408,7 +475,7 @@ export function stateObject(
408
475
  key: s3StateKey(key, ws, str(c.workspace_key_prefix)),
409
476
  region,
410
477
  ...(endpoint ? { endpoint: endpoint.replace(/\/+$/, "") } : {}),
411
- lockfile: true,
478
+ lockfile: c.use_lockfile === true || c.use_lockfile === "true",
412
479
  target,
413
480
  };
414
481
  }
@@ -423,7 +490,7 @@ const gcsEndpoint = (e: string): string => e.replace(/\/+$/, "").replace(/\/stor
423
490
  * JSON), GOOGLE_BACKEND_CREDENTIALS, GOOGLE_CREDENTIALS, and
424
491
  * GOOGLE_APPLICATION_CREDENTIALS.
425
492
  */
426
- function gcsObject(c: Record<string, unknown>, ws: string, env: NodeJS.ProcessEnv): StateObject {
493
+ function gcsObject(c: Record<string, unknown>, ws: string, env: NodeJS.ProcessEnv, words: StateStoreWords): StateObject {
427
494
  const bucket = str(c.bucket);
428
495
  if (!bucket) return { backend: "gcs", refused: "config", reason: "the gcs backend's bucket is not in the configuration init recorded" };
429
496
  const raw = str(c.prefix) ?? "";
@@ -437,7 +504,10 @@ function gcsObject(c: Record<string, unknown>, ws: string, env: NodeJS.ProcessEn
437
504
  if (token) target = { ...where, accessToken: token };
438
505
  else if (creds) target = creds.trim().startsWith("{") ? { ...where, credentialsJson: creds } : { ...where, credentialsFile: creds };
439
506
  else if (env.GOOGLE_APPLICATION_CREDENTIALS) target = { ...where, credentialsFile: env.GOOGLE_APPLICATION_CREDENTIALS };
440
- else return { backend: "gcs", refused: "credentials", reason: `the job has no credentials to read gs://${bucket}: set GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CREDENTIALS or GOOGLE_OAUTH_ACCESS_TOKEN` };
507
+ else {
508
+ const how = words.hints?.gcp ? `give the job ${words.hints.gcp} (it sets GOOGLE_APPLICATION_CREDENTIALS), or set GOOGLE_CREDENTIALS or GOOGLE_OAUTH_ACCESS_TOKEN` : "set GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CREDENTIALS or GOOGLE_OAUTH_ACCESS_TOKEN";
509
+ return { backend: "gcs", refused: "credentials", reason: `the job has no credentials to read gs://${bucket}: ${how}` };
510
+ }
441
511
  return { backend: "gcs", bucket, key: `${prefix}${ws}.tfstate`, lock: `${prefix}${ws}.tflock`, target };
442
512
  }
443
513
 
@@ -452,19 +522,20 @@ const CLOUD_ENDPOINTS: Record<string, { storage: string; authority: string }> =
452
522
  * An azurerm backend's state: the blob `key` in `container_name` of
453
523
  * `storage_account_name`, `<key>env:<workspace>` in another workspace, with
454
524
  * the credentials the backend would use: `access_key` (ARM_ACCESS_KEY),
455
- * `sas_token` (ARM_SAS_TOKEN), else the job's OIDC identity. An
456
- * `environment` other than public, china or usgovernment is refused: its
457
- * storage suffix would need the metadata lookup terragucci makes and chant
458
- * does not.
525
+ * `sas_token` (ARM_SAS_TOKEN), else the job's OIDC identity. A backend that
526
+ * names `metadata_host` (ARM_METADATA_HOSTNAME) gets its endpoint from that
527
+ * cloud's metadata, which the store reads (#4793); an `environment` other
528
+ * than public, china or usgovernment without one is refused.
459
529
  */
460
- function azureObject(c: Record<string, unknown>, ws: string, env: NodeJS.ProcessEnv): StateObject {
530
+ function azureObject(c: Record<string, unknown>, ws: string, env: NodeJS.ProcessEnv, words: StateStoreWords): StateObject {
461
531
  const account = str(c.storage_account_name);
462
532
  const container = str(c.container_name);
463
533
  const base = str(c.key);
464
534
  if (!account || !container || !base) return { backend: "azurerm", refused: "config", reason: "the azurerm backend's storage_account_name, container_name or key is not in the configuration init recorded" };
465
535
  const key = ws === "default" ? base : `${base}env:${ws}`;
466
536
  const cloud = CLOUD_ENDPOINTS[str(c.environment) ?? env.ARM_ENVIRONMENT ?? "public"];
467
- if (!cloud) return { backend: "azurerm", refused: "config", reason: `the azurerm backend's environment ${str(c.environment) ?? env.ARM_ENVIRONMENT} is not public, china or usgovernment` };
537
+ const metadataHost = str(c.metadata_host) ?? env.ARM_METADATA_HOSTNAME ?? env.ARM_METADATA_HOST;
538
+ if (!cloud && !metadataHost) return { backend: "azurerm", refused: "config", reason: `the azurerm backend's environment ${str(c.environment) ?? env.ARM_ENVIRONMENT} is not public, china or usgovernment, and it names no metadata_host` };
468
539
  const accessKey = str(c.access_key) ?? env.ARM_ACCESS_KEY;
469
540
  const sas = str(c.sas_token) ?? env.ARM_SAS_TOKEN;
470
541
  const tenantId = str(c.tenant_id) ?? env.ARM_TENANT_ID;
@@ -473,15 +544,19 @@ function azureObject(c: Record<string, unknown>, ws: string, env: NodeJS.Process
473
544
  let auth: AzureAuth;
474
545
  if (accessKey) auth = { accountKey: accessKey };
475
546
  else if (sas) auth = { sas };
476
- else if (tenantId && clientId && tokenFile) auth = { oidc: { tenantId, clientId, tokenFile, authority: (env.AZURE_AUTHORITY_HOST || cloud.authority).replace(/\/+$/, "") } };
477
- else return { backend: "azurerm", refused: "credentials", reason: `the job has no credentials to read the container ${container} of ${account}: set ARM_ACCESS_KEY, ARM_SAS_TOKEN, or ARM_TENANT_ID, ARM_CLIENT_ID and ARM_OIDC_TOKEN_FILE_PATH` };
478
- return { backend: "azurerm", account, container, key, snapshot: c.snapshot === true || env.ARM_SNAPSHOT === "true", endpoint: `https://${account}.blob.${cloud.storage}`, auth };
547
+ else if (tenantId && clientId && tokenFile) auth = { oidc: { tenantId, clientId, tokenFile, authority: (env.AZURE_AUTHORITY_HOST || cloud?.authority || AZURE_AUTHORITY).replace(/\/+$/, "") } };
548
+ else {
549
+ const how = words.hints?.azure ? `give the job ${words.hints.azure} (it sets ARM_TENANT_ID, ARM_CLIENT_ID and ARM_OIDC_TOKEN_FILE_PATH), or set ARM_ACCESS_KEY` : "set ARM_ACCESS_KEY, ARM_SAS_TOKEN, or ARM_TENANT_ID, ARM_CLIENT_ID and ARM_OIDC_TOKEN_FILE_PATH";
550
+ return { backend: "azurerm", refused: "credentials", reason: `the job has no credentials to read the container ${container} of ${account}: ${how}` };
551
+ }
552
+ return { backend: "azurerm", account, container, key, snapshot: c.snapshot === true || env.ARM_SNAPSHOT === "true", ...(metadataHost ? { metadataHost } : { endpoint: `https://${account}.blob.${cloud!.storage}` }), auth };
479
553
  }
480
554
 
481
- /** `s3://<bucket>/<key>`, `gs://<bucket>/<key>`, `az://<account>/<container>/<key>`, or the local file's path; undefined for a refusal. */
555
+ /** `s3://<bucket>/<key>`, `gs://<bucket>/<key>`, `az://<account>/<container>/<key>`, a GitLab state's address without its credentials, or the local file's path; undefined for a refusal. */
482
556
  export function stateLocation(o: StateObject): string | undefined {
483
557
  if (isRefused(o)) return undefined;
484
558
  if (o.backend === "local") return o.path;
559
+ if (o.backend === "http") return shownUrl(o.address);
485
560
  if (o.backend === "gcs") return `gs://${o.bucket}/${o.key}`;
486
561
  if (o.backend === "azurerm") return `az://${o.account}/${o.container}/${o.key}`;
487
562
  return `s3://${o.bucket}/${o.key}`;
@@ -172,7 +172,7 @@ export interface GitLabStateStore extends StateStore {
172
172
  * reads the state and keeps those two fields only.
173
173
  */
174
174
  serial(): Promise<{ serial: number; lineage?: string } | undefined>;
175
- /** Whether GitLab keeps the version with this serial: a HEAD, so no state is read. */
175
+ /** Whether GitLab keeps the version with this serial: a HEAD, so no state is read. An id that is not a serial is none. */
176
176
  hasVersion(serial: string | number): Promise<boolean>;
177
177
  /** One version of the state, or undefined when GitLab keeps no version with that serial. */
178
178
  readVersion(serial: string | number): Promise<string | undefined>;
@@ -248,23 +248,36 @@ export function gitlabStore(s: GitLabState, fetchFn: GitLabFetch = defaultFetch,
248
248
  if (!r.ok) throw answered("a write of", url, r.status, text);
249
249
  };
250
250
 
251
+ /** The serial and lineage of the state GitLab holds now, read from the state, or undefined when it holds none. */
252
+ const serialNow = async (): Promise<{ serial: number; lineage?: string } | undefined> => {
253
+ const text = await read(s.address);
254
+ if (text === undefined) return undefined;
255
+ let doc: { serial?: unknown; lineage?: unknown };
256
+ try {
257
+ doc = JSON.parse(text) as typeof doc;
258
+ } catch {
259
+ throw new StoreError(`GitLab answered ${location} with no state`);
260
+ }
261
+ if (typeof doc.serial !== "number") throw new StoreError(`the state at ${location} has no serial`);
262
+ return { serial: doc.serial, ...(typeof doc.lineage === "string" ? { lineage: doc.lineage } : {}) };
263
+ };
264
+
251
265
  return {
252
266
  backend: "http",
253
267
  location,
254
268
  lockLocation: shownUrl(s.lockAddress ?? s.address),
255
- serial: async () => {
256
- const text = await read(s.address);
257
- if (text === undefined) return undefined;
258
- let doc: { serial?: unknown; lineage?: unknown };
259
- try {
260
- doc = JSON.parse(text) as typeof doc;
261
- } catch {
262
- throw new StoreError(`GitLab answered ${location} with no state`);
263
- }
264
- if (typeof doc.serial !== "number") throw new StoreError(`the state at ${location} has no serial`);
265
- return { serial: doc.serial, ...(typeof doc.lineage === "string" ? { lineage: doc.lineage } : {}) };
269
+ serial: serialNow,
270
+ // The version id of a GitLab-managed state is its serial (#4793).
271
+ version: async () => {
272
+ const now = await serialNow();
273
+ return now ? { exists: true, versionId: String(now.serial) } : { exists: false };
274
+ },
275
+ isAt: async (id) => {
276
+ const now = await serialNow();
277
+ return now !== undefined && String(now.serial) === id;
266
278
  },
267
279
  hasVersion: async (serial) => {
280
+ if (!/^\d+$/.test(String(serial))) return false;
268
281
  const url = gitlabVersionUrl(s, serial);
269
282
  const r = await fetchFn(url, { method: "HEAD", headers: headers(s) });
270
283
  if (r.status === 404) return false;
@@ -15,3 +15,4 @@ export { S3Client, s3FromEnv, type S3Target } from "./s3";
15
15
  export { GcsClient, type GcsTarget } from "./gcs";
16
16
  export { AzureBlobClient, type AzureTarget } from "./azure-blob";
17
17
  export * from "./versions";
18
+ export * from "./source";
package/src/state/s3.ts CHANGED
@@ -5,7 +5,7 @@
5
5
  * no static keys, a role is assumed with the job's OIDC token through STS
6
6
  * AssumeRoleWithWebIdentity.
7
7
  */
8
- import { s3FromEnv as coreS3FromEnv, type S3Target } from "@intentius/chant/object-store";
8
+ import { s3FromEnv as coreS3FromEnv, type S3Target, type StoreHints } from "@intentius/chant/object-store";
9
9
 
10
10
  export { assumeRoleWithWebIdentity, S3Client, sign, type S3Credentials, type S3Location, type S3Target, type S3WebIdentity } from "@intentius/chant/object-store";
11
11
 
@@ -14,8 +14,9 @@ export { assumeRoleWithWebIdentity, S3Client, sign, type S3Credentials, type S3L
14
14
  * first match wins: static keys in `AWS_ACCESS_KEY_ID` and
15
15
  * `AWS_SECRET_ACCESS_KEY`; `AWS_ROLE_ARN` assumed with the token in
16
16
  * `AWS_WEB_IDENTITY_TOKEN_FILE`, in a session named `chant-state` unless
17
- * AWS_ROLE_SESSION_NAME names one.
17
+ * AWS_ROLE_SESSION_NAME names one. `words` puts a product's names in the
18
+ * session and the messages (#4793).
18
19
  */
19
- export function s3FromEnv(where: { bucket: string; endpoint?: string }, env: NodeJS.ProcessEnv = process.env): S3Target {
20
- return coreS3FromEnv({ ...where, sessionName: "chant-state", setting: "the state bucket" }, env);
20
+ export function s3FromEnv(where: { bucket: string; endpoint?: string }, env: NodeJS.ProcessEnv = process.env, words: { setting?: string; roleSetting?: string; sessionName?: string; hints?: StoreHints } = {}): S3Target {
21
+ return coreS3FromEnv({ sessionName: "chant-state", setting: "the state bucket", ...words, ...where }, env);
21
22
  }