@intentius/chant-lexicon-terraform 0.124.86 → 0.124.88

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/dist/action-ops.d.ts.map +1 -1
  2. package/dist/action-ops.js +3 -1
  3. package/dist/chant-floors.d.ts +30 -0
  4. package/dist/chant-floors.d.ts.map +1 -0
  5. package/dist/chant-floors.js +29 -0
  6. package/dist/components/capability-plugin.d.ts +15 -1
  7. package/dist/components/capability-plugin.d.ts.map +1 -1
  8. package/dist/components/capability-plugin.js +13 -5
  9. package/dist/components/compose-group.d.ts +5 -1
  10. package/dist/components/compose-group.d.ts.map +1 -1
  11. package/dist/components/compose-group.js +7 -4
  12. package/dist/engine-timings.d.ts +249 -0
  13. package/dist/engine-timings.d.ts.map +1 -0
  14. package/dist/engine-timings.js +569 -0
  15. package/dist/integrity.json +2 -2
  16. package/dist/live-roots.d.ts +93 -0
  17. package/dist/live-roots.d.ts.map +1 -0
  18. package/dist/live-roots.js +206 -0
  19. package/dist/manifest.json +1 -1
  20. package/dist/migration-history.d.ts +105 -0
  21. package/dist/migration-history.d.ts.map +1 -0
  22. package/dist/migration-history.js +159 -0
  23. package/dist/module-catalog/index.d.ts +1 -0
  24. package/dist/module-catalog/index.d.ts.map +1 -1
  25. package/dist/module-catalog/index.js +3 -1
  26. package/dist/op/activities/live-detect.d.ts +15 -0
  27. package/dist/op/activities/live-detect.d.ts.map +1 -1
  28. package/dist/op/activities/live-detect.js +94 -0
  29. package/dist/op/activities/terraform.d.ts +1 -65
  30. package/dist/op/activities/terraform.d.ts.map +1 -1
  31. package/dist/op/activities/terraform.js +4 -54
  32. package/dist/op/command-hook.d.ts +88 -0
  33. package/dist/op/command-hook.d.ts.map +1 -0
  34. package/dist/op/command-hook.js +115 -0
  35. package/dist/registry/index.d.ts +1 -0
  36. package/dist/registry/index.d.ts.map +1 -1
  37. package/dist/registry/index.js +1 -0
  38. package/dist/state/exec.d.ts +23 -0
  39. package/dist/state/exec.d.ts.map +1 -1
  40. package/dist/state/exec.js +38 -0
  41. package/dist/state-ops.d.ts.map +1 -1
  42. package/dist/state-ops.js +3 -1
  43. package/dist/terragrunt/index.d.ts +3 -1
  44. package/dist/terragrunt/index.d.ts.map +1 -1
  45. package/dist/terragrunt/index.js +3 -1
  46. package/dist/terragrunt/place.d.ts +27 -0
  47. package/dist/terragrunt/place.d.ts.map +1 -0
  48. package/dist/terragrunt/place.js +52 -0
  49. package/package.json +2 -2
  50. package/src/action-ops.ts +3 -1
  51. package/src/chant-floors.ts +32 -0
  52. package/src/components/capability-plugin.ts +27 -6
  53. package/src/components/compose-group.test.ts +29 -0
  54. package/src/components/compose-group.ts +12 -5
  55. package/src/components/terraform-apply-command-hook.test.ts +43 -0
  56. package/src/engine-timings.test.ts +203 -0
  57. package/src/engine-timings.ts +718 -0
  58. package/src/live-roots.test.ts +80 -0
  59. package/src/live-roots.ts +244 -0
  60. package/src/migration-history.test.ts +83 -0
  61. package/src/migration-history.ts +199 -0
  62. package/src/module-catalog/index.ts +4 -1
  63. package/src/op/activities/live-detect.ts +87 -0
  64. package/src/op/activities/terraform.ts +12 -111
  65. package/src/op/command-hook.ts +182 -0
  66. package/src/registry/index.ts +1 -0
  67. package/src/state/engine-env.test.ts +18 -0
  68. package/src/state/exec.ts +38 -0
  69. package/src/state-ops.ts +3 -1
  70. package/src/terragrunt/index.ts +3 -1
  71. package/src/terragrunt/place.test.ts +42 -0
  72. package/src/terragrunt/place.ts +75 -0
