@intentius/chant-lexicon-terraform 0.124.75 → 0.124.77
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/integrity.json +2 -2
- package/dist/manifest.json +1 -1
- package/dist/pr-env.d.ts +138 -0
- package/dist/pr-env.d.ts.map +1 -0
- package/dist/pr-env.js +248 -0
- package/dist/state/gitlab.d.ts +74 -0
- package/dist/state/gitlab.d.ts.map +1 -0
- package/dist/state/gitlab.js +275 -0
- package/dist/state/index.d.ts +2 -0
- package/dist/state/index.d.ts.map +1 -1
- package/dist/state/index.js +2 -0
- package/dist/state/store.d.ts +2 -1
- package/dist/state/store.d.ts.map +1 -1
- package/dist/state/versions.d.ts +39 -0
- package/dist/state/versions.d.ts.map +1 -0
- package/dist/state/versions.js +85 -0
- package/dist/state-migration.d.ts +85 -0
- package/dist/state-migration.d.ts.map +1 -0
- package/dist/state-migration.js +296 -0
- package/dist/state-ops.d.ts +54 -87
- package/dist/state-ops.d.ts.map +1 -1
- package/dist/state-ops.js +120 -77
- package/package.json +2 -2
- package/src/pr-env.test.ts +132 -0
- package/src/pr-env.ts +312 -0
- package/src/state/gitlab.test.ts +226 -0
- package/src/state/gitlab.ts +318 -0
- package/src/state/index.ts +2 -0
- package/src/state/store.ts +2 -1
- package/src/state/versions.ts +103 -0
- package/src/state-export-unlock.test.ts +230 -0
- package/src/state-migration.test.ts +236 -0
- package/src/state-migration.ts +353 -0
- package/src/state-ops.ts +132 -130
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A state migration between Terraform roots (#4762), for chant core's
|
|
3
|
+
* gated migration (`@intentius/chant/state-migration`): what `moved`,
|
|
4
|
+
* `import` and `removed` blocks cannot do, because each works inside one
|
|
5
|
+
* root's state.
|
|
6
|
+
*
|
|
7
|
+
* moves resources (`[module.<m>.]<type>.<name>`) or module calls
|
|
8
|
+
* (`module.<m>`), with every instance, from one root's state to
|
|
9
|
+
* the same address in another's
|
|
10
|
+
* restores a root's state put back to a version a migration recorded (a
|
|
11
|
+
* revert), refused when the state moved past what that
|
|
12
|
+
* migration left
|
|
13
|
+
*
|
|
14
|
+
* Planning (planTerraformMigration) initialises each root in a data dir of
|
|
15
|
+
* its own, reads its backend version id and pulls its state, keeps only
|
|
16
|
+
* their digests, builds each new state in the work dir, and plans each root
|
|
17
|
+
* against its new state through a local-backend override file and another
|
|
18
|
+
* data dir, so the root's own `.terraform` and its real state are not
|
|
19
|
+
* touched. The engine it returns writes the new states for core under each
|
|
20
|
+
* stored state's lock (s3's lock file, the gcs lock object, the azurerm
|
|
21
|
+
* lease, as `./state/locks.ts` takes them): `state push -lock=false`, or a
|
|
22
|
+
* write under the lease on azurerm, the roots that gain resources first, so
|
|
23
|
+
* a write that stops half way leaves a resource in two states rather than
|
|
24
|
+
* in none. Then each root plans against its real backend.
|
|
25
|
+
*
|
|
26
|
+
* State contents never leave the work dir. The record holds version ids and
|
|
27
|
+
* digests.
|
|
28
|
+
*
|
|
29
|
+
* Lifted from terragucci's `migrate.ts` (`moveResources`, `addressMatches`,
|
|
30
|
+
* `derivedLineage`, `stateDigest`, `resourceChanges`, `backendBlock`,
|
|
31
|
+
* `proofPlan`, `planMigration`'s moves and reverts, `applyMigration`,
|
|
32
|
+
* `movedSince`), so terragucci deletes its copy. A backend move (a state
|
|
33
|
+
* read from another backend, a TFE workspace or an exported file) and a
|
|
34
|
+
* migration of choudoufu's live estates stay terragucci's for now.
|
|
35
|
+
*/
|
|
36
|
+
import { createHash } from "node:crypto";
|
|
37
|
+
import { hostname } from "node:os";
|
|
38
|
+
import { join, resolve } from "node:path";
|
|
39
|
+
import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
40
|
+
import { initRoot, planStateCheck, pushStateFile } from "./state-ops.js";
|
|
41
|
+
import { isRefused, isStored, stateLocation, stateObject } from "./state/backend.js";
|
|
42
|
+
import { pullState, runBinary } from "./state/exec.js";
|
|
43
|
+
import { takeLocksWithSources } from "./state/locks.js";
|
|
44
|
+
import { stateStore } from "./state/store.js";
|
|
45
|
+
import { stateVersionSource } from "./state/versions.js";
|
|
46
|
+
/** A migration that cannot be planned: an address in no state, a root that is refused. Nothing was written. */
|
|
47
|
+
export class MigrationError extends Error {
|
|
48
|
+
constructor(message) {
|
|
49
|
+
super(message);
|
|
50
|
+
this.name = "MigrationError";
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
const sha = (text) => `sha256:${createHash("sha256").update(text).digest("hex")}`;
|
|
54
|
+
/** A state's digest: sha256 of its JSON as parsed and written back, so whitespace never moves it. */
|
|
55
|
+
export const stateDigest = (s) => sha(JSON.stringify(s));
|
|
56
|
+
/** A resource entry's address without instance keys: `module.a.module.b.type.name`, module keys dropped. */
|
|
57
|
+
const resourceAddress = (r) => `${r.module ? `${r.module.replace(/\[[^\]]*\]/g, "")}.` : ""}${r.mode === "data" ? "data." : ""}${r.type}.${r.name}`;
|
|
58
|
+
const moduleOf = (r) => (r.module ?? "").replace(/\[[^\]]*\]/g, "");
|
|
59
|
+
/** Whether a migration address names a state entry: the managed resource itself, or a module call it sits in, with its data sources. */
|
|
60
|
+
export function addressMatches(address, r) {
|
|
61
|
+
if (/(^|\.)module\.[A-Za-z_][\w-]*$/.test(address))
|
|
62
|
+
return moduleOf(r) === address || moduleOf(r).startsWith(`${address}.`);
|
|
63
|
+
return r.mode === "managed" && resourceAddress(r) === address;
|
|
64
|
+
}
|
|
65
|
+
/** A lineage that a migration and a root always give the same: a state planned twice has one digest. */
|
|
66
|
+
export function derivedLineage(...parts) {
|
|
67
|
+
const h = createHash("sha256").update(parts.join("\n")).digest("hex");
|
|
68
|
+
return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-8${h.slice(17, 20)}-${h.slice(20, 32)}`;
|
|
69
|
+
}
|
|
70
|
+
const emptyState = (lineage, serial, terraformVersion = "1.0.0") => ({ version: 4, terraform_version: terraformVersion, serial, lineage, outputs: {}, resources: [], check_results: null });
|
|
71
|
+
/**
|
|
72
|
+
* The states after the moves. `before` holds each affected root's state, or
|
|
73
|
+
* null when it has none. A changed state keeps its lineage and gets the next
|
|
74
|
+
* serial; a root with no state gets a new one, its lineage derived from the
|
|
75
|
+
* migration and the root. Throws MigrationError naming every address that
|
|
76
|
+
* is in no state, or already in the root it moves to.
|
|
77
|
+
*/
|
|
78
|
+
export function moveResources(name, moves, before) {
|
|
79
|
+
const after = new Map();
|
|
80
|
+
const take = (root, from) => {
|
|
81
|
+
const held = after.get(root);
|
|
82
|
+
if (held)
|
|
83
|
+
return held;
|
|
84
|
+
const was = before.get(root) ?? null;
|
|
85
|
+
const s = was ? { ...structuredClone(was), serial: was.serial + 1 } : emptyState(derivedLineage(name, root), 1, from?.terraform_version);
|
|
86
|
+
after.set(root, s);
|
|
87
|
+
return s;
|
|
88
|
+
};
|
|
89
|
+
const problems = [];
|
|
90
|
+
for (const m of moves) {
|
|
91
|
+
const src = before.get(m.from) ?? null;
|
|
92
|
+
if (!src) {
|
|
93
|
+
problems.push(`${m.from} has no state to move ${m.addresses.join(", ")} from`);
|
|
94
|
+
continue;
|
|
95
|
+
}
|
|
96
|
+
const from = take(m.from);
|
|
97
|
+
const to = take(m.to, src);
|
|
98
|
+
for (const address of m.addresses) {
|
|
99
|
+
const found = from.resources.filter((r) => addressMatches(address, r));
|
|
100
|
+
if (found.length === 0) {
|
|
101
|
+
problems.push(`${address} is not in the state of ${m.from}`);
|
|
102
|
+
continue;
|
|
103
|
+
}
|
|
104
|
+
if (to.resources.some((r) => addressMatches(address, r))) {
|
|
105
|
+
problems.push(`${address} is already in the state of ${m.to}`);
|
|
106
|
+
continue;
|
|
107
|
+
}
|
|
108
|
+
from.resources = from.resources.filter((r) => !found.includes(r));
|
|
109
|
+
to.resources.push(...found);
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
if (problems.length > 0)
|
|
113
|
+
throw new MigrationError(`migration ${name}:\n ${problems.join("\n ")}`);
|
|
114
|
+
return after;
|
|
115
|
+
}
|
|
116
|
+
/** The resource changes of a plan's JSON, as `<address>: <actions>`; no-ops and reads are not changes. */
|
|
117
|
+
export function resourceChanges(plan) {
|
|
118
|
+
const rc = plan?.resource_changes ?? [];
|
|
119
|
+
return rc
|
|
120
|
+
.filter((c) => {
|
|
121
|
+
const a = c.change?.actions ?? [];
|
|
122
|
+
return !(a.length === 1 && (a[0] === "no-op" || a[0] === "read"));
|
|
123
|
+
})
|
|
124
|
+
.map((c) => `${c.address}: ${(c.change?.actions ?? []).join("+")}`);
|
|
125
|
+
}
|
|
126
|
+
/** A terraform block whose backend is the local file `path`, for the proof plan's override file. Terraform and OpenTofu merge any `*_override.tf` over the root's files. */
|
|
127
|
+
export const localBackendOverride = (path) => `terraform {\n backend "local" {\n path = ${JSON.stringify(path)}\n }\n}\n`;
|
|
128
|
+
/** The override file a proof plan writes into a root, and removes, unless the product names its own. */
|
|
129
|
+
export const DEFAULT_OVERRIDE_FILE = "chant_migrate_override.tf";
|
|
130
|
+
/** What a migration's lock says, unless the product names its own. */
|
|
131
|
+
export const DEFAULT_MIGRATE_LOCK = { operation: "chant migrate", info: "a state migration is writing this state" };
|
|
132
|
+
/** A root's version id now, when its store keeps versions. `pin` lets an azurerm blob with snapshots only take one to name it. */
|
|
133
|
+
async function versionNow(o, fetchFn, pin) {
|
|
134
|
+
const src = stateVersionSource(o, fetchFn, { pin });
|
|
135
|
+
if ("refused" in src)
|
|
136
|
+
return undefined;
|
|
137
|
+
return (await src.current()).versionId;
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* Plan a migration: read every affected state and its version, build the new
|
|
141
|
+
* states in `work`, and plan each root against its new state. Throws
|
|
142
|
+
* MigrationError for a root that is refused or a move that does not fit.
|
|
143
|
+
*/
|
|
144
|
+
export async function planTerraformMigration(input) {
|
|
145
|
+
const exec = input.exec ?? runBinary;
|
|
146
|
+
const log = input.log ?? (() => { });
|
|
147
|
+
const lockOp = input.lock ?? DEFAULT_MIGRATE_LOCK;
|
|
148
|
+
const override = input.overrideFile ?? DEFAULT_OVERRIDE_FILE;
|
|
149
|
+
if (!!input.moves?.length === !!input.restores?.length)
|
|
150
|
+
throw new MigrationError(`migration ${input.name}: give it moves or restores, one of the two`);
|
|
151
|
+
mkdirSync(input.work, { recursive: true });
|
|
152
|
+
const named = [...new Set(input.moves ? input.moves.flatMap((m) => [m.from, m.to]) : input.restores.map((r) => r.root))].sort();
|
|
153
|
+
const byName = new Map(input.roots.map((r) => [r.root, r]));
|
|
154
|
+
const missing = named.filter((n) => !byName.has(n));
|
|
155
|
+
if (missing.length > 0)
|
|
156
|
+
throw new MigrationError(`migration ${input.name}: ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not among its roots`);
|
|
157
|
+
const runs = new Map();
|
|
158
|
+
const objects = new Map();
|
|
159
|
+
const versions = new Map();
|
|
160
|
+
const before = new Map();
|
|
161
|
+
for (const [i, name] of named.entries()) {
|
|
162
|
+
const r = byName.get(name);
|
|
163
|
+
let env = r.env ?? process.env;
|
|
164
|
+
if (r.init !== false) {
|
|
165
|
+
env = { ...env, TF_DATA_DIR: join(input.work, `data-${i}`) };
|
|
166
|
+
await initRoot({ ...r, env, exec, reconfigure: true });
|
|
167
|
+
}
|
|
168
|
+
const o = stateObject(r.dir, env, undefined, r.binary);
|
|
169
|
+
if (isRefused(o))
|
|
170
|
+
throw new MigrationError(`migration ${input.name} cannot run: ${name}: ${o.reason}`);
|
|
171
|
+
runs.set(name, { ...r, env });
|
|
172
|
+
objects.set(name, o);
|
|
173
|
+
versions.set(name, await versionNow(o, input.fetch, false));
|
|
174
|
+
before.set(name, await pullState(exec, r.binary, name, r.dir, env));
|
|
175
|
+
}
|
|
176
|
+
const after = new Map();
|
|
177
|
+
if (input.moves) {
|
|
178
|
+
for (const [root, s] of moveResources(input.name, input.moves, before))
|
|
179
|
+
after.set(root, s);
|
|
180
|
+
}
|
|
181
|
+
else {
|
|
182
|
+
for (const r of input.restores) {
|
|
183
|
+
const o = objects.get(r.root);
|
|
184
|
+
const location = stateLocation(o);
|
|
185
|
+
if (location !== r.location)
|
|
186
|
+
throw new MigrationError(`migration ${input.name}: ${r.root}'s state is at ${location}, and the revert restores ${r.location}`);
|
|
187
|
+
const v = versions.get(r.root);
|
|
188
|
+
if ((r.from_version_id ?? undefined) !== v)
|
|
189
|
+
throw new MigrationError(`migration ${input.name}: ${r.root}'s state is at version ${v ?? "none"}, and the migration it reverts left ${r.from_version_id ?? "none"}; it moved since, so putting the older version back would undo that change too`);
|
|
190
|
+
const now = before.get(r.root) ?? null;
|
|
191
|
+
const lineage = now?.lineage || derivedLineage(input.name, r.root);
|
|
192
|
+
const serial = (now?.serial ?? 0) + 1;
|
|
193
|
+
if (r.version_id === null) {
|
|
194
|
+
after.set(r.root, emptyState(lineage, serial, now?.terraform_version));
|
|
195
|
+
continue;
|
|
196
|
+
}
|
|
197
|
+
const src = stateVersionSource(o, input.fetch);
|
|
198
|
+
if ("refused" in src)
|
|
199
|
+
throw new MigrationError(`migration ${input.name}: ${r.root}: ${src.refused}`);
|
|
200
|
+
const text = await src.readVersion(r.version_id);
|
|
201
|
+
if (text === undefined)
|
|
202
|
+
throw new MigrationError(`migration ${input.name}: ${r.location} has no version ${r.version_id}; a lifecycle rule may have expired it`);
|
|
203
|
+
const old = JSON.parse(typeof text === "string" ? text : Buffer.from(text).toString("utf-8"));
|
|
204
|
+
after.set(r.root, { ...old, resources: Array.isArray(old.resources) ? old.resources : [], lineage, serial });
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
const planned = new Map();
|
|
208
|
+
const roots = [];
|
|
209
|
+
for (const [i, name] of named.entries()) {
|
|
210
|
+
const state = after.get(name);
|
|
211
|
+
if (!state)
|
|
212
|
+
continue;
|
|
213
|
+
const run = runs.get(name);
|
|
214
|
+
const file = join(input.work, `${i}.tfstate`);
|
|
215
|
+
writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`);
|
|
216
|
+
planned.set(name, { run, object: objects.get(name), file, gained: state.resources.length - (before.get(name)?.resources.length ?? 0) });
|
|
217
|
+
const proof = await proofPlan(run, exec, file, join(input.work, `proof-${i}`), override);
|
|
218
|
+
log(`${name}: ${proof.changes.length === 0 ? "no changes against its new state" : `${proof.changes.length} change${proof.changes.length === 1 ? "" : "s"} against its new state: ${proof.changes.join(", ")}`}`);
|
|
219
|
+
const was = before.get(name) ?? null;
|
|
220
|
+
const v = versions.get(name);
|
|
221
|
+
const location = stateLocation(objects.get(name));
|
|
222
|
+
roots.push({ root: name, ...(location ? { location } : {}), before: { ...(v ? { version_id: v } : {}), digest: was ? stateDigest(was) : null }, after: { digest: stateDigest(state) }, proof });
|
|
223
|
+
}
|
|
224
|
+
return { roots, engine: migrationEngine(planned, input, exec, lockOp) };
|
|
225
|
+
}
|
|
226
|
+
/**
|
|
227
|
+
* Plan a root against a state file: an override file switches its backend to
|
|
228
|
+
* that local file, in a data dir of its own, so the root's `.terraform` and
|
|
229
|
+
* its real state are never touched. The override file is removed whatever
|
|
230
|
+
* happens.
|
|
231
|
+
*/
|
|
232
|
+
async function proofPlan(run, exec, file, data, override) {
|
|
233
|
+
const at = join(run.dir, override);
|
|
234
|
+
const env = { ...run.env, TF_DATA_DIR: data };
|
|
235
|
+
writeFileSync(at, localBackendOverride(resolve(file)));
|
|
236
|
+
try {
|
|
237
|
+
await initRoot({ ...run, env, exec, reconfigure: true });
|
|
238
|
+
const read = await planStateCheck({ ...run, env, exec, planFile: `${data}.tfplan` });
|
|
239
|
+
return { changes: resourceChanges(read.json), summary: read.summary };
|
|
240
|
+
}
|
|
241
|
+
finally {
|
|
242
|
+
rmSync(at, { force: true });
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
function migrationEngine(planned, input, exec, lockOp) {
|
|
246
|
+
const log = input.log ?? (() => { });
|
|
247
|
+
const stores = new Map();
|
|
248
|
+
for (const [root, p] of planned)
|
|
249
|
+
if (isStored(p.object))
|
|
250
|
+
stores.set(root, stateStore(p.object, p.run.dir, input.fetch));
|
|
251
|
+
const pinned = new Map();
|
|
252
|
+
return {
|
|
253
|
+
async lock() {
|
|
254
|
+
const got = await takeLocksWithSources({ sources: [], stores: [...stores].map(([root, store]) => ({ root, store })), now: new Date().toISOString(), op: lockOp, who: input.who ?? `chant@${hostname()}` });
|
|
255
|
+
return async () => {
|
|
256
|
+
for (const l of got.locks.reverse())
|
|
257
|
+
await l.release().catch((e) => log(`${l.root}: the lock could not be released: ${e.message}`));
|
|
258
|
+
};
|
|
259
|
+
},
|
|
260
|
+
async current(root) {
|
|
261
|
+
const p = planned.get(root);
|
|
262
|
+
const v = await versionNow(p.object, input.fetch, false);
|
|
263
|
+
const s = await pullState(exec, p.run.binary, root, p.run.dir, p.run.env);
|
|
264
|
+
return { ...(v ? { version_id: v } : {}), digest: s ? stateDigest(s) : null };
|
|
265
|
+
},
|
|
266
|
+
async write() {
|
|
267
|
+
// An azurerm state named by no version gets a snapshot first, so the record names what it was.
|
|
268
|
+
for (const [root, p] of planned) {
|
|
269
|
+
if (p.object.backend !== "azurerm")
|
|
270
|
+
continue;
|
|
271
|
+
if (await versionNow(p.object, input.fetch, false))
|
|
272
|
+
continue;
|
|
273
|
+
const v = await versionNow(p.object, input.fetch, true);
|
|
274
|
+
if (v)
|
|
275
|
+
pinned.set(root, v);
|
|
276
|
+
}
|
|
277
|
+
const order = [...planned].sort(([a, pa], [b, pb]) => pb.gained - pa.gained || (a < b ? -1 : 1));
|
|
278
|
+
for (const [root, p] of order) {
|
|
279
|
+
const store = stores.get(root);
|
|
280
|
+
// A state whose lock keeps the binary out (azurerm's lease) is written under it; the binary writes the others with the lock held for it.
|
|
281
|
+
if (store?.write)
|
|
282
|
+
await store.write(readFileSync(p.file, "utf-8"));
|
|
283
|
+
else
|
|
284
|
+
await pushStateFile({ ...p.run, exec, file: p.file, ...(store ? { lock: false } : {}) });
|
|
285
|
+
log(`${root}: wrote its new state`);
|
|
286
|
+
}
|
|
287
|
+
},
|
|
288
|
+
async verify(root) {
|
|
289
|
+
const p = planned.get(root);
|
|
290
|
+
const read = await planStateCheck({ ...p.run, exec, planFile: join(input.work, `verify-${root.replace(/[^\w.-]/g, "_")}.tfplan`), ...(stores.has(root) ? { lock: false } : {}) });
|
|
291
|
+
const v = await versionNow(p.object, input.fetch, true);
|
|
292
|
+
const was = pinned.get(root);
|
|
293
|
+
return { changes: resourceChanges(read.json), summary: read.summary, ...(v ? { version_id: v } : {}), ...(was ? { before_version_id: was } : {}) };
|
|
294
|
+
},
|
|
295
|
+
};
|
|
296
|
+
}
|
package/dist/state-ops.d.ts
CHANGED
|
@@ -1,7 +1,13 @@
|
|
|
1
1
|
import type { Capability } from "@intentius/chant/components/capability";
|
|
2
2
|
import type { ChangeSetPart } from "@intentius/chant/change-set";
|
|
3
|
-
import {
|
|
3
|
+
import { type GatedRequest, type GatedRequestRules } from "@intentius/chant/lifecycle/gated-request";
|
|
4
|
+
import { gatedOp } from "@intentius/chant/lifecycle/gated-op";
|
|
5
|
+
import { type StateExportInput, type StateExportOutcome } from "@intentius/chant/state-export";
|
|
6
|
+
import { type StateLockSource, type StateUnlockInput, type StateUnlockOutcome } from "@intentius/chant/state-unlock";
|
|
7
|
+
import { type StateObject } from "./state/backend.js";
|
|
4
8
|
import { type BinaryExec } from "./state/exec.js";
|
|
9
|
+
import { type GitLabState } from "./state/gitlab.js";
|
|
10
|
+
import type { StoreFetch } from "./state/object-store.js";
|
|
5
11
|
/** The ops the gated requests of this module wait at, one per kind, as terragucci named them. */
|
|
6
12
|
export declare const STATE_OPS: {
|
|
7
13
|
readonly unlock: "tf-unlock";
|
|
@@ -103,97 +109,59 @@ export declare function applyPlanFile(r: RootRun & {
|
|
|
103
109
|
planFile: string;
|
|
104
110
|
lockTimeout?: string | false;
|
|
105
111
|
}): Promise<void>;
|
|
106
|
-
|
|
107
|
-
export
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
* The time a request was first asked, so asking again binds the same
|
|
115
|
-
* digest: chant's digest covers `at`, and a run that asked anew each time
|
|
116
|
-
* would never meet the approval of the last one. The newest standing,
|
|
117
|
-
* unspent request with the same kind, subject, requester and fields gives
|
|
118
|
-
* its `at`; with none, `now`.
|
|
119
|
-
*/
|
|
120
|
-
export declare function requestedAt(op: string, request: Omit<GatedRequest, "at">, options?: {
|
|
121
|
-
now?: string;
|
|
122
|
-
cwd?: string;
|
|
123
|
-
ledger?: Pick<GatedRequestLedger, "readGatedRequests">;
|
|
124
|
-
}): Promise<string>;
|
|
125
|
-
/** The digest `requestGate` puts in `fields.proof` for an attachment. */
|
|
126
|
-
export declare const attachmentDigest: (attachment: string) => string;
|
|
127
|
-
export interface GatedStateOpInput {
|
|
128
|
-
op: string;
|
|
129
|
-
/** The request, less `at`, which {@link requestedAt} fills. */
|
|
130
|
-
request: Omit<GatedRequest, "at"> & {
|
|
131
|
-
at?: string;
|
|
132
|
-
};
|
|
133
|
-
rules: GatedRequestRules;
|
|
134
|
-
description?: string;
|
|
135
|
-
expiry?: string;
|
|
136
|
-
base?: string;
|
|
137
|
-
/** A document the request carries, such as a migration's proof; its digest joins the request. */
|
|
138
|
-
attachment?: string;
|
|
139
|
-
cwd?: string;
|
|
140
|
-
now?: string;
|
|
141
|
-
runId?: string;
|
|
142
|
-
commit?: string;
|
|
143
|
-
ledger?: GatedRequestLedger;
|
|
144
|
-
gates?: RequestGateInput["gates"];
|
|
145
|
-
/**
|
|
146
|
-
* A last check just before the spend, for a fact that can change while the
|
|
147
|
-
* request waited (a run that may hold the lock came back). A string refuses
|
|
148
|
-
* the operation with that reason, and the approval is not spent.
|
|
149
|
-
*/
|
|
150
|
-
beforeSpend?: () => Promise<string | undefined>;
|
|
112
|
+
export { attachmentDigest, requestedAt, type GatedRequestLedger } from "@intentius/chant/lifecycle/gated-op";
|
|
113
|
+
export type { GatedOpInput as GatedStateOpInput, GatedOpResult as GatedStateOpResult } from "@intentius/chant/lifecycle/gated-op";
|
|
114
|
+
/** Run `act` once its request is approved: chant core's {@link gatedOp}. */
|
|
115
|
+
export declare const gatedStateOp: typeof gatedOp;
|
|
116
|
+
/** The digest a request binds, for a caller that prints it before it asks. */
|
|
117
|
+
export declare const stateOpDigest: (op: string, request: GatedRequest) => string;
|
|
118
|
+
/** A root's backend, read the way export and release read it. */
|
|
119
|
+
export interface RootBackendRun extends RootRun {
|
|
151
120
|
/**
|
|
152
|
-
*
|
|
153
|
-
*
|
|
121
|
+
* Run `init` in a data dir of its own (a new temp dir as `TF_DATA_DIR`,
|
|
122
|
+
* removed after), so the checkout's `.terraform` is left alone. Default
|
|
123
|
+
* true. Pass false for a root another tool initialised in `dir` with `env`,
|
|
124
|
+
* such as a Terragrunt unit.
|
|
154
125
|
*/
|
|
155
|
-
|
|
126
|
+
init?: boolean;
|
|
127
|
+
/** The backend's HTTP calls, for tests. */
|
|
128
|
+
fetch?: StoreFetch;
|
|
129
|
+
}
|
|
130
|
+
/** Where a root's state is: a state object, or a GitLab-managed state (./state/gitlab.ts), which the lock verdict refuses and export and release read. */
|
|
131
|
+
type RootStateAt = StateObject | GitLabState;
|
|
132
|
+
export interface TerraformStateExportInput extends Omit<StateExportInput, "source" | "subject">, RootBackendRun {
|
|
156
133
|
}
|
|
157
|
-
/**
|
|
158
|
-
export
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
recorded: boolean;
|
|
134
|
+
/**
|
|
135
|
+
* chant core's state export (`exportStateVersion`) of one root: its backend
|
|
136
|
+
* read by an init of its own, its versions read from the bucket or container
|
|
137
|
+
* (`./state/versions.ts`). Throws `StateExportError` for a backend that keeps
|
|
138
|
+
* no versions chant reads.
|
|
139
|
+
*/
|
|
140
|
+
export declare function terraformStateExport(input: TerraformStateExportInput): Promise<StateExportOutcome>;
|
|
141
|
+
/**
|
|
142
|
+
* A root's lock as chant core's lock release reads it: the lock its store
|
|
143
|
+
* holds (`StateStore.heldLock`: the s3 lock file, the gcs lock object, whose
|
|
144
|
+
* generation is the ID the binary takes, the azurerm lease), released with
|
|
145
|
+
* the binary's fixed `force-unlock` of that ID. A GitLab-managed state's lock
|
|
146
|
+
* is read by asking for it and released by its ID on the unlock address,
|
|
147
|
+
* which GitLab refuses for any other lock. A local state's lock goes with
|
|
148
|
+
* the process that took it, so it is refused.
|
|
149
|
+
*/
|
|
150
|
+
export declare function terraformLockSource(r: RootRun & {
|
|
151
|
+
object: RootStateAt;
|
|
152
|
+
fetch?: StoreFetch;
|
|
153
|
+
}): StateLockSource | {
|
|
154
|
+
refused: string;
|
|
179
155
|
};
|
|
156
|
+
export interface TerraformStateUnlockInput extends Omit<StateUnlockInput, "lock" | "subject">, RootBackendRun {
|
|
157
|
+
}
|
|
180
158
|
/**
|
|
181
|
-
*
|
|
182
|
-
*
|
|
183
|
-
*
|
|
184
|
-
*
|
|
185
|
-
* cannot be written is reported as `recorded: false`; the act already ran.
|
|
159
|
+
* chant core's lock release (`releaseStateLock`) of one root's state: its
|
|
160
|
+
* backend read by an init of its own, the lock read from the store, released
|
|
161
|
+
* by `force-unlock` in the same data dir. Throws `StateUnlockError` for a
|
|
162
|
+
* backend whose lock chant does not read.
|
|
186
163
|
*/
|
|
187
|
-
export declare function
|
|
188
|
-
digest: string;
|
|
189
|
-
request: GatedRequest;
|
|
190
|
-
approvedBy: string;
|
|
191
|
-
}) => Promise<{
|
|
192
|
-
output: T;
|
|
193
|
-
detail?: Record<string, string | number | boolean>;
|
|
194
|
-
}>): Promise<GatedStateOpResult<T>>;
|
|
195
|
-
/** The digest a request binds, for a caller that prints it before it asks. */
|
|
196
|
-
export declare const stateOpDigest: (op: string, request: GatedRequest) => string;
|
|
164
|
+
export declare function terraformStateUnlock(input: TerraformStateUnlockInput): Promise<StateUnlockOutcome>;
|
|
197
165
|
/** The step input the gated capabilities share: the root and the request's rules. */
|
|
198
166
|
interface GatedRootInput {
|
|
199
167
|
root: string;
|
|
@@ -256,5 +224,4 @@ export declare const terraformStateOpCapabilities: readonly [Capability<StateUnl
|
|
|
256
224
|
root: string;
|
|
257
225
|
planDigest: string;
|
|
258
226
|
}>];
|
|
259
|
-
export {};
|
|
260
227
|
//# sourceMappingURL=state-ops.d.ts.map
|
package/dist/state-ops.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"state-ops.d.ts","sourceRoot":"","sources":["../src/state-ops.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"state-ops.d.ts","sourceRoot":"","sources":["../src/state-ops.ts"],"names":[],"mappings":"AAuCA,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,wCAAwC,CAAC;AACzF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,OAAO,EAAsB,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AACzH,OAAO,EAAE,OAAO,EAAE,MAAM,qCAAqC,CAAC;AAC9D,OAAO,EAAwC,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACrI,OAAO,EAAoE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAGvL,OAAO,EAA8C,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,EAAwB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EAAwD,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACxG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIvD,iGAAiG;AACjG,eAAO,MAAM,SAAS;aACpB,MAAM,EAAE,WAAW;aACnB,OAAO,EAAE,YAAY;aACrB,MAAM,EAAE,iBAAiB;CACjB,CAAC;AAEX,2CAA2C;AAC3C,eAAO,MAAM,cAAc;aACzB,MAAM,EAAE,QAAQ;aAChB,OAAO,EAAE,SAAS;aAClB,MAAM,EAAE,cAAc;CACd,CAAC;AAEX,sEAAsE;AACtE,qBAAa,YAAa,SAAQ,KAAK;IAEnC,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM;IAJvB,YACW,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAItB;CACF;AAED,kHAAkH;AAClH,qBAAa,mBAAoB,SAAQ,KAAK;IAG1C,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM;IAL1B,QAAQ,CAAC,QAAQ,IAAsB;IACvC,YACW,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EAIzB;CACF;AAED,kDAAkD;AAClD,MAAM,WAAW,OAAO;IACtB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAWD,iGAAiG;AACjG,wBAAsB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5H;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGjF;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGjH;AAED,iEAAiE;AACjE,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAcD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEnG;AAED,gGAAgG;AAChG,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC5C,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,CAAC,EAAE,OAAO,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GACxI,OAAO,CAAC,YAAY,CAAC,CAQvB;AAED,mFAAmF;AACnF,wBAAsB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAElH;AAKD,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAC7G,YAAY,EAAE,YAAY,IAAI,iBAAiB,EAAE,aAAa,IAAI,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAClI,4EAA4E;AAC5E,eAAO,MAAM,YAAY,gBAAU,CAAC;AAEpC,8EAA8E;AAC9E,eAAO,MAAM,aAAa,OAAQ,MAAM,WAAW,YAAY,KAAG,MAAyC,CAAC;AAI5G,iEAAiE;AACjE,MAAM,WAAW,cAAe,SAAQ,OAAO;IAC7C;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2CAA2C;IAC3C,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAqBD,0JAA0J;AAC1J,KAAK,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAmB7C,MAAM,WAAW,yBAA0B,SAAQ,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,SAAS,CAAC,EAAE,cAAc;CAAG;AAElH;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAIxG;AAKD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,KAAK,CAAC,EAAE,UAAU,CAAA;CAAE,GAAG,eAAe,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CA+BnI;AAED,MAAM,WAAW,yBAA0B,SAAQ,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,cAAc;CAAG;AAEhH;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAMxG;AAID,qFAAqF;AACrF,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,QAAQ,CAAC,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;CACtC;AAED,gFAAgF;AAChF,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,EAAE,EAAE,MAAM,CAAC;IACX,mGAAmG;IACnG,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,sHAAsH;AACtH,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACxD,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC5F,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qFAAqF;AACrF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC9B;AAsBD,eAAO,MAAM,8BAA8B,EAAE,UAAU,CAAC,oBAAoB,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAgBzG,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,UAAU,CAAC,kBAAkB,EAAE;IAAE,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAqB5F,CAAC;AAQF,eAAO,MAAM,uBAAuB,EAAE,UAAU,CAAC,aAAa,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAiBnG,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,4BAA4B;UAnE6C,MAAM;QAAM,MAAM;;WAkBrB,MAAM,EAAE;;UA6BnB,MAAM;gBAAc,MAAM;GAoB0C,CAAC"}
|