sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ FIS/ ExperimentTemplate.ts

import * as crypto from "node:crypto";
import * as fis from "@distilled.cloud/aws/fis";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags, tagRecord } from "alchemy/Tags";
import { toSeconds } from "alchemy/Util/Duration";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

/**
 * A filter that narrows the resources selected by an experiment template
 * target using resource attribute paths.
 */
export interface ExperimentTemplateTargetFilter {
  /**
   * The attribute path used to filter, e.g. `State.Name` for EC2 instances.
   */
  path: string;
  /**
   * The attribute values that a resource must match to be included.
   */
  values: string[];
}

/**
 * A target definition for an experiment template — the set of resources an
 * action is applied to.
 */
export interface ExperimentTemplateTarget {
  /**
   * The resource type of the target, e.g. `aws:ec2:instance`.
   */
  resourceType: string;
  /**
   * ARNs of specific resources to target. Mutually exclusive with
   * `resourceTags`.
   */
  resourceArns?: string[];
  /**
   * Tags that resources must have to be targeted. Mutually exclusive with
   * `resourceArns`.
   */
  resourceTags?: Record<string, string>;
  /**
   * Filters that further narrow the targeted resources by attribute path,
   * e.g. only running instances.
   */
  filters?: ExperimentTemplateTargetFilter[];
  /**
   * How targets are selected from the matched resources, e.g. `ALL`,
   * `COUNT(1)`, or `PERCENT(25)`.
   */
  selectionMode: string;
  /**
   * Resource-type-specific parameters for the target.
   */
  parameters?: Record<string, string>;
}

/**
 * An action carried out on targets during an experiment, e.g.
 * `aws:ec2:stop-instances`.
 */
export interface ExperimentTemplateAction {
  /**
   * The FIS action ID, e.g. `aws:ec2:stop-instances` or
   * `aws:fis:wait`.
   */
  actionId: string;
  /**
   * A description of the action.
   */
  description?: string;
  /**
   * Action-specific parameters, e.g.
   * `{ startInstancesAfterDuration: "PT2M" }`.
   */
  parameters?: Record<string, string>;
  /**
   * The named targets (keys of the template's `targets` map) the action
   * applies to, keyed by the action's target name, e.g.
   * `{ Instances: "MyTarget" }`.
   */
  targets?: Record<string, string>;
  /**
   * Names of other actions that must complete before this action starts.
   */
  startAfter?: string[];
}

/**
 * A stop condition for an experiment. When triggered while an experiment is
 * running, the experiment is stopped.
 */
export interface ExperimentTemplateStopCondition {
  /**
   * The source of the stop condition: `aws:cloudwatch:alarm` or `none`.
   */
  source: "aws:cloudwatch:alarm" | "none" | (string & {});
  /**
   * The ARN of the CloudWatch alarm. Required when `source` is
   * `aws:cloudwatch:alarm`.
   */
  value?: string;
}

/**
 * Experiment log delivery configuration.
 */
export interface ExperimentTemplateLogConfiguration {
  /**
   * Deliver experiment logs to a CloudWatch Logs log group.
   */
  cloudWatchLogsConfiguration?: {
    /**
     * The ARN of the destination log group.
     */
    logGroupArn: string;
  };
  /**
   * Deliver experiment logs to an S3 bucket.
   */
  s3Configuration?: {
    /**
     * The name of the destination bucket.
     */
    bucketName: string;
    /**
     * The bucket prefix for delivered log objects.
     */
    prefix?: string;
  };
  /**
   * The schema version of delivered log records.
   * @default 2
   */
  logSchemaVersion?: number;
}

/**
 * Experiment options controlling account targeting and empty-target
 * behavior.
 */
export interface ExperimentTemplateExperimentOptions {
  /**
   * Whether the experiment targets resources in the current account only or
   * across multiple accounts. Changing this replaces the template.
   * @default "single-account"
   */
  accountTargeting?: "single-account" | "multi-account";
  /**
   * What happens when a target resolves to zero resources: `fail` the
   * experiment or `skip` the action.
   * @default "fail"
   */
  emptyTargetResolutionMode?: "fail" | "skip";
}