@@ -0,0 +1,569 @@
1
+ /**
2
+ * Per-root engine timings for `terraform-apply` (chant#4887): how long each
3
+ * root's init, plan and apply ran, and the engine's own spans, read into the
4
+ * slowest resources and provider calls, provider start-up and state lock
5
+ * waits, for a plain wave and a composed one.
6
+ *
7
+ * {@link engineTimings} gives a {@link TerraformCommandHook} to pass as
8
+ * `terraformApplyCapabilityWith({ onCommand })` (chant#4865). It listens on
9
+ * a loopback port for the run and points each command's OTLP trace exporter
10
+ * at it (`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`), with a header naming the
11
+ * root and the command the spans came from. OpenTofu and choudoufu export
12
+ * OTLP/HTTP protobuf, so the receiver decodes the few protobuf messages a
13
+ * trace export holds; OTLP/JSON is read too. A binary that sends no spans
14
+ * (Terraform) still gets each command timed. With `forward`, each batch also
15
+ * goes on unchanged to the product's own collector.
16
+ *
17
+ * A composed group's commands (`terraform.compose`) run once for all its
18
+ * members, so each member root gets the group's times and spans, and its
19
+ * timings name the members it ran with. The run's slowest resources count a
20
+ * group once.
21
+ *
22
+ * Lifted from terragucci's `report/spans.ts` (the decoder, `SpanReceiver`,
23
+ * `rootTimings`, `runTimings`, `duration`) and the timing half of
24
+ * `report/observe.ts` (`StageObserver.commandHook`, `addTimings`), so
25
+ * terragucci deletes its copy. No OpenTelemetry SDK and no protobuf library.
26
+ */
27
+ import { randomBytes } from "node:crypto";
28
+ import { createServer } from "node:http";
29
+ import { gunzipSync, inflateSync } from "node:zlib";
30
+ /** The fields of one protobuf message. Throws on a truncated or malformed one. */
31
+ function* fields(buf) {
32
+ let pos = 0;
33
+ const varint = () => {
34
+ let out = 0n;
35
+ for (let shift = 0n;; shift += 7n) {
36
+ if (pos >= buf.length)
37
+ throw new Error("truncated varint");
38
+ const b = buf[pos++];
39
+ out |= BigInt(b & 0x7f) << shift;
40
+ if (b < 0x80)
41
+ return out;
42
+ if (shift > 63n)
43
+ throw new Error("varint too long");
44
+ }
45
+ };
46
+ const take = (n) => {
47
+ if (pos + n > buf.length)
48
+ throw new Error("truncated field");
49
+ const b = buf.subarray(pos, pos + n);
50
+ pos += n;
51
+ return b;
52
+ };
53
+ while (pos < buf.length) {
54
+ const key = Number(varint());
55
+ const no = key >>> 3;
56
+ const wire = key & 7;
57
+ if (wire === 0)
58
+ yield { no, wire, int: varint() };
59
+ else if (wire === 1)
60
+ yield { no, wire, bytes: take(8) };
61
+ else if (wire === 2)
62
+ yield { no, wire, bytes: take(Number(varint())) };
63
+ else if (wire === 5)
64
+ yield { no, wire, bytes: take(4) };
65
+ else
66
+ throw new Error(`unsupported wire type ${wire}`);
67
+ }
68
+ }
69
+ /** opentelemetry.proto.common.v1.AnyValue, scalars only. */
70
+ function anyValue(buf) {
71
+ for (const f of fields(buf)) {
72
+ if (f.no === 1 && f.bytes)
73
+ return f.bytes.toString("utf-8");
74
+ if (f.no === 2 && f.int !== undefined)
75
+ return f.int !== 0n;
76
+ if (f.no === 3 && f.int !== undefined)
77
+ return Number(BigInt.asIntN(64, f.int));
78
+ if (f.no === 4 && f.bytes)
79
+ return f.bytes.readDoubleLE(0);
80
+ }
81
+ return undefined;
82
+ }
83
+ function keyValue(buf, into) {
84
+ let key;
85
+ let value;
86
+ for (const f of fields(buf)) {
87
+ if (f.no === 1 && f.bytes)
88
+ key = f.bytes.toString("utf-8");
89
+ else if (f.no === 2 && f.bytes)
90
+ value = anyValue(f.bytes);
91
+ }
92
+ if (key !== undefined && value !== undefined)
93
+ into[key] = value;
94
+ }
95
+ function protoSpan(buf) {
96
+ const s = { attributes: {} };
97
+ for (const f of fields(buf)) {
98
+ if (!f.bytes)
99
+ continue;
100
+ if (f.no === 2)
101
+ s.spanId = f.bytes.toString("hex");
102
+ else if (f.no === 4 && f.bytes.length > 0)
103
+ s.parentSpanId = f.bytes.toString("hex");
104
+ else if (f.no === 5)
105
+ s.name = f.bytes.toString("utf-8");
106
+ else if (f.no === 7)
107
+ s.start = f.bytes.readBigUInt64LE(0);
108
+ else if (f.no === 8)
109
+ s.end = f.bytes.readBigUInt64LE(0);
110
+ else if (f.no === 9)
111
+ keyValue(f.bytes, s.attributes);
112
+ else if (f.no === 15) {
113
+ for (const g of fields(f.bytes))
114
+ if (g.no === 3 && g.int === 2n)
115
+ s.error = true;
116
+ }
117
+ }
118
+ if (!s.spanId || s.name === undefined || s.start === undefined || s.end === undefined)
119
+ return undefined;
120
+ return s;
121
+ }
122
+ /** The spans of an `ExportTraceServiceRequest` in protobuf. */
123
+ export function decodeTracesProto(buf) {
124
+ const out = [];
125
+ for (const rs of fields(buf)) {
126
+ if (rs.no !== 1 || !rs.bytes)
127
+ continue;
128
+ for (const ss of fields(rs.bytes)) {
129
+ if (ss.no !== 2 || !ss.bytes)
130
+ continue;
131
+ for (const sp of fields(ss.bytes)) {
132
+ if (sp.no !== 2 || !sp.bytes)
133
+ continue;
134
+ const span = protoSpan(sp.bytes);
135
+ if (span)
136
+ out.push(span);
137
+ }
138
+ }
139
+ }
140
+ return out;
141
+ }
142
+ const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
143
+ const list = (v) => (Array.isArray(v) ? v : []);
144
+ function jsonValue(v) {
145
+ if (!isObj(v))
146
+ return undefined;
147
+ if (typeof v.stringValue === "string")
148
+ return v.stringValue;
149
+ if (typeof v.boolValue === "boolean")
150
+ return v.boolValue;
151
+ if (typeof v.intValue === "string" || typeof v.intValue === "number")
152
+ return Number(v.intValue);
153
+ if (typeof v.doubleValue === "number")
154
+ return v.doubleValue;
155
+ return undefined;
156
+ }
157
+ const nanos = (v) => {
158
+ try {
159
+ return typeof v === "string" || typeof v === "number" ? BigInt(v) : undefined;
160
+ }
161
+ catch {
162
+ return undefined;
163
+ }
164
+ };
165
+ /** The spans of an `ExportTraceServiceRequest` in OTLP/JSON. */
166
+ export function decodeTracesJson(body) {
167
+ const out = [];
168
+ for (const rs of list(isObj(body) ? body.resourceSpans : undefined)) {
169
+ if (!isObj(rs))
170
+ continue;
171
+ for (const ss of list(rs.scopeSpans)) {
172
+ if (!isObj(ss))
173
+ continue;
174
+ for (const s of list(ss.spans)) {
175
+ if (!isObj(s) || typeof s.spanId !== "string" || typeof s.name !== "string")
176
+ continue;
177
+ const start = nanos(s.startTimeUnixNano);
178
+ const end = nanos(s.endTimeUnixNano);
179
+ if (start === undefined || end === undefined)
180
+ continue;
181
+ const attributes = {};
182
+ for (const kv of list(s.attributes)) {
183
+ if (!isObj(kv) || typeof kv.key !== "string")
184
+ continue;
185
+ const v = jsonValue(kv.value);
186
+ if (v !== undefined)
187
+ attributes[kv.key] = v;
188
+ }
189
+ out.push({
190
+ spanId: s.spanId,
191
+ ...(typeof s.parentSpanId === "string" && s.parentSpanId ? { parentSpanId: s.parentSpanId } : {}),
192
+ name: s.name,
193
+ start,
194
+ end,
195
+ attributes,
196
+ ...(isObj(s.status) && (s.status.code === 2 || s.status.code === "STATUS_CODE_ERROR") ? { error: true } : {}),
197
+ });
198
+ }
199
+ }
200
+ }
201
+ return out;
202
+ }
203
+ // The receiver
204
+ /** The header whose token says which run of the binary a batch of spans came from. */
205
+ export const ENGINE_RUN_HEADER = "x-chant-run";
206
+ /**
207
+ * A loopback OTLP/HTTP trace endpoint for one run. It never holds the
208
+ * process open, and a request it cannot read is answered and dropped. Spans
209
+ * are kept by the key {@link SpanReceiver.exporter} was given.
210
+ */
211
+ export class SpanReceiver {
212
+ /** `forward`: a collector that also gets every batch the binary sends, unchanged. */
213
+ constructor(forward, fetchFn = fetch) {
214
+ this.forward = forward;
215
+ this.fetchFn = fetchFn;
216
+ this.url = "";
217
+ this.runs = new Map();
218
+ this.spans = new Map();
219
+ this.forwards = [];
220
+ /** Batches that could not be read, with why. */
221
+ this.unreadable = [];
222
+ }
223
+ /** Start listening. Undefined when it is up; the problem when it could not start. */
224
+ async listen() {
225
+ const server = createServer((req, res) => this.handle(req, res));
226
+ try {
227
+ await new Promise((resolve, reject) => {
228
+ server.once("error", reject);
229
+ server.listen(0, "127.0.0.1", () => resolve());
230
+ });
231
+ }
232
+ catch (e) {
233
+ return e.message;
234
+ }
235
+ server.unref();
236
+ const addr = server.address();
237
+ if (!addr || typeof addr === "string")
238
+ return "no port";
239
+ this.server = server;
240
+ this.url = `http://127.0.0.1:${addr.port}/v1/traces`;
241
+ return undefined;
242
+ }
243
+ get listening() {
244
+ return this.server !== undefined;
245
+ }
246
+ /** The variables one run of the binary gets so its spans come here, kept under `key`; none when the receiver is not listening. */
247
+ exporter(key) {
248
+ if (!this.server)
249
+ return {};
250
+ const token = randomBytes(12).toString("hex");
251
+ this.runs.set(token, key);
252
+ return {
253
+ OTEL_TRACES_EXPORTER: "otlp",
254
+ OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: this.url,
255
+ OTEL_EXPORTER_OTLP_TRACES_PROTOCOL: "http/protobuf",
256
+ OTEL_EXPORTER_OTLP_TRACES_HEADERS: `${ENGINE_RUN_HEADER}=${token}`,
257
+ };
258
+ }
259
+ /** The spans the runs exported under `key` sent. */
260
+ spansOf(key) {
261
+ return this.spans.get(key) ?? [];
262
+ }
263
+ handle(req, res) {
264
+ const chunks = [];
265
+ req.on("data", (c) => chunks.push(c));
266
+ req.on("end", () => {
267
+ const type = String(req.headers["content-type"] ?? "");
268
+ const proto = !type.includes("json");
269
+ const reply = (status) => {
270
+ res.writeHead(status, { "content-type": proto ? "application/x-protobuf" : "application/json" });
271
+ res.end(proto ? "" : "{}");
272
+ };
273
+ const key = this.runs.get(String(req.headers[ENGINE_RUN_HEADER] ?? ""));
274
+ if (req.method !== "POST" || key === undefined)
275
+ return reply(req.method === "POST" ? 401 : 405);
276
+ const raw = Buffer.concat(chunks);
277
+ try {
278
+ const encoding = String(req.headers["content-encoding"] ?? "").toLowerCase();
279
+ const body = encoding === "gzip" ? gunzipSync(raw) : encoding === "deflate" ? inflateSync(raw) : raw;
280
+ const got = proto ? decodeTracesProto(body) : decodeTracesJson(JSON.parse(body.toString("utf-8")));
281
+ this.spans.set(key, [...(this.spans.get(key) ?? []), ...got]);
282
+ }
283
+ catch (e) {
284
+ this.unreadable.push(`${key.replace(/\u0000/g, " ")}: ${e.message}`);
285
+ }
286
+ reply(200);
287
+ if (this.forward)
288
+ this.forwards.push(this.relay(raw, req));
289
+ });
290
+ }
291
+ async relay(raw, req) {
292
+ const t = this.forward;
293
+ const headers = { ...t.headers, "content-type": String(req.headers["content-type"] ?? "application/x-protobuf") };
294
+ if (req.headers["content-encoding"])
295
+ headers["content-encoding"] = String(req.headers["content-encoding"]);
296
+ try {
297
+ const res = await this.fetchFn(t.url, { method: "POST", headers, body: new Uint8Array(raw), signal: AbortSignal.timeout(10000) });
298
+ return res.ok ? undefined : `${t.url} answered ${res.status}`;
299
+ }
300
+ catch (e) {
301
+ return `${t.url}: ${e.message}`;
302
+ }
303
+ }
304
+ /** Stop listening, once every forwarded batch is answered. Returns the forwards that failed. */
305
+ async close() {
306
+ const problems = (await Promise.all(this.forwards)).filter((p) => p !== undefined);
307
+ const server = this.server;
308
+ this.server = undefined;
309
+ if (server)
310
+ await new Promise((resolve) => server.close(() => resolve()));
311
+ return problems;
312
+ }
313
+ }
314
+ // Reading the spans
315
+ /** How many of each list a root's timings keep. */
316
+ export const TOP = 10;
317
+ const RESOURCE_SPANS = new Set(["Plan resource instance changes", "Apply resource instance changes"]);
318
+ const BUILTIN_PROVIDER = "terraform.io/builtin/terraform";
319
+ const PROVIDER_CALL = /^tfplugin[56]\.Provider\/(\w+)$/;
320
+ const ms = (s) => Math.round(Number(s.end - s.start) / 1e5) / 10;
321
+ const str = (v) => (v === undefined || v === "" ? undefined : String(v));
322
+ const num = (v) => (typeof v === "number" ? v : typeof v === "string" && v !== "" && !Number.isNaN(Number(v)) ? Number(v) : undefined);
323
+ const slowest = (xs, n = TOP) => [...xs].sort((a, b) => b.ms - a.ms).slice(0, n);
324
+ const defined = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
325
+ /** A root's timings from the spans its plan sent. */
326
+ export function rootTimings(spans, facts) {
327
+ const byId = new Map(spans.map((s) => [s.spanId, s]));
328
+ const refresh = new Map();
329
+ for (const s of spans)
330
+ if (s.name === "Refresh resource instance" && s.parentSpanId)
331
+ refresh.set(s.parentSpanId, (refresh.get(s.parentSpanId) ?? 0) + ms(s));
332
+ const resources = spans.filter((s) => RESOURCE_SPANS.has(s.name)).map((s) => defined({
333
+ address: str(s.attributes["opentofu.resource_instance.address"]) ?? "(no address)",
334
+ type: str(s.attributes["opentofu.resource.type"]),
335
+ action: str(s.attributes["opentofu.resource_instance.action"]),
336
+ provider: str(s.attributes["opentofu.provider_instance.address"]),
337
+ ms: ms(s),
338
+ refresh_ms: refresh.get(s.spanId),
339
+ }));
340
+ const calls = [];
341
+ for (const s of spans) {
342
+ const m = PROVIDER_CALL.exec(s.name);
343
+ if (!m)
344
+ continue;
345
+ const parent = s.parentSpanId ? byId.get(s.parentSpanId) : undefined;
346
+ calls.push(defined({
347
+ method: str(s.attributes["rpc.method"]) ?? m[1],
348
+ provider: str(s.attributes["opentofu.provider.address"]),
349
+ type: str(s.attributes["opentofu.resource.type"]),
350
+ address: parent && RESOURCE_SPANS.has(parent.name) ? str(parent.attributes["opentofu.resource_instance.address"]) : undefined,
351
+ ms: ms(s),
352
+ }));
353
+ }
354
+ // choudoufu starts each provider process inside a "Start provider" span.
355
+ // OpenTofu has none: the nearest it sends is "Configure provider", which
356
+ // names the provider in opentofu.provider.source. The builtin provider runs
357
+ // in-process and is left out. A root with Start spans is read from those
358
+ // alone, so choudoufu's Configure spans are not counted a second time.
359
+ const startSpans = spans.filter((s) => s.name === "Start provider");
360
+ const initSpans = startSpans.length > 0 ? startSpans : spans.filter((s) => s.name === "Configure provider" && str(s.attributes["opentofu.provider.source"]) !== BUILTIN_PROVIDER);
361
+ const starts = new Map();
362
+ for (const s of initSpans) {
363
+ const provider = str(s.attributes["opentofu.provider.address"]) ?? str(s.attributes["opentofu.provider.source"]) ?? "(unnamed)";
364
+ const e = starts.get(provider) ?? { provider, count: 0, ms: 0, max_ms: 0 };
365
+ e.count++;
366
+ e.ms = Math.round((e.ms + ms(s)) * 10) / 10;
367
+ e.max_ms = Math.max(e.max_ms, ms(s));
368
+ starts.set(provider, e);
369
+ }
370
+ const lockWaits = spans.filter((s) => s.name === "State lock wait").map((s) => defined({
371
+ backend: str(s.attributes["opentofu.state.backend"]),
372
+ operation: str(s.attributes["opentofu.state.lock.operation"]),
373
+ attempts: num(s.attributes["opentofu.state.lock.attempts"]),
374
+ ms: ms(s),
375
+ }));
376
+ const aggregates = spans.filter((s) => s.name.startsWith("Aggregate: ")).map((s) => {
377
+ const a = s.attributes;
378
+ return defined({
379
+ of: s.name.slice("Aggregate: ".length),
380
+ kind: str(a["choudoufu.aggregate.kind"]),
381
+ type: str(a["opentofu.resource.type"]),
382
+ provider: str(a["opentofu.provider.address"]),
383
+ method: str(a["rpc.method"]),
384
+ count: num(a["choudoufu.aggregate.count"]) ?? 0,
385
+ detailed: num(a["choudoufu.aggregate.detailed_count"]) ?? 0,
386
+ ms: num(a["choudoufu.aggregate.duration_total_ms"]) ?? 0,
387
+ max_ms: num(a["choudoufu.aggregate.duration_max_ms"]) ?? 0,
388
+ slowest: str(a["choudoufu.aggregate.slowest"]),
389
+ groups: num(a["choudoufu.aggregate.groups"]),
390
+ });
391
+ });
392
+ const summed = aggregates.filter((a) => a.kind !== "provider_call").reduce((n, a) => n + Math.max(0, a.count - a.detailed), 0);
393
+ const detail = resources.length > 0 ? "resources" : aggregates.length > 0 ? "aggregate" : "none";
394
+ const what = facts.applySeconds !== undefined ? "plan and apply" : "plan";
395
+ let note;
396
+ if (facts.source === "terragrunt" && spans.length === 0)
397
+ note = `Terragrunt ran the binary for this unit, so its time is from Terragrunt's run report, and ${facts.binary} sent no spans for its plan, so it has no per-resource timings`;
398
+ else if (facts.source === "terragrunt" && detail === "none")
399
+ note = `Terragrunt ran the binary for this unit, so its time is from Terragrunt's run report; ${facts.binary} sent ${spans.length} span${spans.length === 1 ? "" : "s"} for its plan, none of them per resource`;
400
+ else if (facts.planSeconds === undefined)
401
+ note = "the root did not reach a plan, so no spans were read";
402
+ else if (spans.length === 0)
403
+ note = `${facts.binary} sent no spans for the ${what}, so this root has no per-resource timings. A binary that exports per-resource OpenTelemetry spans, such as choudoufu, gives them`;
404
+ else if (detail === "none")
405
+ note = `${facts.binary} sent ${spans.length} span${spans.length === 1 ? "" : "s"} for the ${what}, none of them per resource, so this root has no per-resource timings`;
406
+ else if (detail === "aggregate")
407
+ note = `${facts.binary} summed its resources by type instead of a span each, so the slowest are listed by type`;
408
+ else if (summed > 0)
409
+ note = `past the span budget, ${summed} resource instance${summed === 1 ? " is" : "s are"} summed by type instead of listed`;
410
+ return {
411
+ seconds: Math.round(facts.seconds * 100) / 100,
412
+ ...(facts.planSeconds !== undefined ? { plan_seconds: Math.round(facts.planSeconds * 100) / 100 } : {}),
413
+ ...(facts.applySeconds !== undefined ? { apply_seconds: Math.round(facts.applySeconds * 100) / 100 } : {}),
414
+ ...(facts.source === "terragrunt" ? { source: "terragrunt" } : {}),
415
+ spans: spans.length,
416
+ detail,
417
+ ...(note ? { note } : {}),
418
+ resources: slowest(resources),
419
+ provider_calls: slowest(calls),
420
+ provider_init: slowest([...starts.values()]),
421
+ lock_waits: slowest(lockWaits),
422
+ aggregates: slowest(aggregates, 2 * TOP),
423
+ };
424
+ }
425
+ /** The run's slowest roots and resources, from each root's timings. */
426
+ export function runTimings(roots, note) {
427
+ const timed = roots.filter((r) => r.timings !== undefined);
428
+ return {
429
+ roots: [...timed]
430
+ .sort((a, b) => b.timings.seconds - a.timings.seconds)
431
+ .map((r) => ({
432
+ root: r.path,
433
+ seconds: r.timings.seconds,
434
+ ...(r.timings.plan_seconds !== undefined ? { plan_seconds: r.timings.plan_seconds } : {}),
435
+ ...(r.timings.apply_seconds !== undefined ? { apply_seconds: r.timings.apply_seconds } : {}),
436
+ ...(r.timings.source ? { source: r.timings.source } : {}),
437
+ detail: r.timings.detail,
438
+ })),
439
+ resources: slowest(timed.flatMap((r) => r.timings.resources.map((x) => ({ root: r.path, address: x.address, ...(x.type ? { type: x.type } : {}), ms: x.ms })))),
440
+ ...(note ? { note } : {}),
441
+ };
442
+ }
443
+ /** `850ms`, `3.2s`, `2m05s`. */
444
+ export function duration(msValue) {
445
+ if (msValue < 1000)
446
+ return `${Math.round(msValue)}ms`;
447
+ const s = msValue / 1000;
448
+ if (s < 59.95)
449
+ return `${s.toFixed(1)}s`;
450
+ const total = Math.round(s);
451
+ return `${Math.floor(total / 60)}m${String(total % 60).padStart(2, "0")}s`;
452
+ }
453
+ /** The key spans are kept by: a root's, or a composed group's, and the command. */
454
+ const keyOf = (roots, command) => `${roots.join("\u0001")}\u0000${command}`;
455
+ /**
456
+ * The engine timings of one run (chant#4887): {@link EngineTimings.onCommand}
457
+ * goes in `terraformApplyCapabilityWith({ onCommand })`, and once the wave
458
+ * ran, {@link EngineTimings.roots} gives each root's timings and
459
+ * {@link EngineTimings.run} the run's slowest roots and resources. Call
460
+ * {@link EngineTimings.close} once, after the last command.
461
+ */
462
+ export class EngineTimings {
463
+ constructor(options, receiver, problem) {
464
+ this.options = options;
465
+ this.receiver = receiver;
466
+ this.commands = new Map();
467
+ this.groups = new Map();
468
+ this.binaries = new Map();
469
+ /** The hook to pass as `onCommand`. */
470
+ this.onCommand = async (c) => {
471
+ const inner = (await this.options.inner?.(c)) ?? {};
472
+ // An upstream's reads for a root are the upstream's, not the root's: only the product's own hook sees them.
473
+ if (c.upstream !== undefined)
474
+ return inner;
475
+ const roots = c.members && c.members.length > 0 ? [...c.members] : [c.root];
476
+ if (roots.length > 1)
477
+ for (const r of roots)
478
+ this.groups.set(r, roots);
479
+ for (const r of roots)
480
+ this.binaries.set(r, (c.binary.split("/").pop() || c.binary));
481
+ const exporter = this.receiver && this.spanCommands.includes(c.name) ? this.receiver.exporter(keyOf(roots, c.name)) : {};
482
+ return {
483
+ env: { ...(inner.env ?? {}), ...exporter },
484
+ after: async (r) => {
485
+ try {
486
+ await inner.after?.(r);
487
+ }
488
+ finally {
489
+ for (const root of roots) {
490
+ const list = this.commands.get(root) ?? [];
491
+ list.push({ command: c.name, method: c.method, seconds: r.seconds, code: r.code });
492
+ this.commands.set(root, list);
493
+ }
494
+ }
495
+ },
496
+ };
497
+ };
498
+ this.spanCommands = options.spanCommands ?? ["plan", "apply"];
499
+ if (problem)
500
+ this.problem = problem;
501
+ }
502
+ /** Start the receiver (unless `noSpans`) and answer the timings. Never throws: a receiver that cannot listen leaves `problem` set. */
503
+ static async start(options = {}) {
504
+ if (options.noSpans)
505
+ return new EngineTimings(options, undefined);
506
+ const receiver = new SpanReceiver(options.forward, options.fetch);
507
+ const problem = await receiver.listen();
508
+ return problem ? new EngineTimings(options, undefined, problem) : new EngineTimings(options, receiver);
509
+ }
510
+ /** Batches of spans that could not be read, with why. */
511
+ get unreadable() {
512
+ return this.receiver?.unreadable ?? [];
513
+ }
514
+ /** One root's timings, or undefined when it ran no command. */
515
+ root(root) {
516
+ const commands = this.commands.get(root);
517
+ if (!commands)
518
+ return undefined;
519
+ const group = this.groups.get(root) ?? [root];
520
+ const sum = (name) => commands.filter((x) => x.command === name).reduce((n, x) => (n ?? 0) + x.seconds, undefined);
521
+ const plan = sum("plan") ?? sum("live-plan-set");
522
+ const apply = sum("apply") ?? sum("live-wave-apply");
523
+ const init = sum("init");
524
+ const spans = this.spanCommands.flatMap((name) => this.receiver?.spansOf(keyOf(group, name)) ?? []);
525
+ const timings = rootTimings(spans, {
526
+ binary: this.options.binary ?? this.binaries.get(root) ?? "the binary",
527
+ seconds: commands.reduce((n, x) => n + x.seconds, 0),
528
+ ...(plan !== undefined ? { planSeconds: plan } : {}),
529
+ ...(apply !== undefined ? { applySeconds: apply } : {}),
530
+ });
531
+ return {
532
+ root,
533
+ ...timings,
534
+ commands: commands.map((x) => ({ ...x })),
535
+ ...(init !== undefined ? { init_seconds: Math.round(init * 100) / 100 } : {}),
536
+ ...(group.length > 1 ? { composed: [...group] } : {}),
537
+ };
538
+ }
539
+ /** Every root that ran a command, by root. */
540
+ roots() {
541
+ const out = {};
542
+ for (const root of [...this.commands.keys()].sort())
543
+ out[root] = this.root(root);
544
+ return out;
545
+ }
546
+ /** The run's slowest roots and resources; a composed group's resources count once. */
547
+ run(note) {
548
+ const roots = Object.values(this.roots());
549
+ const once = new Set();
550
+ const forResources = roots.filter((r) => {
551
+ const k = (r.composed ?? [r.root]).join("\u0001");
552
+ if (once.has(k))
553
+ return false;
554
+ once.add(k);
555
+ return true;
556
+ });
557
+ const all = runTimings(roots.map((r) => ({ path: r.root, timings: r })), note);
558
+ const resources = runTimings(forResources.map((r) => ({ path: r.composed ? r.composed.join(", ") : r.root, timings: r }))).resources;
559
+ return { ...all, resources };
560
+ }
561
+ /** Stop the receiver, once every forwarded batch is answered. Returns the forwards that failed. */
562
+ async close() {
563
+ return this.receiver ? this.receiver.close() : [];
564
+ }
565
+ }
566
+ /** {@link EngineTimings.start}: the engine timings of one run, whose `onCommand` goes in `terraformApplyCapabilityWith`. */
567
+ export function engineTimings(options = {}) {
568
+ return EngineTimings.start(options);
569
+ }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "algorithm": "sha256",
3
3
  "artifacts": {
4
- "manifest.json": "801af4fb22d31f0226ff35a30ca4bace4b9b772cc8b499d0ff1774839e3e5e97",
4
+ "manifest.json": "74df8d4dde6b23128cb0e27a730ddc02a9b6ac2b5da83f03dccc3965c5620520",
5
5
  "meta.json": "ca3d163bab055381827226140568f3bef7eaac187cebd76878e0b63e9e442356",
6
6
  "types/index.d.ts": "022927e6a7b351cc4cf52d5f973f60ccd140e5810e17b32fb8868965aa1db161",
7
7
  "rules/plan-before-apply.ts": "7c10245b2c3335253b48ee7d8b075d89f43116bde20313a5d1031b343fef1282",
@@ -59,5 +59,5 @@
59
59
  "rules/tf047.ts": "bfa86f85c4c5efff297280fc2f15104d6319fa96dfc444a31829fb7353224092",
60
60
  "skills/chant-terraform.md": "53dd11c7b289652f92fdaf2c03766abda46d8964e31fe709e8b142ced4f19c50"
61
61
  },
