@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.
- package/dist/ci-setup.d.ts +11 -2
- package/dist/ci-setup.d.ts.map +1 -1
- package/dist/ci-setup.js +11 -6
- package/dist/components/capability-plugin.d.ts +12 -0
- package/dist/components/capability-plugin.d.ts.map +1 -1
- package/dist/components/capability-plugin.js +22 -4
- package/dist/compose.d.ts.map +1 -1
- package/dist/compose.js +1 -1
- package/dist/estate-migration.d.ts +101 -0
- package/dist/estate-migration.d.ts.map +1 -0
- package/dist/estate-migration.js +471 -0
- package/dist/integrity.json +2 -2
- package/dist/manifest.json +1 -1
- package/dist/op/activities/terraform.d.ts +65 -0
- package/dist/op/activities/terraform.d.ts.map +1 -1
- package/dist/op/activities/terraform.js +94 -1
- package/dist/state/backend.d.ts +46 -9
- package/dist/state/backend.d.ts.map +1 -1
- package/dist/state/backend.js +84 -31
- package/dist/state/gitlab.d.ts +1 -1
- package/dist/state/gitlab.d.ts.map +1 -1
- package/dist/state/gitlab.js +27 -14
- package/dist/state/index.d.ts +1 -0
- package/dist/state/index.d.ts.map +1 -1
- package/dist/state/index.js +1 -0
- package/dist/state/s3.d.ts +9 -3
- package/dist/state/s3.d.ts.map +1 -1
- package/dist/state/s3.js +4 -3
- package/dist/state/source.d.ts +92 -0
- package/dist/state/source.d.ts.map +1 -0
- package/dist/state/source.js +254 -0
- package/dist/state/store.d.ts +41 -4
- package/dist/state/store.d.ts.map +1 -1
- package/dist/state/store.js +125 -10
- package/dist/state/versions.d.ts +77 -10
- package/dist/state/versions.d.ts.map +1 -1
- package/dist/state/versions.js +118 -64
- package/dist/state-migration.d.ts +43 -1
- package/dist/state-migration.d.ts.map +1 -1
- package/dist/state-migration.js +251 -20
- package/dist/state-ops.d.ts +2 -3
- package/dist/state-ops.d.ts.map +1 -1
- package/dist/state-ops.js +4 -7
- package/package.json +2 -2
- package/src/ci-setup.test.ts +20 -0
- package/src/ci-setup.ts +11 -6
- package/src/components/capability-plugin.ts +36 -3
- package/src/components/terraform-apply-command-hook.test.ts +157 -0
- package/src/compose.ts +1 -0
- package/src/estate-migration.test.ts +186 -0
- package/src/estate-migration.ts +563 -0
- package/src/op/activities/terraform.ts +153 -3
- package/src/state/backend-verdict.test.ts +4 -3
- package/src/state/backend.test.ts +3 -1
- package/src/state/backend.ts +108 -33
- package/src/state/gitlab.ts +25 -12
- package/src/state/index.ts +1 -0
- package/src/state/s3.ts +5 -4
- package/src/state/source.ts +289 -0
- package/src/state/store.ts +145 -11
- package/src/state/versions.test.ts +365 -0
- package/src/state/versions.ts +148 -68
- package/src/state-migration-backends.test.ts +277 -0
- package/src/state-migration.ts +265 -23
- 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
|
+
}
|
package/src/state/store.ts
CHANGED
|
@@ -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 {
|
|
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"]
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
|
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) =>
|
|
176
|
-
writeBeside: async (suffix, body) => void (await
|
|
177
|
-
removeBeside: (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
|
-
/**
|
|
221
|
-
|
|
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
|
}
|