@intentius/chant-lexicon-terraform 0.124.85 → 0.124.87

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
@@ -0,0 +1,289 @@
1
+ /**
2
+ * Where a backend move (#4806, `../state-migration.ts`) reads a state that no
3
+ * backend block of the root can reach with an override file: a workspace of
4
+ * HCP Terraform or another service that speaks its API (a `remote` backend
5
+ * or a `cloud` block), and a state file exported from a platform that keeps
6
+ * state its own way.
7
+ *
8
+ * A workspace's state is read over the API the stock `remote` backend and
9
+ * `cloud` block use: service discovery at
10
+ * `https://<hostname>/.well-known/terraform.json` gives the `tfe.v2` base,
11
+ * then the workspace by organization and name, its current state version
12
+ * and that version's download URL. The token is the one Terraform and
13
+ * OpenTofu use for the host: `TF_TOKEN_<host>`, else a `credentials` block
14
+ * in the CLI config, else `~/.terraform.d/credentials.tfrc.json`, read by
15
+ * chant core's reader (`@intentius/chant/terraform/credentials`, #4563). A
16
+ * migration holds the workspace's lock while it writes, as it holds an S3
17
+ * state's lock file, and the workspace's state is left where it was.
18
+ *
19
+ * `tfeClient` is the one client of that API, which a product's importers of
20
+ * TFE and Scalr workspaces use too.
21
+ *
22
+ * Lifted from terragucci's `state-source.ts`, so terragucci deletes it.
23
+ */
24
+ import { existsSync, readFileSync } from "node:fs";
25
+ import { isAbsolute, join } from "node:path";
26
+ import { terraformCredential } from "@intentius/chant/terraform/credentials";
27
+ import type { StoreFetch } from "./object-store";
28
+
29
+ /** A source cannot be read: its config, its answer, or its token. Nothing was written. */
30
+ export class StateSourceError extends Error {
31
+ constructor(message: string) {
32
+ super(message);
33
+ this.name = "StateSourceError";
34
+ }
35
+ }
36
+
37
+ /** The backends a move reads from without the binary: a TFE-API workspace, and a state file. */
38
+ export const EXTERNAL_BACKENDS = ["remote", "cloud", "file"];
39
+
40
+ /** A state as the source gives it: its JSON, and the source's version id when it keeps versions. */
41
+ export interface ReadState {
42
+ text: string;
43
+ version?: string;
44
+ }
45
+
46
+ /** A source of a backend move that the job reads itself. */
47
+ export interface ExternalSource {
48
+ backend: string;
49
+ /** Where the state is, as the record and the digest name it. */
50
+ location: string;
51
+ read(): Promise<ReadState | null>;
52
+ /** Take the source's lock; returns its release. Throws StateSourceError when another holds it. */
53
+ lock?(reason: string): Promise<() => Promise<void>>;
54
+ }
55
+
56
+ const DEFAULT_HOST = "app.terraform.io";
57
+ const HOST = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:\d+)?$/i;
58
+
59
+ /** Problems with the config of an external source, as `<at>.from.config...` lines. */
60
+ export function externalProblems(at: string, backend: string, config: Record<string, unknown>): string[] {
61
+ const p: string[] = [];
62
+ if (backend === "file") {
63
+ for (const k of Object.keys(config)) if (k !== "path") p.push(`${at}.from.config.${k} is not a key; a file source has path`);
64
+ if (typeof config.path !== "string" || !config.path.trim()) p.push(`${at}.from.config.path must name the state file`);
65
+ else if (!isAbsolute(config.path) && config.path.split("/").includes("..")) p.push(`${at}.from.config.path must be in the repo or an absolute path, not ${config.path}`);
66
+ return p;
67
+ }
68
+ for (const k of Object.keys(config)) {
69
+ if (k === "token") p.push(`${at}.from.config.token: a token does not belong in the repo; the job reads TF_TOKEN_<host> or credentials.tfrc.json`);
70
+ else if (!["hostname", "organization", "workspaces"].includes(k)) p.push(`${at}.from.config.${k} is not a key; a ${backend} source has hostname, organization and workspaces`);
71
+ }
72
+ if (config.hostname !== undefined && (typeof config.hostname !== "string" || !HOST.test(config.hostname))) p.push(`${at}.from.config.hostname must be a host name, such as ${DEFAULT_HOST}`);
73
+ if (typeof config.organization !== "string" || !config.organization) p.push(`${at}.from.config.organization must name the organization`);
74
+ const ws = config.workspaces && typeof config.workspaces === "object" && !Array.isArray(config.workspaces) ? (config.workspaces as Record<string, unknown>) : undefined;
75
+ if (!ws || typeof ws.name !== "string" || !ws.name) p.push(`${at}.from.config.workspaces.name must name the one workspace whose state moves`);
76
+ for (const k of Object.keys(ws ?? {})) if (k !== "name") p.push(`${at}.from.config.workspaces.${k}: a move reads one workspace, named by workspaces.name`);
77
+ return p;
78
+ }
79
+
80
+ /** The variable Terraform and OpenTofu read a host's token from: dots to `_`, dashes to `__`. */
81
+ export const tokenVariable = (host: string): string => `TF_TOKEN_${host.replace(/-/g, "__").replace(/\./g, "_")}`;
82
+
83
+ /** A host's token and where it was found: a variable's name or a file's path, never the value. */
84
+ export interface HostToken {
85
+ token: string;
86
+ from: string;
87
+ }
88
+
89
+ /** The token for a host, found as Terraform and OpenTofu find it, by chant's reader. */
90
+ export async function tokenFor(host: string, env: NodeJS.ProcessEnv): Promise<HostToken | undefined> {
91
+ const got = terraformCredential(host, { env });
92
+ return got ? { token: got.token, from: got.from } : undefined;
93
+ }
94
+
95
+ /** What to set for a host's token: its variable, or a credentials block for a host whose port has no variable form. */
96
+ const tokenSetting = (host: string): string => (/:\d+$/.test(host) && !host.endsWith(":443") ? `a credentials "${host}" block in the CLI config` : tokenVariable(host.replace(/:443$/, "")));
97
+
98
+ /** The source a backend move reads from, when the job reads it itself; undefined for a backend read through the root. */
99
+ export function externalSource(repo: string, backend: string, config: Record<string, unknown>, env: NodeJS.ProcessEnv, fetchFn?: StoreFetch): ExternalSource | undefined {
100
+ if (backend === "file") return fileSource(repo, String(config.path));
101
+ if (backend !== "remote" && backend !== "cloud") return undefined;
102
+ const ws = config.workspaces as { name: string };
103
+ return workspaceSource(backend, typeof config.hostname === "string" ? config.hostname : DEFAULT_HOST, String(config.organization), ws.name, env, fetchFn);
104
+ }
105
+
106
+ /** A state file: in the repo, or at an absolute path the job can read. No versions, no lock; its digest is in the migration's. */
107
+ export function fileSource(repo: string, path: string): ExternalSource {
108
+ const full = isAbsolute(path) ? path : join(repo, path);
109
+ return {
110
+ backend: "file",
111
+ location: path,
112
+ read: async () => {
113
+ if (!existsSync(full)) return null;
114
+ const text = readFileSync(full, "utf-8");
115
+ let doc: { version?: unknown; lineage?: unknown; serial?: unknown; resources?: unknown };
116
+ try {
117
+ doc = JSON.parse(text);
118
+ } catch {
119
+ throw new StateSourceError(`${path} is not a state file: it is not JSON`);
120
+ }
121
+ if (doc.version !== 4 || typeof doc.lineage !== "string" || typeof doc.serial !== "number" || !Array.isArray(doc.resources)) throw new StateSourceError(`${path} is not a state file of format version 4 with a lineage, a serial and resources`);
122
+ return { text };
123
+ },
124
+ };
125
+ }
126
+
127
+ interface Json {
128
+ data?: { id?: string; attributes?: Record<string, unknown> };
129
+ }
130
+
131
+ /** A JSON:API resource as the TFE API and Scalr's give it. */
132
+ export interface ApiResource {
133
+ id: string;
134
+ type?: string;
135
+ attributes?: Record<string, unknown>;
136
+ relationships?: Record<string, { data?: { id?: string; type?: string } | { id?: string; type?: string }[] | null }>;
137
+ }
138
+
139
+ /** A call's answer: its status and body. */
140
+ export interface ApiAnswer {
141
+ status: number;
142
+ text: string;
143
+ }
144
+
145
+ /** A client of a host that speaks the TFE API: its token, discovery and JSON:API reads. */
146
+ export interface TfeClient {
147
+ host: string;
148
+ /** Whether a token was found for the host; never printed. */
149
+ hasToken(): Promise<boolean>;
150
+ call(url: string, method?: string, body?: string): Promise<ApiAnswer>;
151
+ /** The body of a 2xx answer as JSON; a 401 or 404 says what to check, naming `what`. */
152
+ json<T = Json>(what: string, r: ApiAnswer): T;
153
+ /** Where the token the calls send was found (a variable's name or a file's path), once a call has run. */
154
+ tokenFrom(): string | undefined;
155
+ /** The `tfe.v2` base that discovery names, ending in `/`. */
156
+ api(): Promise<string>;
157
+ /** Every resource of a list, page by page (`meta.pagination.next-page`). */
158
+ list(what: string, url: string): Promise<{ data: ApiResource[]; included: ApiResource[] }>;
159
+ }
160
+
161
+ /**
162
+ * A client of `host` over the TFE API, as the remote backend and the cloud
163
+ * block reach it: discovery at /.well-known/terraform.json, the token in
164
+ * `TF_TOKEN_<host>` or credentials.tfrc.json (else `tokenEnv`, when named),
165
+ * sent only to the host and the API discovery names. `location` heads every
166
+ * error.
167
+ */
168
+ export function tfeClient(host: string, location: string, env: NodeJS.ProcessEnv, fetchFn: StoreFetch = fetch as unknown as StoreFetch, tokenEnv?: string): TfeClient {
169
+ let found: Promise<HostToken | undefined> | undefined;
170
+ /** The token, looked up once on the first call: `TF_TOKEN_<host>` or the CLI's credentials, else `tokenEnv`. */
171
+ const lookup = (): Promise<HostToken | undefined> =>
172
+ (found ??= tokenFor(host, env).then((t) => t ?? (tokenEnv && env[tokenEnv] ? { token: env[tokenEnv]!, from: tokenEnv } : undefined)));
173
+ let held: HostToken | undefined;
174
+ const origin = `https://${host}`;
175
+ let base: string | undefined;
176
+ const call = async (url: string, method = "GET", body?: string): Promise<ApiAnswer> => {
177
+ held = await lookup();
178
+ const token = held?.token;
179
+ // The token goes to the host and the API discovery names (Spacelift's is on another host), as the binary sends it; never to a download elsewhere.
180
+ const sameHost = [host, base ? new URL(base).host : host].includes(new URL(url).host);
181
+ const headers: Record<string, string> = { accept: "application/vnd.api+json", ...(body ? { "content-type": "application/vnd.api+json" } : {}), ...(token && sameHost ? { authorization: `Bearer ${token}` } : {}) };
182
+ let r: Awaited<ReturnType<StoreFetch>>;
183
+ try {
184
+ r = await fetchFn(url, { method, headers, ...(body ? { body } : {}) });
185
+ } catch (e) {
186
+ const cause = (e as Error & { cause?: { message?: string } }).cause?.message;
187
+ throw new StateSourceError(`${location}: ${method} ${new URL(url).pathname} failed: ${(e as Error).message}${cause ? ` (${cause})` : ""}`);
188
+ }
189
+ return { status: r.status, text: await r.text() };
190
+ };
191
+ const tokenHint = (): string => (held ? `the token in ${held.from} may not read it` : `there is no token for ${host}: set ${tokenSetting(host)}${tokenEnv ? ` or ${tokenEnv}` : ""}`);
192
+ const json = <T = Json>(what: string, r: ApiAnswer): T => {
193
+ if (r.status === 401 || r.status === 404) throw new StateSourceError(`${location}: ${what} answered ${r.status}; ${tokenHint()}`);
194
+ if (r.status >= 300) throw new StateSourceError(`${location}: ${what} answered ${r.status}: ${r.text.slice(0, 200)}`);
195
+ try {
196
+ return JSON.parse(r.text) as T;
197
+ } catch {
198
+ throw new StateSourceError(`${location}: ${what} answered with something that is not JSON`);
199
+ }
200
+ };
201
+ const api = async (): Promise<string> => {
202
+ if (base) return base;
203
+ const r = await call(`${origin}/.well-known/terraform.json`);
204
+ let doc: Record<string, unknown> = {};
205
+ try {
206
+ doc = r.status < 300 ? (JSON.parse(r.text) as Record<string, unknown>) : {};
207
+ } catch {
208
+ doc = {};
209
+ }
210
+ const v2 = doc["tfe.v2"];
211
+ if (typeof v2 !== "string") throw new StateSourceError(`${location}: ${host} names no tfe.v2 API in /.well-known/terraform.json, so it does not speak the remote backend's protocol`);
212
+ base = new URL(v2, `${origin}/`).toString().replace(/\/?$/, "/");
213
+ return base;
214
+ };
215
+ const list = async (what: string, url: string): Promise<{ data: ApiResource[]; included: ApiResource[] }> => {
216
+ const data: ApiResource[] = [];
217
+ const included: ApiResource[] = [];
218
+ for (let page = 1, guard = 0; page && guard < 1000; guard++) {
219
+ const u = new URL(url);
220
+ u.searchParams.set("page[number]", String(page));
221
+ u.searchParams.set("page[size]", "100");
222
+ const doc = json<{ data?: unknown; included?: unknown; meta?: { pagination?: { "next-page"?: number | null } } }>(what, await call(u.toString()));
223
+ if (!Array.isArray(doc.data)) throw new StateSourceError(`${location}: ${what} answered with no list`);
224
+ data.push(...(doc.data as ApiResource[]));
225
+ if (Array.isArray(doc.included)) included.push(...(doc.included as ApiResource[]));
226
+ const next = doc.meta?.pagination?.["next-page"];
227
+ page = typeof next === "number" && next > page ? next : 0;
228
+ }
229
+ return { data, included };
230
+ };
231
+ return { host, hasToken: async () => (await lookup()) !== undefined, call, json, api, list, tokenFrom: () => held?.from };
232
+ }
233
+
234
+ /** A workspace's state over the TFE API, as the remote backend and the cloud block read it. */
235
+ export function workspaceSource(backend: string, host: string, org: string, name: string, env: NodeJS.ProcessEnv, fetchFn: StoreFetch = fetch as unknown as StoreFetch): ExternalSource {
236
+ const location = `${backend}://${host}/${org}/${name}`;
237
+ const origin = `https://${host}`;
238
+ const { call, api, tokenFrom } = tfeClient(host, location, env, fetchFn);
239
+ const json = (what: string, r: ApiAnswer): Json => {
240
+ // The state read's own wording: the workspace, not "it".
241
+ if (r.status === 401 || r.status === 404) {
242
+ const from = tokenFrom();
243
+ throw new StateSourceError(`${location}: ${what} answered ${r.status}; ${from ? `the token in ${from} may not read the workspace` : `the job has no token for ${host}: set ${tokenSetting(host)}`}`);
244
+ }
245
+ if (r.status >= 300) throw new StateSourceError(`${location}: ${what} answered ${r.status}: ${r.text.slice(0, 200)}`);
246
+ try {
247
+ return JSON.parse(r.text) as Json;
248
+ } catch {
249
+ throw new StateSourceError(`${location}: ${what} answered with something that is not JSON`);
250
+ }
251
+ };
252
+ let id: string | undefined;
253
+ const workspace = async (): Promise<string> => {
254
+ if (id) return id;
255
+ const b = await api();
256
+ const got = json("the workspace", await call(`${b}organizations/${encodeURIComponent(org)}/workspaces/${encodeURIComponent(name)}`));
257
+ if (!got.data?.id) throw new StateSourceError(`${location}: the workspace answered with no id`);
258
+ id = got.data.id;
259
+ return id;
260
+ };
261
+ return {
262
+ backend,
263
+ location,
264
+ read: async () => {
265
+ const b = await api();
266
+ const ws = await workspace();
267
+ const r = await call(`${b}workspaces/${ws}/current-state-version`);
268
+ // The workspace answered, so no current version is no state yet.
269
+ if (r.status === 404) return null;
270
+ const sv = json("the current state version", r);
271
+ const url = sv.data?.attributes?.["hosted-state-download-url"];
272
+ if (!sv.data?.id || typeof url !== "string") throw new StateSourceError(`${location}: the current state version names no download URL`);
273
+ const got = await call(new URL(url, `${origin}/`).toString());
274
+ if (got.status >= 300) throw new StateSourceError(`${location}: the download of ${sv.data.id} answered ${got.status}`);
275
+ return { text: got.text, version: sv.data.id };
276
+ },
277
+ lock: async (reason) => {
278
+ const b = await api();
279
+ const ws = await workspace();
280
+ const r = await call(`${b}workspaces/${ws}/actions/lock`, "POST", JSON.stringify({ reason }));
281
+ if (r.status === 409) throw new StateSourceError(`its workspace ${location} is locked, so nothing was written`);
282
+ json("the workspace lock", r);
283
+ return async () => {
284
+ const u = await call(`${b}workspaces/${ws}/actions/unlock`, "POST");
285
+ if (u.status >= 300) throw new StateSourceError(`${location}: the unlock answered ${u.status}`);
286
+ };
287
+ },
288
+ };
289
+ }
@@ -16,18 +16,44 @@
16
16
  * `terraform apply` on the same checkout at the same time is not