/**
 * Experiment report configuration.
 */
export interface ExperimentTemplateReportConfiguration {
  /**
   * Where the experiment report is delivered.
   */
  outputs?: {
    /**
     * Deliver the report to an S3 bucket.
     */
    s3Configuration?: {
      /**
       * The name of the destination bucket.
       */
      bucketName?: string;
      /**
       * The bucket prefix for the delivered report.
       */
      prefix?: string;
    };
  };
  /**
   * Data sources included in the report.
   */
  dataSources?: {
    /**
     * CloudWatch dashboards to capture in the report.
     */
    cloudWatchDashboards?: {
      /**
       * The ARN of the CloudWatch dashboard.
       */
      dashboardIdentifier?: string;
    }[];
  };
  /**
   * How long before the experiment to capture data, e.g. `"10 minutes"` or
   * `Duration.minutes(10)`. Sent to FIS as an ISO-8601 duration (`PT10M`).
   */
  preExperimentDuration?: Duration.Input;
  /**
   * How long after the experiment to capture data, e.g. `"10 minutes"` or
   * `Duration.minutes(10)`. Sent to FIS as an ISO-8601 duration (`PT10M`).
   */
  postExperimentDuration?: Duration.Input;
}

export interface ExperimentTemplateProps {
  /**
   * A description of the experiment template.
   * @default the logical ID of the resource
   */
  description?: string;
  /**
   * The ARN of the IAM role that grants FIS permission to perform the
   * template's actions on your behalf. The role must trust
   * `fis.amazonaws.com`.
   */
  roleArn: string;
  /**
   * The actions carried out during an experiment, keyed by a name of your
   * choosing.
   */
  actions: Record<string, ExperimentTemplateAction>;
  /**
   * The targets the actions apply to, keyed by a name of your choosing and
   * referenced from each action's `targets` map.
   */
  targets?: Record<string, ExperimentTemplateTarget>;
  /**
   * Stop conditions that halt a running experiment when triggered.
   * @default [{ source: "none" }]
   */
  stopConditions?: ExperimentTemplateStopCondition[];
  /**
   * Experiment log delivery configuration. Once configured, log delivery
   * cannot be fully removed via the API — only changed.
   */
  logConfiguration?: ExperimentTemplateLogConfiguration;
  /**
   * Experiment options. `accountTargeting` is create-only — changing it
   * replaces the template.
   */
  experimentOptions?: ExperimentTemplateExperimentOptions;
  /**
   * Experiment report configuration.
   */
  experimentReportConfiguration?: ExperimentTemplateReportConfiguration;
  /**
   * Tags to apply to the experiment template. Merged with internal Alchemy
   * tags.
   */
  tags?: Record<string, string>;
}

export interface ExperimentTemplate extends Resource<
  "AWS.FIS.ExperimentTemplate",
  ExperimentTemplateProps,
  {
    /**
     * The generated ID of the experiment template, e.g. `EXT1a2b3c4d`.
     */
    id: string;
    /**
     * The ARN of the experiment template.
     */
    arn: string;
    /**
     * The ARN of the IAM role the experiment runs as.
     */
    roleArn: string;
  },
  never,
  Providers
> {}

