@intentius/chant-lexicon-aws 0.14.0 → 0.15.0

package/src/components/safety.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { createSnapshotBeforeCapability, createRollbackPreviousCapability } from "./safety";
+import { createMockCloudExecutor } from "./__tests__/mock-cloud-executor";
+
+const ctx = { env: "dev", component: "orders" };
+
+describe("snapshot-before (#557)", () => {
+  it("dispatches to the executor's snapshot.create with the resource + kind, returning the snapshotId", async () => {
+    const mock = createMockCloudExecutor();
+    const out = await createSnapshotBeforeCapability(mock.executor).run(ctx, {
+      resource: "orders-table",
+      resourceKind: "dynamodb-table",
+    });
+    expect(out.snapshotId).toBe("snap-mock-dynamodb-table-orders-table");
+    expect(mock.calls).toEqual([
+      { client: "snapshot", method: "create", args: { resource: "orders-table", resourceKind: "dynamodb-table" } },
+    ]);
+  });
+
+  it("passes the kind through for rds/ebs so the executor selects the right mechanism", async () => {
+    const mock = createMockCloudExecutor();
+    await createSnapshotBeforeCapability(mock.executor).run(ctx, { resource: "prod-db", resourceKind: "rds-instance" });
+    expect(mock.calls[0]!.args).toEqual({ resource: "prod-db", resourceKind: "rds-instance" });
+  });
+
+  it("declares no rollback — the snapshot it takes IS the rollback artifact", () => {
+    expect(createSnapshotBeforeCapability(createMockCloudExecutor().executor).rollback).toBeUndefined();
+  });
+});
+
+describe("rollback-previous (#557)", () => {
+  it("restores the resource from the given snapshot via the executor, returning restored: true", async () => {
+    const mock = createMockCloudExecutor();
+    const out = await createRollbackPreviousCapability(mock.executor).run(ctx, {
+      resource: "orders-table",
+      snapshotId: "arn:aws:dynamodb:us-east-2:1:table/orders-table/backup/abc",
+    });
+    expect(out).toEqual({ restored: true });
+    expect(mock.calls).toEqual([
+      { client: "snapshot", method: "restore", args: { resource: "orders-table", snapshotId: "arn:aws:dynamodb:us-east-2:1:table/orders-table/backup/abc" } },
+    ]);
+  });
+
+  it("declares no rollback — it is the rollback", () => {
+    expect(createRollbackPreviousCapability(createMockCloudExecutor().executor).rollback).toBeUndefined();
+  });
+});

package/src/components/safety.ts

@@ -0,0 +1,78 @@
+/**
+ * safety / rollback family — explicit snapshot-and-restore capabilities, used
+ * alongside the per-capability `rollback` compensation for cases that need an
+ * up-front capture (e.g. before a `cfn-deploy` with `onReplace: "snapshot-first"`).
+ *
+ * Both dispatch to the kind-appropriate AWS backup/restore mechanism through the
+ * injectable `CloudExecutor` (DynamoDB backup, RDS DB snapshot, EBS snapshot).
+ */
+
+import type { Capability } from "@intentius/chant/components/capability";
+import { defaultCloudExecutor, type CloudExecutor } from "./cloud-executor";
+
+// ── snapshot-before ──────────────────────────────────────────────────────────
+
+export interface SnapshotBeforeInput {
+  /** Resource identifier to snapshot (e.g. a DynamoDB table name, an RDS instance id). */
+  resource: string;
+  /** Resource kind, used to select the right snapshot mechanism. */
+  resourceKind: "dynamodb-table" | "rds-instance" | "opensearch-domain" | "ebs-volume";
+}
+
+export interface SnapshotBeforeOutput {
+  /** Snapshot identifier, for `rollback-previous` to restore from. */
+  snapshotId: string;
+}
+
+/**
+ * Capture a restorable snapshot before a risky/destructive apply step, via the
+ * kind-appropriate AWS backup mechanism through the injectable `CloudExecutor`
+ * (DynamoDB on-demand backup, RDS DB snapshot, or EBS volume snapshot). Returns
+ * the backup/snapshot id `rollback-previous` restores from.
+ */
+export function createSnapshotBeforeCapability(executor: CloudExecutor = defaultCloudExecutor()): Capability<SnapshotBeforeInput, SnapshotBeforeOutput> {
+  return {
+    kind: "snapshot-before",
+    async run(_ctx, input) {
+      return executor.snapshot.create({ resource: input.resource, resourceKind: input.resourceKind });
+    },
+  };
+}
+
+/** Default `snapshot-before` capability, backed by the real `CloudExecutor`. */
+export const snapshotBeforeCapability: Capability<SnapshotBeforeInput, SnapshotBeforeOutput> =
+  createSnapshotBeforeCapability();
+
+// ── rollback-previous ────────────────────────────────────────────────────────
+
+export interface RollbackPreviousInput {
+  /** Snapshot identifier to restore (typically `"@snapshot-before.snapshotId"`). */
+  snapshotId: string;
+  /** Resource identifier being restored. */
+  resource: string;
+}
+
+export interface RollbackPreviousOutput {
+  /** True once the restore completed. */
+  restored: boolean;
+}
+
+/**
+ * Restore a resource from a prior `snapshot-before` capture — an explicit,
+ * caller-composed rollback (not the auto-triggered per-capability compensation).
+ * Dispatches by the snapshot-id shape through the `CloudExecutor` and waits for
+ * the restore to become available.
+ */
+export function createRollbackPreviousCapability(executor: CloudExecutor = defaultCloudExecutor()): Capability<RollbackPreviousInput, RollbackPreviousOutput> {
+  return {
+    kind: "rollback-previous",
+    async run(_ctx, input) {
+      await executor.snapshot.restore({ resource: input.resource, snapshotId: input.snapshotId });
+      return { restored: true };
+    },
+  };
+}
+
+/** Default `rollback-previous` capability, backed by the real `CloudExecutor`. */
+export const rollbackPreviousCapability: Capability<RollbackPreviousInput, RollbackPreviousOutput> =
+  createRollbackPreviousCapability();

