@intentius/chant 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/__fixtures__/agent-guard/plywood.d.ts +8 -0
- package/dist/__fixtures__/agent-guard/plywood.d.ts.map +1 -0
- package/dist/__fixtures__/agent-guard/plywood.js +19 -0
- package/dist/__fixtures__/agent-guard/terragucci.d.ts +8 -0
- package/dist/__fixtures__/agent-guard/terragucci.d.ts.map +1 -0
- package/dist/__fixtures__/agent-guard/terragucci.js +30 -0
- package/dist/__fixtures__/gated-ledger.d.ts +10 -0
- package/dist/__fixtures__/gated-ledger.d.ts.map +1 -0
- package/dist/__fixtures__/gated-ledger.js +51 -0
- package/dist/agent-guard.d.ts +143 -0
- package/dist/agent-guard.d.ts.map +1 -0
- package/dist/agent-guard.js +456 -0
- package/dist/ci-commit.d.ts +54 -3
- package/dist/ci-commit.d.ts.map +1 -1
- package/dist/ci-commit.js +69 -7
- package/dist/ci-own-jobs.d.ts +81 -0
- package/dist/ci-own-jobs.d.ts.map +1 -0
- package/dist/ci-own-jobs.js +234 -0
- package/dist/ci-product.d.ts +39 -0
- package/dist/ci-product.d.ts.map +1 -1
- package/dist/ci-product.js +40 -0
- package/dist/cli/handlers/approve.d.ts +5 -1
- package/dist/cli/handlers/approve.d.ts.map +1 -1
- package/dist/cli/handlers/approve.js +17 -11
- package/dist/cli/handlers/build.d.ts +1 -1
- package/dist/cli/handlers/build.d.ts.map +1 -1
- package/dist/cli/handlers/build.js +88 -2
- package/dist/cli/handlers/commit.d.ts.map +1 -1
- package/dist/cli/handlers/commit.js +3 -1
- package/dist/cli/handlers/notify-relay.d.ts +18 -1
- package/dist/cli/handlers/notify-relay.d.ts.map +1 -1
- package/dist/cli/handlers/notify-relay.js +90 -14
- package/dist/cli/handlers/pr.d.ts.map +1 -1
- package/dist/cli/handlers/pr.js +3 -1
- package/dist/cli/handlers/release.d.ts +9 -1
- package/dist/cli/handlers/release.d.ts.map +1 -1
- package/dist/cli/handlers/release.js +34 -6
- package/dist/cli/handlers/run-generate.d.ts.map +1 -1
- package/dist/cli/handlers/run-generate.js +2 -1
- package/dist/cli/main.d.ts.map +1 -1
- package/dist/cli/main.js +21 -1
- package/dist/cli/parse-args.d.ts.map +1 -1
- package/dist/cli/parse-args.js +60 -4
- package/dist/cli/registry.d.ts +16 -0
- package/dist/cli/registry.d.ts.map +1 -1
- package/dist/components/pr-env-components.d.ts +65 -0
- package/dist/components/pr-env-components.d.ts.map +1 -0
- package/dist/components/pr-env-components.js +163 -0
- package/dist/components/pr-policy.d.ts +15 -0
- package/dist/components/pr-policy.d.ts.map +1 -1
- package/dist/components/pr-policy.js +24 -1
- package/dist/components/release-compile.d.ts +15 -3
- package/dist/components/release-compile.d.ts.map +1 -1
- package/dist/components/release-compile.js +66 -15
- package/dist/gate-policy.d.ts +14 -1
- package/dist/gate-policy.d.ts.map +1 -1
- package/dist/gate-policy.js +16 -6
- package/dist/lexicon.d.ts +17 -1
- package/dist/lexicon.d.ts.map +1 -1
- package/dist/lexicon.js +1 -0
- package/dist/lifecycle/gated-op.d.ts +95 -0
- package/dist/lifecycle/gated-op.d.ts.map +1 -0
- package/dist/lifecycle/gated-op.js +96 -0
- package/dist/lifecycle/git.d.ts.map +1 -1
- package/dist/lifecycle/git.js +83 -2
- package/dist/notify-relay-repo.d.ts +131 -0
- package/dist/notify-relay-repo.d.ts.map +1 -0
- package/dist/notify-relay-repo.js +202 -0
- package/dist/notify-relay.d.ts +25 -1
- package/dist/notify-relay.d.ts.map +1 -1
- package/dist/notify-relay.js +28 -2
- package/dist/op/op-waves-capability.js +2 -2
- package/dist/policy-engine.d.ts +95 -0
- package/dist/policy-engine.d.ts.map +1 -0
- package/dist/policy-engine.js +158 -0
- package/dist/release-floors.d.ts +1 -1
- package/dist/release-floors.js +1 -1
- package/dist/state-export.d.ts +126 -0
- package/dist/state-export.d.ts.map +1 -0
- package/dist/state-export.js +157 -0
- package/dist/state-migration.d.ts +148 -0
- package/dist/state-migration.d.ts.map +1 -0
- package/dist/state-migration.js +147 -0
- package/dist/state-unlock.d.ts +167 -0
- package/dist/state-unlock.d.ts.map +1 -0
- package/dist/state-unlock.js +197 -0
- package/dist/wave-runtime.mjs +329 -329
- package/dist/workspace/declaration.schema.json +1 -1
- package/dist/workspace/release-workflow.d.ts +10 -0
- package/dist/workspace/release-workflow.d.ts.map +1 -1
- package/dist/workspace/release-workflow.js +8 -3
- package/package.json +1 -1
- package/src/__fixtures__/agent-guard/plywood.ts +27 -0
- package/src/__fixtures__/agent-guard/terragucci.ts +39 -0
- package/src/__fixtures__/gated-ledger.ts +58 -0
- package/src/agent-guard.test.ts +320 -0
- package/src/agent-guard.ts +548 -0
- package/src/ci-commit.test.ts +50 -2
- package/src/ci-commit.ts +93 -9
- package/src/ci-own-jobs.test.ts +109 -0
- package/src/ci-own-jobs.ts +253 -0
- package/src/ci-product.ts +81 -0
- package/src/cli/handlers/approve-cwd.test.ts +112 -0
- package/src/cli/handlers/approve.ts +22 -11
- package/src/cli/handlers/build-own-jobs.test.ts +80 -0
- package/src/cli/handlers/build-pr-loop-control.test.ts +88 -0
- package/src/cli/handlers/build-run-group.test.ts +60 -0
- package/src/cli/handlers/build.ts +83 -3
- package/src/cli/handlers/commit.ts +3 -0
- package/src/cli/handlers/notify-relay.ts +99 -17
- package/src/cli/handlers/pr.ts +3 -1
- package/src/cli/handlers/release-cut-archives.test.ts +21 -0
- package/src/cli/handlers/release.ts +31 -6
- package/src/cli/handlers/run-generate.ts +2 -1
- package/src/cli/main.ts +21 -1
- package/src/cli/parse-args.ts +45 -3
- package/src/cli/registry.ts +16 -0
- package/src/components/pr-env-components.test.ts +138 -0
- package/src/components/pr-env-components.ts +214 -0
- package/src/components/pr-policy.test.ts +41 -1
- package/src/components/pr-policy.ts +25 -1
- package/src/components/release-compile.test.ts +47 -0
- package/src/components/release-compile.ts +70 -13
- package/src/gate-policy-bundle.test.ts +14 -0
- package/src/gate-policy.test.ts +7 -0
- package/src/gate-policy.ts +22 -7
- package/src/lexicon.ts +18 -1
- package/src/lifecycle/gated-op.ts +158 -0
- package/src/lifecycle/git.test.ts +92 -0
- package/src/lifecycle/git.ts +71 -2
- package/src/notify-relay-repo.test.ts +284 -0
- package/src/notify-relay-repo.ts +234 -0
- package/src/notify-relay.test.ts +12 -0
- package/src/notify-relay.ts +30 -3
- package/src/op/op-waves-capability.ts +2 -2
- package/src/policy-engine.test.ts +163 -0
- package/src/policy-engine.ts +201 -0
- package/src/release-floors.ts +1 -1
- package/src/state-export.test.ts +125 -0
- package/src/state-export.ts +228 -0
- package/src/state-migration.test.ts +134 -0
- package/src/state-migration.ts +237 -0
- package/src/state-unlock.test.ts +166 -0
- package/src/state-unlock.ts +294 -0
- package/src/workspace/declaration.schema.json +1 -1
- package/src/workspace/release-workflow.test.ts +34 -0
- package/src/workspace/release-workflow.ts +17 -3
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A state export behind a gated request (#4762): one version of a state,
|
|
3
|
+
* written to the machine of the person who asks once someone else approved
|
|
4
|
+
* it, and recorded with who exported which version.
|
|
5
|
+
*
|
|
6
|
+
* Engine-neutral. The engine's adapter is a {@link StateVersionSource}: where
|
|
7
|
+
* the state is, the version it holds now, and one version's bytes. The
|
|
8
|
+
* terraform lexicon builds one from a root's backend
|
|
9
|
+
* (`@intentius/chant-lexicon-terraform/state-export`); a Pulumi stack's
|
|
10
|
+
* export (`pulumi stack export --version`) fits the same three calls. The
|
|
11
|
+
* product passes its words: the op the requests wait at, the approve
|
|
12
|
+
* command it prints, the name of the file.
|
|
13
|
+
*
|
|
14
|
+
* A state holds every secret its resources hold, so the export goes to the
|
|
15
|
+
* requester only:
|
|
16
|
+
*
|
|
17
|
+
* - never in CI, where a file can become a job artifact readable by everyone
|
|
18
|
+
* who can read the repository ({@link CI_MARKERS}), unless the caller
|
|
19
|
+
* says otherwise;
|
|
20
|
+
* - never inside a git working tree, where it could be committed;
|
|
21
|
+
* - never over a file, and mode 0600. With no `out`, a new private
|
|
22
|
+
* directory in the system's temp dir.
|
|
23
|
+
*
|
|
24
|
+
* The first call reads the version's metadata only, records the pending
|
|
25
|
+
* request (kind `state-export`, subject the root or stack, fields the
|
|
26
|
+
* location and the version id) and answers `waiting` with the approve
|
|
27
|
+
* command. Once someone other than the requester approved its digest, the
|
|
28
|
+
* next call spends the approval, reads the version, writes the file, and the
|
|
29
|
+
* finished line records the version id and the digest of the bytes written,
|
|
30
|
+
* never their contents. A request exports once.
|
|
31
|
+
*/
|
|
32
|
+
import { createHash } from "node:crypto";
|
|
33
|
+
import { existsSync, mkdtempSync, realpathSync, writeFileSync } from "node:fs";
|
|
34
|
+
import { tmpdir } from "node:os";
|
|
35
|
+
import { basename, dirname, join, resolve } from "node:path";
|
|
36
|
+
import { CHANT_EXIT } from "./exit-codes.js";
|
|
37
|
+
import { gatedOp } from "./lifecycle/gated-op.js";
|
|
38
|
+
import { NEXT_RELEASE } from "./release-floors.js";
|
|
39
|
+
/** The first chant with the engine-neutral state export (#4762). */
|
|
40
|
+
export const STATE_EXPORT_FLOOR = NEXT_RELEASE;
|
|
41
|
+
/** The CI variables that mark a job, where an export would become an artifact. */
|
|
42
|
+
export const CI_MARKERS = ["CI", "GITHUB_ACTIONS", "GITLAB_CI", "FORGEJO_ACTIONS", "BUILDKITE", "JENKINS_URL"];
|
|
43
|
+
/** The CI marker set in `env`, or undefined when none is. */
|
|
44
|
+
export function ciMarker(env) {
|
|
45
|
+
return CI_MARKERS.find((k) => env[k] !== undefined && env[k] !== "" && env[k] !== "false");
|
|
46
|
+
}
|
|
47
|
+
/** The git working tree `path` sits in, or undefined. */
|
|
48
|
+
export function enclosingWorkTree(path) {
|
|
49
|
+
let dir = resolve(path);
|
|
50
|
+
try {
|
|
51
|
+
dir = realpathSync(dir);
|
|
52
|
+
}
|
|
53
|
+
catch {
|
|
54
|
+
// A path that does not exist is walked as given.
|
|
55
|
+
}
|
|
56
|
+
for (;;) {
|
|
57
|
+
if (existsSync(join(dir, ".git")))
|
|
58
|
+
return dir;
|
|
59
|
+
const up = dirname(dir);
|
|
60
|
+
if (up === dir)
|
|
61
|
+
return undefined;
|
|
62
|
+
dir = up;
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
/** Why an export may not go to `out`, or undefined when it may. */
|
|
66
|
+
export function exportRefusal(out) {
|
|
67
|
+
const abs = resolve(out);
|
|
68
|
+
if (!existsSync(dirname(abs)))
|
|
69
|
+
return `${dirname(abs)} is not a directory`;
|
|
70
|
+
if (existsSync(abs))
|
|
71
|
+
return `${abs} is there already, and an export never writes over a file; name a new one`;
|
|
72
|
+
const tree = enclosingWorkTree(dirname(abs));
|
|
73
|
+
if (tree)
|
|
74
|
+
return `${abs} is inside the git working tree ${tree}, where a state could be committed; name a path outside it`;
|
|
75
|
+
return undefined;
|
|
76
|
+
}
|
|
77
|
+
/** A refusal before anything is asked: a version the store does not have, a destination the export may not use. */
|
|
78
|
+
export class StateExportError extends Error {
|
|
79
|
+
constructor(message) {
|
|
80
|
+
super(message);
|
|
81
|
+
this.name = "StateExportError";
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
const sha = (body) => `sha256:${createHash("sha256").update(body).digest("hex")}`;
|
|
85
|
+
const defaultName = (subject, version) => `${subject.replace(/[^\w.-]+/g, "_")}.${version.replace(/[^\w.-]+/g, "_")}.state`;
|
|
86
|
+
/**
|
|
87
|
+
* Ask for, or with an approval write, one version of a state. Throws
|
|
88
|
+
* {@link StateExportError} before anything is asked when the version or the
|
|
89
|
+
* destination is refused.
|
|
90
|
+
*/
|
|
91
|
+
export async function exportStateVersion(input) {
|
|
92
|
+
const { source, words } = input;
|
|
93
|
+
const env = input.env ?? process.env;
|
|
94
|
+
const marker = input.allowCi ? undefined : ciMarker(env);
|
|
95
|
+
if (marker)
|
|
96
|
+
throw new StateExportError(`an export goes to the requester's machine only, and ${marker} is set, so this is a CI job whose files can become artifacts; ask for it from your own machine`);
|
|
97
|
+
if (input.out !== undefined) {
|
|
98
|
+
const why = exportRefusal(input.out);
|
|
99
|
+
if (why)
|
|
100
|
+
throw new StateExportError(why);
|
|
101
|
+
}
|
|
102
|
+
const location = source.location;
|
|
103
|
+
let version = input.version;
|
|
104
|
+
if (!version) {
|
|
105
|
+
const now = await source.current();
|
|
106
|
+
if (!now.exists)
|
|
107
|
+
throw new StateExportError(`${location} holds no state`);
|
|
108
|
+
if (!now.versionId)
|
|
109
|
+
throw new StateExportError(`${location} keeps no versions, so there is no version id to export: ${now.off ?? "the store gave none"}`);
|
|
110
|
+
version = now.versionId;
|
|
111
|
+
}
|
|
112
|
+
else if (!(await source.hasVersion(version))) {
|
|
113
|
+
throw new StateExportError(`${location} has no version ${version}; a lifecycle rule may have expired it`);
|
|
114
|
+
}
|
|
115
|
+
const versionId = version;
|
|
116
|
+
const result = await gatedOp({
|
|
117
|
+
op: words.op,
|
|
118
|
+
request: { kind: words.kind ?? "state-export", subject: input.subject, by: input.by, fields: { location, version_id: versionId } },
|
|
119
|
+
rules: input.rules,
|
|
120
|
+
description: `state export: ${input.subject} version ${versionId}, for ${input.by}`,
|
|
121
|
+
expiry: input.expiry ?? "48h",
|
|
122
|
+
...(input.base ? { base: input.base } : {}),
|
|
123
|
+
...(input.cwd ? { cwd: input.cwd } : {}),
|
|
124
|
+
...(input.now ? { now: input.now } : {}),
|
|
125
|
+
...(input.ledger ? { ledger: input.ledger } : {}),
|
|
126
|
+
}, async ({ approvedBy }) => {
|
|
127
|
+
const name = (words.fileName ?? defaultName)(input.subject, versionId);
|
|
128
|
+
const file = input.out !== undefined ? resolve(input.out) : join(mkdtempSync(join(tmpdir(), words.tmpPrefix ?? "chant-export-")), basename(name));
|
|
129
|
+
// Checked again: the destination may have changed while the request waited.
|
|
130
|
+
const why = exportRefusal(file);
|
|
131
|
+
if (why)
|
|
132
|
+
throw new StateExportError(why);
|
|
133
|
+
const body = await source.readVersion(versionId);
|
|
134
|
+
if (body === undefined)
|
|
135
|
+
throw new StateExportError(`${location} has no version ${versionId}; it was deleted since the request`);
|
|
136
|
+
writeFileSync(file, body, { mode: 0o600, flag: "wx" });
|
|
137
|
+
const contentDigest = sha(body);
|
|
138
|
+
return { output: { file, contentDigest }, detail: { by: input.by, location, version_id: versionId, content_digest: contentDigest, approved_by: approvedBy } };
|
|
139
|
+
});
|
|
140
|
+
const command = (digest, fallback) => (words.approveCommand ? words.approveCommand(input.subject, digest) : fallback);
|
|
141
|
+
const at = { digest: result.digest, version: versionId, location };
|
|
142
|
+
switch (result.status) {
|
|
143
|
+
case "done":
|
|
144
|
+
return { status: "written", exit: CHANT_EXIT.done, ...at, file: result.output.file, approvedBy: result.approvedBy, contentDigest: result.output.contentDigest, recorded: result.recorded };
|
|
145
|
+
case "waiting":
|
|
146
|
+
return { status: "waiting", exit: CHANT_EXIT.waiting, ...at, command: command(result.digest, result.command) };
|
|
147
|
+
case "refused":
|
|
148
|
+
return { status: "refused", exit: CHANT_EXIT.waiting, ...at, command: command(result.digest, result.command), by: result.by, reason: result.reason };
|
|
149
|
+
case "spent":
|
|
150
|
+
return { status: "spent", exit: CHANT_EXIT.failed, ...at };
|
|
151
|
+
case "held":
|
|
152
|
+
// An export takes no last check, so nothing holds it; kept for the type.
|
|
153
|
+
return { status: "failed", exit: CHANT_EXIT.failed, ...at, error: new StateExportError(result.reason), recorded: false };
|
|
154
|
+
case "failed":
|
|
155
|
+
return { status: "failed", exit: CHANT_EXIT.failed, ...at, error: result.error, recorded: result.recorded };
|
|
156
|
+
}
|
|
157
|
+
}
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
import { type GatedRequestLedger } from "./lifecycle/gated-op.js";
|
|
2
|
+
import type { GatedRequestRules } from "./lifecycle/gated-request.js";
|
|
3
|
+
/** The first chant with the engine-neutral state migration (#4762). */
|
|
4
|
+
export declare const STATE_MIGRATION_FLOOR = "0.124.77";
|
|
5
|
+
/** A state as a migration binds it: its version id, when the store keeps versions, and its digest, null for no state. */
|
|
6
|
+
export interface MigrationStateAt {
|
|
7
|
+
version_id?: string;
|
|
8
|
+
digest: string | null;
|
|
9
|
+
}
|
|
10
|
+
/** What a plan of a root against a state found. */
|
|
11
|
+
export interface MigrationCheck {
|
|
12
|
+
/** Each change, as `<address>: <actions>`. None: the root plans clean. */
|
|
13
|
+
changes: string[];
|
|
14
|
+
/** The engine's own summary line. */
|
|
15
|
+
summary: string;
|
|
16
|
+
}
|
|
17
|
+
/** One root of a migration's plan: never its state's contents. */
|
|
18
|
+
export interface MigrationRootPlan {
|
|
19
|
+
root: string;
|
|
20
|
+
/** Where its state is, as the record names it. */
|
|
21
|
+
location?: string;
|
|
22
|
+
before: MigrationStateAt;
|
|
23
|
+
/** The new state's digest, and its version id once written. */
|
|
24
|
+
after: {
|
|
25
|
+
digest: string;
|
|
26
|
+
version_id?: string;
|
|
27
|
+
};
|
|
28
|
+
/** The plan against the new state, before anything is written. */
|
|
29
|
+
proof: MigrationCheck;
|
|
30
|
+
/** The plan against the real state, after the write. */
|
|
31
|
+
verify?: MigrationCheck;
|
|
32
|
+
}
|
|
33
|
+
/** The engine's half of a migration's write. */
|
|
34
|
+
export interface StateMigrationEngine {
|
|
35
|
+
/** Take the lock of every state the migration writes or reads. Throws when one is held, having released what it took. Answers the release. */
|
|
36
|
+
lock(): Promise<() => Promise<void>>;
|
|
37
|
+
/** A root's state now, read under the locks. */
|
|
38
|
+
current(root: string): Promise<MigrationStateAt>;
|
|
39
|
+
/** Write every new state, in the engine's order. Throws at the first that fails. */
|
|
40
|
+
write(): Promise<void>;
|
|
41
|
+
/** After the write: the root planned against its real state, its version now, and its version before when only the write named it (a snapshot). */
|
|
42
|
+
verify(root: string): Promise<MigrationCheck & {
|
|
43
|
+
version_id?: string;
|
|
44
|
+
before_version_id?: string;
|
|
45
|
+
}>;
|
|
46
|
+
}
|
|
47
|
+
/** The product's words for a migration. */
|
|
48
|
+
export interface StateMigrationWords {
|
|
49
|
+
/** The op the requests wait at, such as `tf-migrate`. */
|
|
50
|
+
op: string;
|
|
51
|
+
/** The request's kind. Default `migrate`. */
|
|
52
|
+
kind?: string;
|
|
53
|
+
approveCommand?: (subject: string, digest: string) => string;
|
|
54
|
+
}
|
|
55
|
+
export interface StateMigrationInput {
|
|
56
|
+
/** The migration's name: the gate its request waits at. */
|
|
57
|
+
name: string;
|
|
58
|
+
/** The requester. Their own approval never counts. */
|
|
59
|
+
by: string;
|
|
60
|
+
roots: MigrationRootPlan[];
|
|
61
|
+
engine: StateMigrationEngine;
|
|
62
|
+
words: StateMigrationWords;
|
|
63
|
+
/** The product's facts the request binds, such as the migration file's path and digest. */
|
|
64
|
+
fields?: Record<string, string>;
|
|
65
|
+
/** The product's facts the finished line adds, given how it ended. */
|
|
66
|
+
detail?: (result: StateMigrationResult) => Record<string, string | number | boolean>;
|
|
67
|
+
rules: GatedRequestRules;
|
|
68
|
+
description?: string;
|
|
69
|
+
cwd?: string;
|
|
70
|
+
base?: string;
|
|
71
|
+
/** How long a request waits for its approval. Default 48h. */
|
|
72
|
+
expiry?: string;
|
|
73
|
+
now?: string;
|
|
74
|
+
runId?: string;
|
|
75
|
+
commit?: string;
|
|
76
|
+
ledger?: GatedRequestLedger;
|
|
77
|
+
}
|
|
78
|
+
/** How the write ended, once approved. */
|
|
79
|
+
export interface StateMigrationResult {
|
|
80
|
+
status: "applied" | "moved" | "failed";
|
|
81
|
+
roots: MigrationRootPlan[];
|
|
82
|
+
/** The roots whose state is not the one planned. */
|
|
83
|
+
moved?: string[];
|
|
84
|
+
error?: string;
|
|
85
|
+
}
|
|
86
|
+
/** How a migration ended. `exit` is the code its command exits with. */
|
|
87
|
+
export type StateMigrationOutcome = {
|
|
88
|
+
status: "proof-failed";
|
|
89
|
+
exit: 1;
|
|
90
|
+
roots: MigrationRootPlan[];
|
|
91
|
+
failing: string[];
|
|
92
|
+
} | {
|
|
93
|
+
status: "waiting";
|
|
94
|
+
exit: 3;
|
|
95
|
+
digest: string;
|
|
96
|
+
command: string;
|
|
97
|
+
} | {
|
|
98
|
+
status: "refused";
|
|
99
|
+
exit: 3;
|
|
100
|
+
digest: string;
|
|
101
|
+
command: string;
|
|
102
|
+
by: string;
|
|
103
|
+
reason: string;
|
|
104
|
+
}
|
|
105
|
+
/** It applied already; a migration applies once. */
|
|
106
|
+
| {
|
|
107
|
+
status: "spent";
|
|
108
|
+
exit: 0;
|
|
109
|
+
digest: string;
|
|
110
|
+
} | {
|
|
111
|
+
status: "applied";
|
|
112
|
+
exit: 0;
|
|
113
|
+
digest: string;
|
|
114
|
+
approvedBy: string;
|
|
115
|
+
result: StateMigrationResult;
|
|
116
|
+
recorded: boolean;
|
|
117
|
+
}
|
|
118
|
+
/** Under the locks a state was not the one planned: nothing was written, and the approval is spent. */
|
|
119
|
+
| {
|
|
120
|
+
status: "moved";
|
|
121
|
+
exit: 4;
|
|
122
|
+
digest: string;
|
|
123
|
+
approvedBy: string;
|
|
124
|
+
result: StateMigrationResult;
|
|
125
|
+
recorded: boolean;
|
|
126
|
+
} | {
|
|
127
|
+
status: "failed";
|
|
128
|
+
exit: 1;
|
|
129
|
+
digest: string;
|
|
130
|
+
error: string;
|
|
131
|
+
result?: StateMigrationResult;
|
|
132
|
+
recorded: boolean;
|
|
133
|
+
};
|
|
134
|
+
/** The finished line's flat facts: how it ended, and each root's location, versions and digests. */
|
|
135
|
+
export declare function migrationFacts(result: StateMigrationResult): Record<string, string | number | boolean>;
|
|
136
|
+
/**
|
|
137
|
+
* Write the migration under the locks: check nothing moved, write, verify.
|
|
138
|
+
* The locks are released whatever happens. {@link runStateMigration} runs it
|
|
139
|
+
* once its request is approved; a migration whose approval an op wave's hold
|
|
140
|
+
* decided already (the wave's own gate) runs it directly.
|
|
141
|
+
*/
|
|
142
|
+
export declare function writeStateMigration(engine: StateMigrationEngine, roots: MigrationRootPlan[]): Promise<StateMigrationResult>;
|
|
143
|
+
/**
|
|
144
|
+
* Ask for, or with an approval write, a proved migration. Refuses a plan
|
|
145
|
+
* whose proof shows a change before anything is asked.
|
|
146
|
+
*/
|
|
147
|
+
export declare function runStateMigration(input: StateMigrationInput): Promise<StateMigrationOutcome>;
|
|
148
|
+
//# sourceMappingURL=state-migration.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"state-migration.d.ts","sourceRoot":"","sources":["../src/state-migration.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A state migration behind a gated request (#4762): new states for several
|
|
3
|
+
* roots or stacks, proved before anyone approves them, written once someone
|
|
4
|
+
* other than the requester approved that proof, under every state's lock,
|
|
5
|
+
* and checked again after the write.
|
|
6
|
+
*
|
|
7
|
+
* Engine-neutral. The engine plans the migration (each root's state before,
|
|
8
|
+
* its new state's digest, and a proof that the root plans no change against
|
|
9
|
+
* it) and supplies a {@link StateMigrationEngine} for the write: take the
|
|
10
|
+
* locks, read a root's state now, write the new states, and plan each root
|
|
11
|
+
* again against its real state. The terraform lexicon plans moves of
|
|
12
|
+
* resources between roots and reverts to a recorded version
|
|
13
|
+
* (`@intentius/chant-lexicon-terraform/state-migration`); a move of
|
|
14
|
+
* resources between Pulumi stacks fits the same calls. The product passes
|
|
15
|
+
* its words: the op, the migration's name, the approve command, and the
|
|
16
|
+
* facts its own history reads back.
|
|
17
|
+
*
|
|
18
|
+
* 1. A plan whose proof shows a change is refused before anything is
|
|
19
|
+
* asked (`proof-failed`).
|
|
20
|
+
* 2. The request (kind `migrate`, subject the migration's name) carries
|
|
21
|
+
* the plan as its attachment, so its digest binds every root's state
|
|
22
|
+
* before and after. A state that moves before the approval asks again.
|
|
23
|
+
* 3. Approved, the approval is spent, every lock is taken, and each root's
|
|
24
|
+
* state is read again. A state that is not the one planned refuses the
|
|
25
|
+
* write (`moved`), with nothing written.
|
|
26
|
+
* 4. The new states are written, every root plans against its real state,
|
|
27
|
+
* and a change left anywhere fails the migration. The locks are
|
|
28
|
+
* released whatever happens. The finished line holds each root's
|
|
29
|
+
* location and its version and digest before and after, never a
|
|
30
|
+
* state's contents.
|
|
31
|
+
*/
|
|
32
|
+
import { CHANT_EXIT } from "./exit-codes.js";
|
|
33
|
+
import { gatedOp } from "./lifecycle/gated-op.js";
|
|
34
|
+
import { NEXT_RELEASE } from "./release-floors.js";
|
|
35
|
+
/** The first chant with the engine-neutral state migration (#4762). */
|
|
36
|
+
export const STATE_MIGRATION_FLOOR = NEXT_RELEASE;
|
|
37
|
+
const same = (a, b) => (a.version_id ?? undefined) === (b.version_id ?? undefined) && a.digest === b.digest;
|
|
38
|
+
/** The finished line's flat facts: how it ended, and each root's location, versions and digests. */
|
|
39
|
+
export function migrationFacts(result) {
|
|
40
|
+
const out = {
|
|
41
|
+
result: result.status === "moved" ? "refused" : result.status,
|
|
42
|
+
roots: result.roots.map((r) => r.root).join(","),
|
|
43
|
+
...(result.moved?.length ? { moved: result.moved.join(",") } : {}),
|
|
44
|
+
...(result.error ? { error: result.error.slice(0, 400) } : {}),
|
|
45
|
+
};
|
|
46
|
+
for (const r of result.roots) {
|
|
47
|
+
if (r.location)
|
|
48
|
+
out[`${r.root}.location`] = r.location;
|
|
49
|
+
if (r.before.version_id)
|
|
50
|
+
out[`${r.root}.before`] = r.before.version_id;
|
|
51
|
+
if (r.after.version_id)
|
|
52
|
+
out[`${r.root}.after`] = r.after.version_id;
|
|
53
|
+
if (r.before.digest)
|
|
54
|
+
out[`${r.root}.before_digest`] = r.before.digest;
|
|
55
|
+
if (r.after.digest)
|
|
56
|
+
out[`${r.root}.after_digest`] = r.after.digest;
|
|
57
|
+
}
|
|
58
|
+
return out;
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Write the migration under the locks: check nothing moved, write, verify.
|
|
62
|
+
* The locks are released whatever happens. {@link runStateMigration} runs it
|
|
63
|
+
* once its request is approved; a migration whose approval an op wave's hold
|
|
64
|
+
* decided already (the wave's own gate) runs it directly.
|
|
65
|
+
*/
|
|
66
|
+
export async function writeStateMigration(engine, roots) {
|
|
67
|
+
const release = await engine.lock();
|
|
68
|
+
try {
|
|
69
|
+
const moved = [];
|
|
70
|
+
for (const r of roots)
|
|
71
|
+
if (!same(await engine.current(r.root), r.before))
|
|
72
|
+
moved.push(r.root);
|
|
73
|
+
if (moved.length > 0)
|
|
74
|
+
return { status: "moved", roots, moved };
|
|
75
|
+
try {
|
|
76
|
+
await engine.write();
|
|
77
|
+
}
|
|
78
|
+
catch (e) {
|
|
79
|
+
return { status: "failed", roots, error: `the write failed: ${e.message}` };
|
|
80
|
+
}
|
|
81
|
+
const after = [];
|
|
82
|
+
for (const r of roots) {
|
|
83
|
+
const v = await engine.verify(r.root);
|
|
84
|
+
after.push({
|
|
85
|
+
...r,
|
|
86
|
+
...(v.before_version_id ? { before: { ...r.before, version_id: v.before_version_id } } : {}),
|
|
87
|
+
after: { ...r.after, ...(v.version_id ? { version_id: v.version_id } : {}) },
|
|
88
|
+
verify: { changes: v.changes, summary: v.summary },
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
const changed = after.filter((r) => r.verify.changes.length > 0).map((r) => r.root);
|
|
92
|
+
return changed.length > 0 ? { status: "failed", roots: after, error: `after the write, ${changed.join(", ")} plan changes` } : { status: "applied", roots: after };
|
|
93
|
+
}
|
|
94
|
+
finally {
|
|
95
|
+
await release();
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Ask for, or with an approval write, a proved migration. Refuses a plan
|
|
100
|
+
* whose proof shows a change before anything is asked.
|
|
101
|
+
*/
|
|
102
|
+
export async function runStateMigration(input) {
|
|
103
|
+
const failing = input.roots.filter((r) => r.proof.changes.length > 0).map((r) => r.root);
|
|
104
|
+
if (failing.length > 0)
|
|
105
|
+
return { status: "proof-failed", exit: CHANT_EXIT.failed, roots: input.roots, failing };
|
|
106
|
+
const roots = [...input.roots].sort((a, b) => (a.root < b.root ? -1 : a.root > b.root ? 1 : 0));
|
|
107
|
+
// The attachment binds each root's state before and after; the proof's wording is the engine's, not the migration.
|
|
108
|
+
const attachment = `${JSON.stringify({ name: input.name, roots: roots.map((r) => ({ root: r.root, location: r.location ?? null, before: { version_id: r.before.version_id ?? null, digest: r.before.digest }, after: r.after.digest })) }, null, 2)}\n`;
|
|
109
|
+
const result = await gatedOp({
|
|
110
|
+
op: input.words.op,
|
|
111
|
+
request: { kind: input.words.kind ?? "migrate", subject: input.name, by: input.by, fields: { ...(input.fields ?? {}), roots: roots.map((r) => r.root).join(",") } },
|
|
112
|
+
rules: input.rules,
|
|
113
|
+
description: input.description ?? `migration ${input.name}: ${roots.map((r) => r.root).join(", ")}`,
|
|
114
|
+
expiry: input.expiry ?? "48h",
|
|
115
|
+
attachment,
|
|
116
|
+
...(input.base ? { base: input.base } : {}),
|
|
117
|
+
...(input.cwd ? { cwd: input.cwd } : {}),
|
|
118
|
+
...(input.now ? { now: input.now } : {}),
|
|
119
|
+
...(input.runId ? { runId: input.runId } : {}),
|
|
120
|
+
...(input.commit ? { commit: input.commit } : {}),
|
|
121
|
+
...(input.ledger ? { ledger: input.ledger } : {}),
|
|
122
|
+
}, async ({ approvedBy }) => {
|
|
123
|
+
const written = await writeStateMigration(input.engine, roots);
|
|
124
|
+
return { output: written, detail: { by: input.by, approved_by: approvedBy, ...migrationFacts(written), ...(input.detail?.(written) ?? {}) }, failed: written.status !== "applied" };
|
|
125
|
+
});
|
|
126
|
+
const command = (fallback) => (input.words.approveCommand ? input.words.approveCommand(input.name, result.digest) : fallback);
|
|
127
|
+
switch (result.status) {
|
|
128
|
+
case "waiting":
|
|
129
|
+
return { status: "waiting", exit: CHANT_EXIT.waiting, digest: result.digest, command: command(result.command) };
|
|
130
|
+
case "refused":
|
|
131
|
+
return { status: "refused", exit: CHANT_EXIT.waiting, digest: result.digest, command: command(result.command), by: result.by, reason: result.reason };
|
|
132
|
+
case "spent":
|
|
133
|
+
return { status: "spent", exit: CHANT_EXIT.done, digest: result.digest };
|
|
134
|
+
case "held":
|
|
135
|
+
return { status: "failed", exit: CHANT_EXIT.failed, digest: result.digest, error: result.reason, recorded: false };
|
|
136
|
+
case "failed":
|
|
137
|
+
return { status: "failed", exit: CHANT_EXIT.failed, digest: result.digest, error: result.error.message, recorded: result.recorded };
|
|
138
|
+
case "done": {
|
|
139
|
+
const r = result.output;
|
|
140
|
+
if (r.status === "applied")
|
|
141
|
+
return { status: "applied", exit: CHANT_EXIT.done, digest: result.digest, approvedBy: result.approvedBy, result: r, recorded: result.recorded };
|
|
142
|
+
if (r.status === "moved")
|
|
143
|
+
return { status: "moved", exit: CHANT_EXIT.moved, digest: result.digest, approvedBy: result.approvedBy, result: r, recorded: result.recorded };
|
|
144
|
+
return { status: "failed", exit: CHANT_EXIT.failed, digest: result.digest, error: r.error ?? "the migration failed", result: r, recorded: result.recorded };
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
}
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
import { type GatedRequestLedger } from "./lifecycle/gated-op.js";
|
|
2
|
+
import type { GatedRequestRules } from "./lifecycle/gated-request.js";
|
|
3
|
+
import type { ForgeFetch, ForgeKind } from "./pr-forge.js";
|
|
4
|
+
/** The first chant with the engine-neutral lock release and {@link forgeLiveRuns} (#4762). */
|
|
5
|
+
export declare const STATE_UNLOCK_FLOOR = "0.124.77";
|
|
6
|
+
/** A run of the repository that has not finished, as {@link forgeLiveRuns} reads it. */
|
|
7
|
+
export interface LiveRun {
|
|
8
|
+
id: string;
|
|
9
|
+
status: string;
|
|
10
|
+
/** When it began, or was created when the forge gives no start. ISO 8601. */
|
|
11
|
+
started?: string;
|
|
12
|
+
url?: string;
|
|
13
|
+
}
|
|
14
|
+
/** Where {@link forgeLiveRuns} reads a repository's runs. */
|
|
15
|
+
export interface LiveRunsTarget {
|
|
16
|
+
kind: ForgeKind;
|
|
17
|
+
/** The forge's API base: `https://api.github.com`, `https://<host>/api/v1`, `https://<host>/api/v4`. */
|
|
18
|
+
apiBase: string;
|
|
19
|
+
/** `owner/repo` on GitHub and Forgejo; the project's id or path on GitLab. */
|
|
20
|
+
repo: string;
|
|
21
|
+
token?: string;
|
|
22
|
+
/** GitLab: the header the token goes in. Default `PRIVATE-TOKEN`. */
|
|
23
|
+
tokenHeader?: "PRIVATE-TOKEN" | "JOB-TOKEN";
|
|
24
|
+
fetch?: ForgeFetch;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* The repository's runs that have not finished: GitHub's and Forgejo's
|
|
28
|
+
* Actions runs queued, waiting or in progress, GitLab's pipelines running,
|
|
29
|
+
* pending, preparing or waiting for a resource. Kept here rather than on the
|
|
30
|
+
* forge clients, so the bundles that carry those clients do not grow with
|
|
31
|
+
* a read only a lock release makes. Throws on a forge that answers an error.
|
|
32
|
+
*/
|
|
33
|
+
export declare function forgeLiveRuns(t: LiveRunsTarget): Promise<LiveRun[]>;
|
|
34
|
+
/** How far a run's start may be after the lock's and still count as a run that could hold it: the clocks of the job and the forge differ. */
|
|
35
|
+
export declare const CLOCK_SKEW_MS: number;
|
|
36
|
+
/** A lock's info, as Terraform's binary writes it and other engines can name it. */
|
|
37
|
+
export interface LockInfo {
|
|
38
|
+
ID: string;
|
|
39
|
+
Operation?: string;
|
|
40
|
+
Info?: string;
|
|
41
|
+
Who?: string;
|
|
42
|
+
Version?: string;
|
|
43
|
+
Created?: string;
|
|
44
|
+
Path?: string;
|
|
45
|
+
}
|
|
46
|
+
/** A lock info's JSON, or undefined when it holds no lock ID. */
|
|
47
|
+
export declare function parseLockInfo(text: string): LockInfo | undefined;
|
|
48
|
+
/** An engine's state lock: the adapter a product's engine supplies. */
|
|
49
|
+
export interface StateLockSource {
|
|
50
|
+
/** Where the lock is, as messages and the record name it. Never a credential. */
|
|
51
|
+
readonly location: string;
|
|
52
|
+
/** The lock held now, or undefined when none is. */
|
|
53
|
+
read(): Promise<LockInfo | undefined>;
|
|
54
|
+
/** Release the lock with this ID, and no other. */
|
|
55
|
+
release(id: string): Promise<void>;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* The live runs that may hold a lock taken at `created`: those that began
|
|
59
|
+
* before it, give or take the clocks' skew. A lock with no time it was taken,
|
|
60
|
+
* or a run with no start, keeps every run in.
|
|
61
|
+
*/
|
|
62
|
+
export declare function possibleHolders(runs: readonly LiveRun[], created: string | undefined, skewMs?: number): LiveRun[];
|
|
63
|
+
/** A lock as one line: its ID, operation, holder and time. */
|
|
64
|
+
export declare const describeLock: (l: LockInfo) => string;
|
|
65
|
+
/** A run as one line. */
|
|
66
|
+
export declare const describeRun: (r: LiveRun) => string;
|
|
67
|
+
/** The product's words for a release. */
|
|
68
|
+
export interface StateUnlockWords {
|
|
69
|
+
/** The op the requests wait at, such as `tf-unlock`. */
|
|
70
|
+
op: string;
|
|
71
|
+
/** The request's kind. Default `unlock`. */
|
|
72
|
+
kind?: string;
|
|
73
|
+
/** The command that approves a request, as the product prints it. Default chant's. */
|
|
74
|
+
approveCommand?: (subject: string, digest: string) => string;
|
|
75
|
+
}
|
|
76
|
+
export interface StateUnlockInput {
|
|
77
|
+
/** Whose lock: a root, a stack. The gate the request waits at. */
|
|
78
|
+
subject: string;
|
|
79
|
+
/** The requester. Their own approval never counts. */
|
|
80
|
+
by: string;
|
|
81
|
+
lock: StateLockSource;
|
|
82
|
+
/**
|
|
83
|
+
* The repository's runs that have not finished, such as
|
|
84
|
+
* {@link forgeLiveRuns}. Read before the request and again just before
|
|
85
|
+
* the spend. A throw refuses the release.
|
|
86
|
+
*/
|
|
87
|
+
liveRuns: () => Promise<LiveRun[]>;
|
|
88
|
+
words: StateUnlockWords;
|
|
89
|
+
rules: GatedRequestRules;
|
|
90
|
+
cwd?: string;
|
|
91
|
+
base?: string;
|
|
92
|
+
/** How long a request waits for its approval. Default 48h. */
|
|
93
|
+
expiry?: string;
|
|
94
|
+
now?: string;
|
|
95
|
+
commit?: string;
|
|
96
|
+
skewMs?: number;
|
|
97
|
+
ledger?: GatedRequestLedger;
|
|
98
|
+
}
|
|
99
|
+
/** How a release ended. `exit` is the code its command exits with. */
|
|
100
|
+
export type StateUnlockOutcome = {
|
|
101
|
+
status: "free";
|
|
102
|
+
exit: 0;
|
|
103
|
+
location: string;
|
|
104
|
+
} | {
|
|
105
|
+
status: "released";
|
|
106
|
+
exit: 0;
|
|
107
|
+
location: string;
|
|
108
|
+
lock: LockInfo;
|
|
109
|
+
digest: string;
|
|
110
|
+
approvedBy: string;
|
|
111
|
+
liveRuns: number;
|
|
112
|
+
recorded: boolean;
|
|
113
|
+
}
|
|
114
|
+
/** A run that may hold the lock is alive: nothing was asked or released. */
|
|
115
|
+
| {
|
|
116
|
+
status: "alive";
|
|
117
|
+
exit: 5;
|
|
118
|
+
location: string;
|
|
119
|
+
lock: LockInfo;
|
|
120
|
+
alive: LiveRun[];
|
|
121
|
+
} | {
|
|
122
|
+
status: "waiting";
|
|
123
|
+
exit: 3;
|
|
124
|
+
location: string;
|
|
125
|
+
lock: LockInfo;
|
|
126
|
+
digest: string;
|
|
127
|
+
command: string;
|
|
128
|
+
} | {
|
|
129
|
+
status: "refused";
|
|
130
|
+
exit: 3;
|
|
131
|
+
location: string;
|
|
132
|
+
lock: LockInfo;
|
|
133
|
+
digest: string;
|
|
134
|
+
command: string;
|
|
135
|
+
by: string;
|
|
136
|
+
reason: string;
|
|
137
|
+
}
|
|
138
|
+
/** Approved, and a run that may hold the lock came back before the spend: the approval stands unspent. */
|
|
139
|
+
| {
|
|
140
|
+
status: "held";
|
|
141
|
+
exit: 5;
|
|
142
|
+
location: string;
|
|
143
|
+
lock: LockInfo;
|
|
144
|
+
digest: string;
|
|
145
|
+
reason: string;
|
|
146
|
+
} | {
|
|
147
|
+
status: "spent";
|
|
148
|
+
exit: 1;
|
|
149
|
+
location: string;
|
|
150
|
+
lock: LockInfo;
|
|
151
|
+
digest: string;
|
|
152
|
+
} | {
|
|
153
|
+
status: "failed";
|
|
154
|
+
exit: 1;
|
|
155
|
+
location: string;
|
|
156
|
+
lock: LockInfo;
|
|
157
|
+
digest: string;
|
|
158
|
+
error: Error;
|
|
159
|
+
recorded: boolean;
|
|
160
|
+
};
|
|
161
|
+
/** A refusal before anything is asked: the runs could not be read. */
|
|
162
|
+
export declare class StateUnlockError extends Error {
|
|
163
|
+
constructor(message: string);
|
|
164
|
+
}
|
|
165
|
+
/** Release a state's lock that no live run can hold, once an approval of that lock stands. */
|
|
166
|
+
export declare function releaseStateLock(input: StateUnlockInput): Promise<StateUnlockOutcome>;
|
|
167
|
+
//# sourceMappingURL=state-unlock.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"state-unlock.d.ts","sourceRoot":"","sources":["../src/state-unlock.ts"],"names":[],"mappings":"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"}
|