/**
 * An AWS Fault Injection Service (FIS) experiment template — a reusable
 * definition of a chaos-engineering experiment: the targets to disrupt, the
 * fault actions to run against them, and the stop conditions that abort a
 * runaway experiment.
 *
 * Creating a template is free and does not disrupt any resources — faults
 * are only injected when an experiment is explicitly started from the
 * template.
 * ### Creating Experiment Templates
 * **Example:** Stop EC2 instances selected by tag
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const role = yield* AWS.IAM.Role("FisRole", {
 *   assumeRolePolicyDocument: {
 *     Version: "2012-10-17",
 *     Statement: [{
 *       Effect: "Allow",
 *       Principal: { Service: "fis.amazonaws.com" },
 *       Action: ["sts:AssumeRole"],
 *     }],
 *   },
 *   managedPolicyArns: [
 *     "arn:aws:iam::aws:policy/service-role/AWSFaultInjectionSimulatorEC2Access",
 *   ],
 * });
 *
 * const template = yield* AWS.FIS.ExperimentTemplate("StopInstances", {
 *   description: "Stop one tagged instance for two minutes",
 *   roleArn: role.roleArn,
 *   targets: {
 *     Instances: {
 *       resourceType: "aws:ec2:instance",
 *       resourceTags: { ChaosReady: "true" },
 *       selectionMode: "COUNT(1)",
 *     },
 *   },
 *   actions: {
 *     StopInstances: {
 *       actionId: "aws:ec2:stop-instances",
 *       parameters: { startInstancesAfterDuration: "PT2M" },
 *       targets: { Instances: "Instances" },
 *     },
 *   },
 * });
 * ```
 *
 * **Example:** Stop condition backed by a CloudWatch alarm
 * ```typescript
 * const template = yield* AWS.FIS.ExperimentTemplate("GuardedExperiment", {
 *   roleArn: role.roleArn,
 *   targets: {
 *     Instances: {
 *       resourceType: "aws:ec2:instance",
 *       resourceTags: { ChaosReady: "true" },
 *       selectionMode: "ALL",
 *     },
 *   },
 *   actions: {
 *     StopInstances: {
 *       actionId: "aws:ec2:stop-instances",
 *       targets: { Instances: "Instances" },
 *     },
 *   },
 *   stopConditions: [
 *     {
 *       source: "aws:cloudwatch:alarm",
 *       value: alarmArn,
 *     },
 *   ],
 * });
 * ```
 *
 * **Example:** Wait action sequenced after a fault
 * ```typescript
 * const template = yield* AWS.FIS.ExperimentTemplate("SequencedExperiment", {
 *   roleArn: role.roleArn,
 *   actions: {
 *     Wait: {
 *       actionId: "aws:fis:wait",
 *       parameters: { duration: "PT1M" },
 *     },
 *     WaitAgain: {
 *       actionId: "aws:fis:wait",
 *       parameters: { duration: "PT1M" },
 *       startAfter: ["Wait"],
 *     },
 *   },
 * });
 * ```
 *
 * @resource
 */
export const ExperimentTemplate = Resource<ExperimentTemplate>("AWS.FIS.ExperimentTemplate");

/**
 * A freshly created IAM role referenced by `roleArn` can take a few seconds
 * to become visible to FIS, which rejects the create/update with a
 * `ValidationException` until the role propagates. Bounded retry through the
 * propagation window. Explicitly typed so the conditional `Retry.Return`
 * type never leaks into declaration emit.
 */
const retryRolePropagation = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "ValidationException",
    schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(10)]),
  });

/**
 * Deterministic stringification for observed-vs-desired comparison: sorts
 * object keys and drops `undefined` members, empty arrays, and empty objects
 * so wire-level "absent" and "empty" compare equal.
 */
const normalize = (value: unknown): unknown => {
  if (Array.isArray(value)) {
    const items = value.map(normalize).filter((v) => v !== undefined);
    return items.length === 0 ? undefined : items;
  }
  if (typeof value === "object" && value !== null) {
    const entries = Object.entries(value)
      .map(([k, v]) => [k, normalize(v)] as const)
      .filter(([, v]) => v !== undefined)
      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
    return entries.length === 0 ? undefined : Object.fromEntries(entries);
  }
  return value;
};

const stableStringify = (value: unknown): string => JSON.stringify(normalize(value) ?? null);