package/src/components/wait-aws.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import {
+  createWaitForStackCapability,
+  createWaitSteadyStateCapability,
+  createWaitJobCapability,
+} from "./wait-aws";
+import { createMockCloudExecutor } from "./__tests__/mock-cloud-executor";
+
+describe("wait-for-stack (#557)", () => {
+  it("polls until the stack is terminal and returns the final status", async () => {
+    const mock = createMockCloudExecutor({ stacks: { "orders-table": { terminalStatus: "CREATE_COMPLETE" } } });
+    const capability = createWaitForStackCapability(mock.executor);
+    const output = await capability.run({ env: "dev", component: "orders-table" }, { stack: "orders-table" });
+    expect(output.stackStatus).toBe("CREATE_COMPLETE");
+  });
+
+  it("declares no rollback — a wait is read-only", () => {
+    const capability = createWaitForStackCapability(createMockCloudExecutor().executor);
+    expect(capability.rollback).toBeUndefined();
+  });
+});
+
+describe("wait-steady-state (#557)", () => {
+  it("returns runningCount once the ECS service reports stable", async () => {
+    const mock = createMockCloudExecutor({
+      ecsServices: { "prod/search": { runningCount: 3, desiredCount: 3, stable: true } },
+    });
+    const capability = createWaitSteadyStateCapability(mock.executor);
+    const output = await capability.run(
+      { env: "dev", component: "search-service" },
+      { service: "search", cluster: "prod" },
+    );
+    expect(output.runningCount).toBe(3);
+  });
+
+  it("defaults the cluster to 'default' when not given (matches the ALB/ECS pilot's bare `{ service }` step)", async () => {
+    const mock = createMockCloudExecutor({
+      ecsServices: { "default/search": { runningCount: 2, desiredCount: 2, stable: true } },
+    });
+    const capability = createWaitSteadyStateCapability(mock.executor);
+    const output = await capability.run({ env: "dev", component: "search-service" }, { service: "search" });
+    expect(output.runningCount).toBe(2);
+  });
+
+  it("times out if the service never stabilizes", async () => {
+    const mock = createMockCloudExecutor({
+      ecsServices: { "prod/search": { runningCount: 1, desiredCount: 3, stable: false } },
+    });
+    const capability = createWaitSteadyStateCapability(mock.executor);
+    await expect(
+      capability.run(
+        { env: "dev", component: "search-service" },
+        { service: "search", cluster: "prod", intervalMs: 1, timeoutMs: 5 },
+      ),
+    ).rejects.toThrow(/timed out/);
+  });
+});
+
+describe("wait-job (#561 — EMR job-run poll)", () => {
+  it("returns the terminal state once the job run completes", async () => {
+    const mock = createMockCloudExecutor({ jobRuns: { "run-1": { terminalState: "COMPLETED" } } });
+    const capability = createWaitJobCapability(mock.executor);
+    const output = await capability.run({ env: "dev", component: "emr-job" }, { runId: "run-1" });
+    expect(output.state).toBe("COMPLETED");
+  });
+
+  it("fails when the job run ends in a non-COMPLETED terminal state", async () => {
+    const mock = createMockCloudExecutor({ jobRuns: { "run-1": { terminalState: "FAILED" } } });
+    const capability = createWaitJobCapability(mock.executor);
+    await expect(capability.run({ env: "dev", component: "emr-job" }, { runId: "run-1" })).rejects.toThrow(
+      /ended in terminal state "FAILED"/,
+    );
+  });
+
+  it("declares no rollback — a job-run poll is read-only", () => {
+    const capability = createWaitJobCapability(createMockCloudExecutor().executor);
+    expect(capability.rollback).toBeUndefined();
+  });
+});

package/src/components/wait-aws.ts