62
- "composite": "008d7285b2fb3b6bac48cd2b58eab4ef645e47cebdcbc2fedb8e25f31bfb2a7a"
62
+ "composite": "d6062b4171ec80f83b7ff48a66a868fd0192778d6cf185e0a68656fb8345ebe4"
63
63
  }
@@ -0,0 +1,93 @@
1
+ import { type BucketReport, type BucketTarget } from "@intentius/chant/bucket-check";
2
+ import { type BinaryExec } from "./state/exec.js";
3
+ export { declaresLive, detectLiveEstate, estateOutputReads } from "./op/activities/live-detect.js";
4
+ /** The roots of `roots` (paths under `repo`) that keep their resources under choudoufu's live markers, in the order given. */
5
+ export declare function liveRoots(repo: string, roots: readonly string[], binary?: string): string[];
6
+ /** A root's estate, as its sidecar or `live` block names it, and the estates whose recorded outputs it reads. */
7
+ export declare function estateOf(dir: string, binary?: string): {
8
+ estate?: string;
9
+ reads: string[];
10
+ };
11
+ /** Where choudoufu's estate name came from: the live block, the configuration's tags, the backend key, or the root's path. */
12
+ export type EstateSource = "explicit" | "tags" | "backend_key" | "root_path" | "none";
13
+ /** The record store choudoufu resolved, as `live-check -json` prints it. */
14
+ export interface LiveStore {
15
+ /** `local`, `s3`, `gcs`, `azurerm` or `kubernetes`. */
16
+ kind: string;
17
+ /** The s3 or gcs bucket, `<account>/<container>` for azurerm, the namespace for kubernetes, the directory for local. */
18
+ bucket: string;
19
+ /** Where this estate's records go, with one trailing slash. */
20
+ prefix: string;
21
+ /** `record_store` (written by the author), `backend` (derived from the backend block) or `implied` (the local store). */
22
+ source: string;
23
+ /** `file:line` of the block that decided it. */
24
+ declaredAt?: string;
25
+ /** Why a backend that was there was not used. */
26
+ note?: string;
27
+ }
28
+ /** What choudoufu resolves for one root. */
29
+ export interface LiveSetup {
30
+ estate?: string;
31
+ estateSource: string;
32
+ store?: LiveStore;
33
+ }
34
+ /** The setup in a `live-check -json` document, or undefined when the document is not JSON or comes from a choudoufu that does not print `estate_source`. */
35
+ export declare function parseLiveSetup(stdout: string): LiveSetup | undefined;
36
+ /** Keep what choudoufu resolved for a root's directory, for the readers below. */
37
+ export declare function rememberLiveSetup(dir: string, setup: LiveSetup): void;
38
+ /** What choudoufu resolved for a root's directory in this process, if it was read. */
39
+ export declare function knownLiveSetup(dir: string): LiveSetup | undefined;
40
+ /** For tests: forget every setup read so far. */
41
+ export declare function forgetLiveSetups(): void;
42
+ /**
43
+ * `choudoufu live-check -json <dir>` for one root, run in the directory, and
44
+ * the setup it prints, remembered for the process. Undefined when the binary
45
+ * prints none (an older release, a root it cannot read, or no binary at
46
+ * all); the caller then reads the files. A root that live-check blocks still
47
+ * prints its setup, so the exit code is not read.
48
+ */
49
+ export declare function readLiveSetup(dir: string, options?: {
50
+ binary?: string;
51
+ exec?: BinaryExec;
52
+ env?: NodeJS.ProcessEnv;
53
+ }): Promise<LiveSetup | undefined>;
54
+ /** A live root's estate: choudoufu's resolved name when it was read, else the name its files write. */
55
+ export declare function resolvedEstate(dir: string, binary?: string): string | undefined;
56
+ /** The store as one phrase: `s3 bucket "acme" under tofu-records/prod/`. */
57
+ export declare function storePhrase(s: LiveStore): string;
58
+ /** A root's setup on one line: where its records go, where that came from, and its estate. */
59
+ export declare function setupLine(root: string, setup: LiveSetup): string;
60
+ /** The setup's store is the local directory, which is empty on every CI run. */
61
+ export declare const onLocalStore: (setup: LiveSetup) => boolean;
62
+ /**
63
+ * The bucket core's check reads for a resolved store, or why there is none.
64
+ * `backend` is the root's backend block's string attributes, for the s3
65
+ * region and the azurerm subscription and resource group. s3 takes the
66
+ * region from there or the job, and an emulator's endpoint and keys from the
67
+ * job; gcs an emulator from `STORAGE_EMULATOR_HOST`; azurerm needs the
68
+ * subscription and resource group, from the backend block or
69
+ * `ARM_SUBSCRIPTION_ID`.
70
+ */
71
+ export declare function bucketTarget(s: LiveStore, backend?: Record<string, string>, env?: NodeJS.ProcessEnv): {
72
+ target: BucketTarget;
73
+ } | {
74
+ skip: string;
75
+ };
76
+ /** What the bucket check said about one root's store. */
77
+ export type BucketOutcome = {
78
+ checked: BucketReport;
79
+ } | {
80
+ skipped: string;
81
+ };
82
+ /**
83
+ * Core's bucket check on a root's resolved store: the settings choudoufu
84
+ * refuses to open the bucket without. It reads only. A store with no bucket,
85
+ * or a check that cannot run, is skipped with the reason; nothing here throws.
86
+ * `check` is injectable for tests.
87
+ */
88
+ export declare function checkStoreBucket(s: LiveStore, backend?: Record<string, string>, env?: NodeJS.ProcessEnv, check?: (target: BucketTarget, options: {
89
+ namespaces: string[];
90
+ }) => Promise<BucketReport>): Promise<BucketOutcome>;
91
+ /** The bucket check's outcome as lines: one for a correct bucket, else one per setting that did not pass, with its fix. */
92
+ export declare function bucketLines(root: string, outcome: BucketOutcome): string[];
93
+ //# sourceMappingURL=live-roots.d.ts.map