export const ExperimentTemplateProvider = () =>
  Provider.effect(
    ExperimentTemplate,
    Effect.gen(function* () {
      const getTemplate = (templateId: string) =>
        fis.getExperimentTemplate({ id: templateId }).pipe(
          Effect.map((r) => r.experimentTemplate),
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
        );

      // FIS template IDs are server-generated, so when the cached output is
      // lost (state persistence failure) we recover our template by the
      // internal Alchemy tags carried on the list summaries. The match is
      // scoped to the INSTANCE id (not just stack/stage/logical id): during a
      // replacement the new instance must not "recover" the old physical
      // template — it has to create a fresh one.
      const findByTags = Effect.fn(function* (id: string, instanceId: string) {
        const summaries = yield* fis.listExperimentTemplates.items({}).pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk)),
        );
        for (const summary of summaries) {
          if (
            summary.id !== undefined &&
            tagRecord(summary.tags)["alchemy::instance"] === instanceId &&
            (yield* hasAlchemyTags(id, summary.tags))
          ) {
            return yield* getTemplate(summary.id);
          }
        }
        return undefined;
      });

      const toAttrs = (template: fis.ExperimentTemplate) => ({
        id: template.id!,
        arn: template.arn!,
        roleArn: template.roleArn!,
      });

      // Report-capture durations are `Duration.Input`s; the FIS wire format
      // is an ISO-8601 duration string (e.g. `PT10M`). Normalize through the
      // central Duration util (handles state-persisted Duration JSON), then
      // emit hours when the duration is whole hours, else minutes, else
      // seconds, matching the canonical forms FIS reports back.
      const toIsoDuration = (input: Duration.Input | undefined): string | undefined => {
        if (input === undefined) return undefined;
        const seconds = toSeconds(input)!;
        if (seconds > 0 && seconds % 3600 === 0) return `PT${seconds / 3600}H`;
        if (seconds % 60 === 0) return `PT${seconds / 60}M`;
        return `PT${seconds}S`;
      };

      // Project the report configuration into the wire shape (ISO-8601
      // duration strings).
      const projectReportConfiguration = (
        config: ExperimentTemplateReportConfiguration | undefined,
      ) =>
        config
          ? {
              ...config,
              preExperimentDuration: toIsoDuration(config.preExperimentDuration),
              postExperimentDuration: toIsoDuration(config.postExperimentDuration),
            }
          : undefined;

      // The desired mutable state, projected into the wire shape that
      // `getExperimentTemplate` reports so observed-vs-desired comparison is
      // structural.
      const projectDesired = (id: string, props: ExperimentTemplateProps) => ({
        description: props.description ?? id,
        roleArn: props.roleArn,
        stopConditions: props.stopConditions ?? [{ source: "none" }],
        targets: props.targets ?? {},
        actions: props.actions,
        // Settable-but-not-removable aspects only participate in the
        // comparison while the user declares them, so dropping the prop
        // doesn't cause a perpetual (and futile) update call.
        logConfiguration: props.logConfiguration
          ? {
              ...props.logConfiguration,
              logSchemaVersion: props.logConfiguration.logSchemaVersion ?? 2,
            }
          : undefined,
        emptyTargetResolutionMode: props.experimentOptions?.emptyTargetResolutionMode,
        experimentReportConfiguration: projectReportConfiguration(
          props.experimentReportConfiguration,
        ),
      });

      const projectObserved = (
        template: fis.ExperimentTemplate,
        props: ExperimentTemplateProps,
      ) => ({
        description: template.description,
        roleArn: template.roleArn,
        stopConditions: template.stopConditions ?? [],
        targets: template.targets ?? {},
        actions: template.actions ?? {},
        logConfiguration: props.logConfiguration ? template.logConfiguration : undefined,
        emptyTargetResolutionMode: props.experimentOptions?.emptyTargetResolutionMode
          ? template.experimentOptions?.emptyTargetResolutionMode
          : undefined,
        experimentReportConfiguration: props.experimentReportConfiguration
          ? template.experimentReportConfiguration
          : undefined,
      });

      return ExperimentTemplate.Provider.of({
        stables: ["id", "arn"],

        // Enumerate every experiment template in the ambient account/region,
        // hydrating each summary into the full attribute shape. A template
        // can vanish between enumeration and hydration; drop it.
        list: () =>
          Effect.gen(function* () {
            const summaries = yield* fis.listExperimentTemplates.items({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk)),
            );
            const items = yield* Effect.forEach(
              summaries,
              (summary) =>
                summary.id === undefined
                  ? Effect.undefined
                  : getTemplate(summary.id).pipe(Effect.map((t) => (t ? toAttrs(t) : undefined))),
              { concurrency: 10 },
            );
            return items.filter(
              (item): item is ExperimentTemplate["Attributes"] => item !== undefined,
            );
          }),

        read: Effect.fn(function* ({ id, instanceId, output }) {
          const template = output?.id
            ? yield* getTemplate(output.id)
            : yield* findByTags(id, instanceId);
          if (template === undefined) return undefined;
          const attrs = toAttrs(template);
          return (yield* hasAlchemyTags(id, template.tags)) ? attrs : Unowned(attrs);
        }),

        diff: Effect.fn(function* ({ news, olds }) {
          // accountTargeting is create-only — changing it replaces. Other
          // props (commonly roleArn) are unresolved Outputs during plan, so
          // narrow only the field replacement detection needs rather than
          // requiring the whole props object to be resolved.
          const newOptions = (
            news as {
              experimentOptions?: Input<ExperimentTemplateExperimentOptions>;
            }
          ).experimentOptions;
          if (newOptions !== undefined && !isResolved(newOptions)) {
            return undefined;
          }
          const oldTargeting = olds.experimentOptions?.accountTargeting ?? "single-account";
          const newTargeting = newOptions?.accountTargeting ?? "single-account";
          if (oldTargeting !== newTargeting) {
            return { action: "replace" } as const;
          }
          // fall through: undefined → default update
        }),

        reconcile: Effect.fn(function* ({ id, instanceId, news, output, session }) {
          const internalTags = yield* createInternalTags(id);
          const desiredTags = {
            ...news.tags,
            ...internalTags,
            "alchemy::instance": instanceId,
          };
          const desired = projectDesired(id, news);

          // 1. Observe — cloud state is authoritative; output is only an id
          // cache. Fall back to instance-scoped tag recovery when the id is
          // unknown (state persistence failure).
          let observed = output?.id ? yield* getTemplate(output.id) : undefined;
          if (observed === undefined) {
            observed = yield* findByTags(id, instanceId);
          }

          // 2. Ensure — create if missing. The clientToken is a per-request
          // idempotency token, not a physical name.
          if (observed === undefined) {
            const clientToken = yield* Effect.sync(() => crypto.randomUUID());
            observed = yield* retryRolePropagation(
              fis.createExperimentTemplate({
                clientToken,
                description: desired.description,
                stopConditions: desired.stopConditions,
                targets: desired.targets,
                actions: desired.actions,
                roleArn: news.roleArn,
                logConfiguration: desired.logConfiguration,
                experimentOptions: news.experimentOptions,
                experimentReportConfiguration: desired.experimentReportConfiguration,
                tags: desiredTags,
              }),
            ).pipe(Effect.map((r) => r.experimentTemplate!));
          } else if (
            // 3a. Sync definition — compare the observed template against the
            // desired projection and apply a single update on any delta
            // (UpdateExperimentTemplate replaces the provided aspects
            // wholesale). Skip the API entirely on no-op.
            stableStringify(projectObserved(observed, news)) !== stableStringify(desired)
          ) {
            observed = yield* retryRolePropagation(
              fis.updateExperimentTemplate({
                id: observed.id!,
                description: desired.description,
                stopConditions: desired.stopConditions,
                targets: desired.targets,
                actions: desired.actions,
                roleArn: news.roleArn,
                logConfiguration: desired.logConfiguration,
                experimentOptions: news.experimentOptions
                  ? {
                      emptyTargetResolutionMode: news.experimentOptions.emptyTargetResolutionMode,
                    }
                  : undefined,
                experimentReportConfiguration: desired.experimentReportConfiguration,
              }),
            ).pipe(Effect.map((r) => r.experimentTemplate!));
          }

          // 3b. Sync tags — diff against the OBSERVED cloud tags (the create
          // path already landed them, so this is a no-op there; adoption and
          // out-of-band drift converge here).
          const arn = observed.arn!;
          const currentTags = tagRecord(observed.tags);
          const { upsert, removed } = diffTags(currentTags, desiredTags);
          if (upsert.length > 0) {
            yield* fis.tagResource({
              resourceArn: arn,
              tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
            });
          }
          if (removed.length > 0) {
            yield* fis.untagResource({
              resourceArn: arn,
              tagKeys: removed,
            });
          }

          yield* session.note(observed.id!);
          return toAttrs(observed);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* fis
            .deleteExperimentTemplate({ id: output.id })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      });
    }),
  );