@@ -0,0 +1,132 @@
+/**
+ * wait / verify family — the cloud-specific members, owned by the aws lexicon:
+ * `wait-for-stack` (CloudFormation), `wait-steady-state` (ECS), `wait-job`
+ * (EMR). The agnostic waits (`wait-cluster-healthy`, `wait-endpoint`,
+ * `health-gate`) stay in core. All poll a real cloud through the injectable aws
+ * `CloudExecutor` (./cloud-executor.ts); none has a rollback — a wait is a
+ * read-only observation, never a mutation.
+ */
+
+import type { Capability } from "@intentius/chant/components/capability";
+import { defaultCloudExecutor, sleep, type CloudExecutor } from "./cloud-executor";
+
+// ── wait-for-stack ───────────────────────────────────────────────────────────
+
+export interface WaitForStackInput {
+  /** CloudFormation stack name. */
+  stack: string;
+  /** Poll interval in ms. Default: 10000. */
+  intervalMs?: number;
+  /** Overall timeout in ms. */
+  timeoutMs?: number;
+}
+
+export interface WaitForStackOutput {
+  /** Terminal stack status (`CREATE_COMPLETE`, `UPDATE_COMPLETE`, ...). */
+  stackStatus: string;
+}
+
+/** Poll a CloudFormation stack until it reaches a terminal status. No rollback: a wait is a read-only observation. */
+export function createWaitForStackCapability(
+  executor: CloudExecutor = defaultCloudExecutor(),
+): Capability<WaitForStackInput, WaitForStackOutput> {
+  return {
+    kind: "wait-for-stack",
+    async run(_ctx, input) {
+      const { stackStatus } = await executor.cloudformation.waitForStack(input.stack, {
+        intervalMs: input.intervalMs,
+        timeoutMs: input.timeoutMs,
+      });
+      return { stackStatus };
+    },
+  };
+}
+
+/** Default `wait-for-stack` capability, backed by the real aws `CloudExecutor`. */
+export const waitForStackCapability: Capability<WaitForStackInput, WaitForStackOutput> = createWaitForStackCapability();
+
+// ── wait-steady-state ────────────────────────────────────────────────────────
+
+export interface WaitSteadyStateInput {
+  /** Service identifier (e.g. an ECS service name). */
+  service: string;
+  /** ECS cluster name/ARN the service lives in. Default: "default". */
+  cluster?: string;
+  /** Poll interval in ms. Default: 10000. */
+  intervalMs?: number;
+  /** Overall timeout in ms. Default: 10 minutes. */
+  timeoutMs?: number;
+}
+
+export interface WaitSteadyStateOutput {
+  /** Running task/instance count once steady state is reached. */
+  runningCount: number;
+}
+
+/** Poll an ECS service until running count matches desired and no deployment is in flight. No rollback: read-only. */
+export function createWaitSteadyStateCapability(
+  executor: CloudExecutor = defaultCloudExecutor(),
+): Capability<WaitSteadyStateInput, WaitSteadyStateOutput> {
+  return {
+    kind: "wait-steady-state",
+    async run(_ctx, input) {
+      const cluster = input.cluster ?? "default";
+      const intervalMs = input.intervalMs ?? 10_000;
+      const deadline = Date.now() + (input.timeoutMs ?? 10 * 60_000);
+      while (true) {
+        const state = await executor.ecs.describeService(cluster, input.service);
+        if (state.stable) return { runningCount: state.runningCount };
+        if (Date.now() > deadline) {
+          throw new Error(`wait-steady-state "${input.service}" timed out before reaching steady state`);
+        }
+        await sleep(intervalMs);
+      }
+    },
+  };
+}
+
+/** Default `wait-steady-state` capability, backed by the real aws `CloudExecutor`. */
+export const waitSteadyStateCapability: Capability<WaitSteadyStateInput, WaitSteadyStateOutput> =
+  createWaitSteadyStateCapability();
+
+// ── wait-job ─────────────────────────────────────────────────────────────────
+
+export interface WaitJobInput {
+  /** Job/step run id (e.g. from `emr-start-job-run` or `emr-submit-step`). */
+  runId: string;
+  /** Poll interval in ms. Default: 10000. */
+  intervalMs?: number;
+  /** Overall timeout in ms. */
+  timeoutMs?: number;
+}
+
+export interface WaitJobOutput {
+  /** Terminal job state (`COMPLETED`, `FAILED`, `CANCELLED`). */
+  state: string;
+}
+
+/**
+ * Poll a submitted job/step (e.g. an EMR job run started by `emr-start-job-run`)
+ * until it reaches a terminal state, failing the step if that state is not
+ * `COMPLETED`. No rollback: read-only observation.
+ */
+export function createWaitJobCapability(
+  executor: CloudExecutor = defaultCloudExecutor(),
+): Capability<WaitJobInput, WaitJobOutput> {
+  return {
+    kind: "wait-job",
+    async run(_ctx, input) {
+      const { state } = await executor.emr.waitForJobRun(input.runId, {
+        intervalMs: input.intervalMs,
+        timeoutMs: input.timeoutMs,
+      });
+      if (state !== "COMPLETED") {
+        throw new Error(`wait-job "${input.runId}" ended in terminal state "${state}", expected "COMPLETED"`);
+      }
+      return { state };
+    },
+  };
+}
+
+/** Default `wait-job` capability, backed by the real aws `CloudExecutor`. */
+export const waitJobCapability: Capability<WaitJobInput, WaitJobOutput> = createWaitJobCapability();