17
17
  * kept out. Ruled on #4481 (ruling 4, 2026-10-25): chant's own
18
18
  * lock file, no Terraform lock-info file, local backends allowed.
19
+ * http a GitLab-managed state (./gitlab.ts): `<address>/lock`
20
+ *
21
+ * Each store also reads the state's versions (#4793), from the object's
22
+ * metadata, and its body only when a version's text is asked for:
23
+ *
24
+ * s3 bucket versioning: the object's `x-amz-version-id`
25
+ * gcs object versioning: a version is a generation
26
+ * azurerm blob versioning: the blob's `x-ms-version-id`; with none, the
27
+ * snapshots the backend takes when it sets `snapshot = true`,
28
+ * and `version(true)` takes one, whose time names it
29
+ * http GitLab keeps each version by its serial
30
+ * local keeps only the latest state
19
31
  *
20
32
  * Lifted from terragucci's `backend.ts` (c493e0e): `StateStore`, `s3Store`,
21
- * `gcsStore` and `azureStore`, plus a local store and `removeBeside`.
33
+ * `gcsStore` and `azureStore`, plus a local store and `removeBeside`; the
34
+ * version reads and the azurerm metadata lookup from the same file (#4793).
22
35
  */
36
+ import { createHash } from "node:crypto";
23
37
  import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
24
38
  import { dirname, isAbsolute, join } from "node:path";
39
+ import type { ObjectVersion } from "@intentius/chant/object-store";
25
40
  import { AzureBlobClient, type AzureTarget } from "./azure-blob";
26
41
  import type { AzureState, GcsState, LocalState, LockableState, S3State } from "./backend";
27
42
  import { GcsClient } from "./gcs";
28
- import { StoreError, type StoreFetch } from "./object-store";
43
+ import { gitlabStore, type GitLabFetch } from "./gitlab";
44
+ import { defaultFetch, StoreError, type StoreFetch } from "./object-store";
29
45
  import { S3Client } from "./s3";
30
46
 
47
+ /** The version of the state a store holds now. */
48
+ export interface StoreVersion {
49
+ /** Whether there is a state at all. */
50
+ exists: boolean;
51
+ /** Its id, when the store keeps versions and can give this one back later. */
52
+ versionId?: string;
53
+ /** Why the store keeps no version of it, when it keeps none. */
54
+ off?: string;
55
+ }
56
+
31
57
  /** The lock a state's backend holds: the ID `force-unlock` takes, and the lock info the binary (or a run) wrote. */
32
58
  export interface LockHolder {
33
59
  id: string;
@@ -38,7 +64,7 @@ export interface LockHolder {
38
64
  /** A state where it is, for what locks it and keeps beside it. */
39
65
  export interface StateStore {
40
66
  /** The backend's type; `http` is a GitLab-managed state (./gitlab.ts). */
41
- readonly backend: LockableState["backend"] | "http";
67
+ readonly backend: LockableState["backend"];
42
68
  /** Where the state is. */
43
69
  readonly location: string;
44
70
  /** Where its lock is: the lock object, or the blob whose lease is the lock. */
@@ -71,6 +97,24 @@ export interface StateStore {
71
97
  * (azurerm) is taken over by its ID, the others need nothing.
72
98
  */
73
99
  adopt(held: LockHolder): void;
100
+ /**
101
+ * The version the store holds now (#4793). With `pin`, an azurerm blob
102
+ * that keeps snapshots and no versions gets a snapshot, whose id names it;
103
+ * without, it names none. The other stores read the version they keep.
104
+ */
105
+ version(pin?: boolean): Promise<StoreVersion>;
106
+ /** Whether the store holds the version `id` names, without reading it. */
107
+ hasVersion(id: string): Promise<boolean>;
108
+ /** That version's text, or undefined when the store holds no such version. */
109
+ readVersion(id: string): Promise<string | undefined>;
110
+ /** Whether the state is still the version `id` names. */
111
+ isAt(id: string): Promise<boolean>;
112
+ /**
113
+ * Every version the store keeps, newest first: ids and times, never a
114
+ * state's contents. Undefined for a store that lists none: a local file,
115
+ * and GitLab's state API, which has no list of a state's versions.
116
+ */
117
+ listVersions?: () => Promise<ObjectVersion[]>;
74
118
  }
75
119
 
76
120
  /** The ID in a lock info's JSON, or "" when it names none. */
@@ -85,10 +129,17 @@ export function lockId(text: string): string {
85
129
 
86
130
  const JSON_TYPE = "application/json";
87
131
 
132
+ const sha = (s: string): string => createHash("sha256").update(s).digest("hex");
133
+
88
134
  /** The S3 state, locked by the lock file `use_lockfile` takes. */
89
135
  function s3Store(o: S3State, fetchFn?: StoreFetch): StateStore {
90
136
  const client = new S3Client(o.target, fetchFn);
91
137
  const lockKey = `${o.key}.tflock`;
138
+ const version = async (): Promise<StoreVersion> => {
139
+ const head = await client.head(o.key);
140
+ if (!head.exists) return { exists: false };
141
+ return head.versionId ? { exists: true, versionId: head.versionId } : { exists: true, off: `bucket versioning is off for ${o.bucket}, so it keeps only the latest state` };
142
+ };
92
143
  return {
93
144
  backend: "s3",
94
145
  location: `s3://${o.bucket}/${o.key}`,
@@ -104,12 +155,18 @@ function s3Store(o: S3State, fetchFn?: StoreFetch): StateStore {
104
155
  removeBeside: (suffix) => client.remove(`${o.key}${suffix}`),
105
156
  besideLocation: (suffix) => `s3://${o.bucket}/${o.key}${suffix}`,
106
157
  adopt: () => {},
158
+ version,
159
+ hasVersion: (id) => client.hasVersion(o.key, id),
160
+ readVersion: (id) => client.readVersion(o.key, id),
161
+ isAt: async (id) => (await version()).versionId === id,
162
+ listVersions: () => client.listVersions(o.key),
107
163
  };
108
164
  }
109
165
 
110
166
  /** The GCS state, locked by `<prefix>/<workspace>.tflock`, whose generation is the lock's ID. */
111
167
  function gcsStore(o: GcsState, fetchFn?: StoreFetch): StateStore {
112
168
  const client = new GcsClient(o.target, fetchFn);
169
+ let versioning: Promise<boolean | undefined> | undefined;
113
170
  return {
114
171
  backend: "gcs",
115
172
  location: `gs://${o.bucket}/${o.key}`,
@@ -127,29 +184,70 @@ function gcsStore(o: GcsState, fetchFn?: StoreFetch): StateStore {
127
184
  removeBeside: (suffix) => client.remove(`${o.key}${suffix}`),
128
185
  besideLocation: (suffix) => `gs://${o.bucket}/${o.key}${suffix}`,
129
186
  adopt: () => {},
187
+ version: async () => {
188
+ const head = await client.head(o.key);
189
+ if (!head.exists) return { exists: false };
190
+ versioning ??= client.versioning();
191
+ if ((await versioning) === false) return { exists: true, off: `object versioning is off for ${o.bucket}, so it keeps only the latest state` };
192
+ return { exists: true, ...(head.generation ? { versionId: head.generation } : {}) };
193
+ },
194
+ hasVersion: async (id) => (await client.head(o.key, id)).exists,
195
+ readVersion: (id) => client.readGeneration(o.key, id),
196
+ isAt: async (id) => (await client.head(o.key)).generation === id,
197
+ listVersions: () => client.listVersions(o.key),
130
198
  };
131
199
  }
132
200
 
133
201
  /** The metadata an azurerm backend keeps a lock's info in, base64 JSON, on the leased blob. */
134
202
  export const LOCK_METADATA = "terraformlockid";
135
203
 
136
- /** The azurerm state blob, locked by a lease on it with the lock info in its metadata. */
204
+ /**
205
+ * The account's blob endpoint: the state's, or `https://<account>.blob.<suffix>`
206
+ * with the storage suffix the cloud's metadata at `metadata_host` names (#4793).
207
+ */
208
+ export async function azureEndpoint(o: AzureState, fetchFn: StoreFetch = defaultFetch): Promise<string> {
209
+ if (o.endpoint) return o.endpoint;
210
+ if (!o.metadataHost) throw new StoreError(`az://${o.account}/${o.container} names neither an endpoint nor a metadata_host`);
211
+ const url = `https://${o.metadataHost}/metadata/endpoints?api-version=2023-11-01`;
212
+ const res = await fetchFn(url, { method: "GET", headers: { accept: "application/json" } });
213
+ const text = await res.text();
214
+ if (!res.ok) throw new StoreError(`the Azure metadata at ${o.metadataHost}: ${res.status}`);
215
+ let suffix: unknown;
216
+ try {
217
+ const j = JSON.parse(text) as { suffixes?: { storage?: unknown } } | { suffixes?: { storage?: unknown } }[];
218
+ suffix = (Array.isArray(j) ? j[0] : j)?.suffixes?.storage;
219
+ } catch {
220
+ // Reported below.
221
+ }
222
+ if (typeof suffix !== "string" || suffix === "") throw new StoreError(`the Azure metadata at ${o.metadataHost} names no storage suffix`);
223
+ return `https://${o.account}.blob.${suffix.replace(/^\.+/, "")}`;
224
+ }
225
+
226
+ /**
227
+ * The azurerm state blob, locked by a lease on it with the lock info in its
228
+ * metadata. Its client is made on the first call, once the endpoint is known.
229
+ */
137
230
  function azureStore(o: AzureState, fetchFn?: StoreFetch): StateStore {
138
- const client = new AzureBlobClient({ account: o.account, container: o.container, endpoint: o.endpoint, ...o.auth } as AzureTarget, fetchFn);
231
+ let made: Promise<AzureBlobClient> | undefined;
232
+ const open = (): Promise<AzureBlobClient> =>
233
+ (made ??= azureEndpoint(o, fetchFn).then((endpoint) => new AzureBlobClient({ account: o.account, container: o.container, endpoint, ...o.auth } as AzureTarget, fetchFn)));
139
234
  let leaseId: string | undefined;
140
235
  const at = `az://${o.account}/${o.container}/${o.key}`;
236
+ /** A version id names the blob's versions when it keeps them, else a snapshot does. */
237
+ const atOf = async (c: AzureBlobClient, id: string) => ((await c.head(o.key)).versionId ? { versionid: id } : { snapshot: id });
141
238
  return {
142
239
  backend: "azurerm",
143
240
  location: at,
144
241
  lockLocation: at,
145
242
  heldLock: async () => {
146
- const head = await client.head(o.key);
243
+ const head = await (await open()).head(o.key);
147
244
  if (!head.exists || head.leaseState !== "leased") return undefined;
148
245
  const meta = head.metadata[LOCK_METADATA];
149
246
  const info = meta ? Buffer.from(meta, "base64").toString("utf-8") : "";
150
247
  return { id: lockId(info), info };
151
248
  },
152
249
  lock: async (info) => {
250
+ const client = await open();
153
251
  const id = lockId(info);
154
252
  // The backend leases a blob that is there: a state with none yet gets an empty one first, as the backend makes it.
155
253
  if (!(await client.head(o.key)).exists) await client.putBlob(o.key, "", JSON_TYPE, { ifNoneMatch: true });
@@ -160,6 +258,7 @@ function azureStore(o: AzureState, fetchFn?: StoreFetch): StateStore {
160
258
  },
161
259
  unlock: async () => {
162
260
  if (!leaseId) return;
261
+ const client = await open();
163
262
  const id = leaseId;
164
263
  await client.setMetadata(o.key, {}, id);
165
264
  await client.lease(o.key, "release", id);
@@ -167,18 +266,44 @@ function azureStore(o: AzureState, fetchFn?: StoreFetch): StateStore {
167
266
  },
168
267
  write: async (body) => {
169
268
  if (!leaseId) throw new StoreError(`${at} is written under its lease, and none is held`);
269
+ const client = await open();
170
270
  // As the backend writes it: a snapshot first when it takes snapshots, and the lock info kept on the blob.
171
271
  if (o.snapshot && (await client.head(o.key)).exists) await client.snapshot(o.key);
172
272
  const meta = (await client.head(o.key)).metadata;
173
273
  await client.putBlob(o.key, body, JSON_TYPE, { leaseId, metadata: meta });
174
274
  },
175
- readBeside: (suffix) => client.get(`${o.key}${suffix}`),
176
- writeBeside: async (suffix, body) => void (await client.putBlob(`${o.key}${suffix}`, body, JSON_TYPE)),
177
- removeBeside: (suffix) => client.remove(`${o.key}${suffix}`),
275
+ readBeside: async (suffix) => (await open()).get(`${o.key}${suffix}`),
276
+ writeBeside: async (suffix, body) => void (await (await open()).putBlob(`${o.key}${suffix}`, body, JSON_TYPE)),
277
+ removeBeside: async (suffix) => (await open()).remove(`${o.key}${suffix}`),
178
278
  besideLocation: (suffix) => `${at}${suffix}`,
179
279
  adopt: (held) => {
180
280
  leaseId = held.id;
181
281
  },
282
+ version: async (pin = false) => {
283
+ const client = await open();
284
+ const head = await client.head(o.key);
285
+ if (!head.exists) return { exists: false };
286
+ if (head.versionId) return { exists: true, versionId: head.versionId };
287
+ if (!o.snapshot) return { exists: true, off: `blob versioning is off for ${o.account}, and the backend takes no snapshots (snapshot = true), so it keeps only the latest state` };
288
+ return pin ? { exists: true, versionId: await client.snapshot(o.key) } : { exists: true, off: "the blob keeps no versions, and only a snapshot would name this one" };
289
+ },
290
+ hasVersion: async (id) => {
291
+ const client = await open();
292
+ return (await client.head(o.key, await atOf(client, id))).exists;
293
+ },
294
+ readVersion: async (id) => {
295
+ const client = await open();
296
+ return client.readAt(o.key, await atOf(client, id));
297
+ },
298
+ isAt: async (id) => {
299
+ const client = await open();
300
+ const head = await client.head(o.key);
301
+ if (head.versionId) return head.versionId === id;
302
+ // A snapshot is a copy, not the blob's own version: the state is at it while the two texts are the same.
303
+ const [then, now] = await Promise.all([client.readAt(o.key, { snapshot: id }), client.get(o.key)]);
304
+ return then !== undefined && now !== undefined && sha(then) === sha(now);
305
+ },
306
+ listVersions: async () => (await open()).listVersions(o.key),
182
307
  };
183
308
  }
184
309
 
@@ -214,13 +339,22 @@ function localStore(o: LocalState, dir: string): StateStore {
214
339
  removeBeside: async (suffix) => rmSync(`${file}${suffix}`, { force: true }),
215
340
  besideLocation: (suffix) => `${file}${suffix}`,
216
341
  adopt: () => {},
342
+ version: async () => (existsSync(file) ? { exists: true, off: "a local backend keeps only the latest state" } : { exists: false }),
343
+ hasVersion: async () => false,
344
+ readVersion: async () => undefined,
345
+ isAt: async () => false,
217
346
  };
218
347
  }
219
348
 
220
- /** The store a state is in, opened with the credentials stateObject chose. `dir` is the root a local path is relative to. */
221
- export function stateStore(o: LockableState, dir: string, fetchFn?: StoreFetch): StateStore {
349
+ /**
350
+ * The store a state is in, opened with the credentials stateObject chose.
351
+ * `dir` is the root a local path is relative to. A GitLab-managed state's
352
+ * store names `who` in the lock info of its probe (./gitlab.ts).
353
+ */
354
+ export function stateStore(o: LockableState, dir: string, fetchFn?: StoreFetch, who?: string): StateStore {
222
355
  if (o.backend === "s3") return s3Store(o, fetchFn);
223
356
  if (o.backend === "gcs") return gcsStore(o, fetchFn);
224
357
  if (o.backend === "azurerm") return azureStore(o, fetchFn);
358
+ if (o.backend === "http") return gitlabStore(o, fetchFn as GitLabFetch | undefined, who);
225
359
  return localStore(o, dir);
226
360
  }