sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Budgets/ BudgetAction.ts

import * as budgets from "@distilled.cloud/aws/budgets";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { BudgetSubscriber } from "./Budget.ts";

/**
 * The threshold that triggers a budget action.
 */
export interface BudgetActionThreshold {
  /**
   * The threshold value. Interpreted as a percentage of the budget limit by
   * default, or an absolute amount when `actionThresholdType` is
   * `ABSOLUTE_VALUE`.
   */
  actionThresholdValue: number;
  /**
   * Whether the threshold is a percentage of the budget or an absolute value.
   */
  actionThresholdType: "PERCENTAGE" | "ABSOLUTE_VALUE" | (string & {});
}

/**
 * What the action does when it fires — exactly one of the three definitions
 * must be set, matching the action's `actionType`.
 */
export interface BudgetActionDefinition {
  /**
   * For `APPLY_IAM_POLICY` actions — attach the managed policy to the given
   * IAM roles, groups, and/or users.
   */
  iamActionDefinition?: {
    /** ARN of the managed policy to attach. */
    policyArn: string;
    /** IAM role names to attach the policy to. */
    roles?: string[];
    /** IAM group names to attach the policy to. */
    groups?: string[];
    /** IAM user names to attach the policy to. */
    users?: string[];
  };
  /**
   * For `APPLY_SCP_POLICY` actions — attach the service control policy to
   * the given Organizations targets.
   */
  scpActionDefinition?: {
    /** The SCP policy ID. */
    policyId: string;
    /** Organizations target IDs (accounts or OUs). */
    targetIds: string[];
  };
  /**
   * For `RUN_SSM_DOCUMENTS` actions — stop the given EC2 or RDS instances.
   */
  ssmActionDefinition?: {
    /** Which instances to stop. */
    actionSubType: "STOP_EC2_INSTANCES" | "STOP_RDS_INSTANCES" | (string & {});
    /** Region of the instances. */
    region: string;
    /** Instance IDs to stop. */
    instanceIds: string[];
  };
}

export interface BudgetActionProps {
  /**
   * Name of the budget the action belongs to.
   *
   * Changing the budget replaces the action.
   */
  budgetName: string;
  /**
   * Whether the action triggers on actual or forecasted spend.
   */
  notificationType: "ACTUAL" | "FORECASTED" | (string & {});
  /**
   * The kind of action to run when the threshold is crossed.
   *
   * Changing the action type replaces the action.
   */
  actionType: "APPLY_IAM_POLICY" | "APPLY_SCP_POLICY" | "RUN_SSM_DOCUMENTS" | (string & {});
  /**
   * The threshold that triggers the action.
   */
  actionThreshold: BudgetActionThreshold;
  /**
   * What the action does — must match `actionType`.
   */
  definition: BudgetActionDefinition;
  /**
   * ARN of the IAM role AWS Budgets assumes to run the action. The role must
   * trust `budgets.amazonaws.com`.
   */
  executionRoleArn: string;
  /**
   * Whether the action runs automatically when the threshold is crossed or
   * requires manual approval.
   * @default "MANUAL"
   */
  approvalModel?: "AUTOMATIC" | "MANUAL" | (string & {});
  /**
   * Subscribers notified when the action is triggered or requires approval.
   */
  subscribers: BudgetSubscriber[];
  /**
   * Tags applied to the budget action.
   */
  tags?: Record<string, string>;
}

export interface BudgetAction extends Resource<
  "AWS.Budgets.BudgetAction",
  BudgetActionProps,
  {
    /**
     * The system-generated ID of the action.
     */
    actionId: string;
    /**
     * Name of the budget the action belongs to.
     */
    budgetName: string;
    /**
     * The AWS account ID that owns the action.
     */
    accountId: string;
    /**
     * ARN of the action, e.g.
     * `arn:aws:budgets::123456789012:budget/my-budget/action/abc123`.
     */
    actionArn: string;
  },
  never,
  Providers
> {}

/**
 * An AWS Budgets action — runs an IAM policy attachment, SCP attachment, or
 * SSM stop-instances document when a budget threshold is crossed, either
 * automatically or after manual approval.
 *
 * The execution role must trust `budgets.amazonaws.com` and carry the
 * permissions the action needs (the AWS managed policy
 * `AWSBudgetsActionsWithAWSResourceControlAccess` covers all three kinds).
 *
 * ### Creating a Budget Action
 * **Example:** Apply a Deny-All Policy at 100% of the Budget
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const budget = yield* AWS.Budgets.Budget("MonthlyCost", {
 *   budgetLimit: { amount: "100", unit: "USD" },
 * });
 *
 * const action = yield* AWS.Budgets.BudgetAction("FreezeSpend", {
 *   budgetName: budget.budgetName,
 *   notificationType: "ACTUAL",
 *   actionType: "APPLY_IAM_POLICY",
 *   actionThreshold: {
 *     actionThresholdValue: 100,
 *     actionThresholdType: "PERCENTAGE",
 *   },
 *   definition: {
 *     iamActionDefinition: {
 *       policyArn: "arn:aws:iam::aws:policy/AWSDenyAll",
 *       roles: [devRole.roleName],
 *     },
 *   },
 *   executionRoleArn: executionRole.roleArn,
 *   approvalModel: "MANUAL",
 *   subscribers: [{ subscriptionType: "EMAIL", address: "team@example.com" }],
 * });
 * ```
 *
 * **Example:** Stop EC2 Instances Automatically
 * ```typescript
 * const action = yield* AWS.Budgets.BudgetAction("StopDevInstances", {
 *   budgetName: budget.budgetName,
 *   notificationType: "ACTUAL",
 *   actionType: "RUN_SSM_DOCUMENTS",
 *   actionThreshold: {
 *     actionThresholdValue: 100,
 *     actionThresholdType: "PERCENTAGE",
 *   },
 *   definition: {
 *     ssmActionDefinition: {
 *       actionSubType: "STOP_EC2_INSTANCES",
 *       region: "us-east-1",
 *       instanceIds: [instance.instanceId],
 *     },
 *   },
 *   executionRoleArn: executionRole.roleArn,
 *   approvalModel: "AUTOMATIC",
 *   subscribers: [{ subscriptionType: "EMAIL", address: "team@example.com" }],
 * });
 * ```
 *
 * @resource
 */
export const BudgetAction = Resource<BudgetAction>("AWS.Budgets.BudgetAction");

/**
 * Compute the ARN of a budget action. Budgets is a global service, so the ARN
 * has no region component.
 */
export const budgetActionArn = (accountId: string, budgetName: string, actionId: string): string =>
  `arn:aws:budgets::${accountId}:budget/${budgetName}/action/${actionId}`;

const toDefinition = (d: BudgetActionDefinition): budgets.Definition => ({
  IamActionDefinition: d.iamActionDefinition
    ? {
        PolicyArn: d.iamActionDefinition.policyArn,
        Roles: d.iamActionDefinition.roles,
        Groups: d.iamActionDefinition.groups,
        Users: d.iamActionDefinition.users,
      }
    : undefined,
  ScpActionDefinition: d.scpActionDefinition
    ? {
        PolicyId: d.scpActionDefinition.policyId,
        TargetIds: d.scpActionDefinition.targetIds,
      }
    : undefined,
  SsmActionDefinition: d.ssmActionDefinition
    ? {
        ActionSubType: d.ssmActionDefinition.actionSubType,
        Region: d.ssmActionDefinition.region,
        InstanceIds: d.ssmActionDefinition.instanceIds,
      }
    : undefined,
});

const toSubscribers = (subscribers: BudgetSubscriber[]): budgets.Subscriber[] =>
  subscribers.map((s) => ({
    SubscriptionType: s.subscriptionType,
    Address: s.address,
  }));

/** The updatable slice of an action, in a canonical shape for comparison. */
const updatableSlice = (a: {
  NotificationType: string;
  ActionThreshold: budgets.ActionThreshold;
  Definition: budgets.Definition;
  ExecutionRoleArn: string;
  ApprovalModel: string;
  Subscribers: readonly budgets.Subscriber[];
}): string =>
  JSON.stringify({
    NotificationType: a.NotificationType,
    ActionThreshold: {
      ActionThresholdValue: a.ActionThreshold.ActionThresholdValue,
      ActionThresholdType: a.ActionThreshold.ActionThresholdType,
    },
    Definition: {
      IamActionDefinition: a.Definition.IamActionDefinition
        ? {
            PolicyArn: a.Definition.IamActionDefinition.PolicyArn,
            Roles: a.Definition.IamActionDefinition.Roles ?? [],
            Groups: a.Definition.IamActionDefinition.Groups ?? [],
            Users: a.Definition.IamActionDefinition.Users ?? [],
          }
        : undefined,
      ScpActionDefinition: a.Definition.ScpActionDefinition,
      SsmActionDefinition: a.Definition.SsmActionDefinition,
    },
    ExecutionRoleArn: a.ExecutionRoleArn,
    ApprovalModel: a.ApprovalModel,
    // Distilled marks `Subscriber.Address` sensitive — observed subscribers
    // come back Redacted; unwrap so the observed-vs-desired comparison does
    // not see `<redacted>` and issue a dirty update on every reconcile.
    Subscribers: [...a.Subscribers]
      .map(
        (s) =>
          `${s.SubscriptionType}:${
            Redacted.isRedacted(s.Address) ? Redacted.value(s.Address) : s.Address
          }`,
      )
      .sort(),
  });

export const BudgetActionProvider = () =>
  Provider.effect(
    BudgetAction,
    Effect.gen(function* () {
      const syncTags = Effect.fn(function* (arn: string, desired: Record<string, string>) {
        const observed = yield* budgets.listTagsForResource({ ResourceARN: arn }).pipe(
          Effect.map((r) =>
            Object.fromEntries((r.ResourceTags ?? []).map((t) => [t.Key, t.Value])),
          ),
          Effect.catchTag("NotFoundException", () => Effect.succeed({} as Record<string, string>)),
        );
        const { removed, upsert } = diffTags(observed, desired);
        if (upsert.length > 0) {
          yield* budgets.tagResource({
            ResourceARN: arn,
            ResourceTags: upsert,
          });
        }
        if (removed.length > 0) {
          yield* budgets.untagResource({
            ResourceARN: arn,
            ResourceTagKeys: removed,
          });
        }
      });

      const attrs = (accountId: string, budgetName: string, actionId: string) =>
        ({
          actionId,
          budgetName,
          accountId,
          actionArn: budgetActionArn(accountId, budgetName, actionId),
        }) as const;

      return BudgetAction.Provider.of({
        stables: ["actionId", "budgetName", "accountId", "actionArn"],
        list: () =>
          Effect.gen(function* () {
            const { accountId } = yield* AWSEnvironment.current;
            return yield* budgets.describeBudgetActionsForAccount
              .pages({ AccountId: accountId })
              .pipe(
                Stream.runCollect,
                Effect.map((chunk) =>
                  Array.from(chunk)
                    .flatMap((page) => page.Actions ?? [])
                    .map((a) => attrs(accountId, a.BudgetName, a.ActionId)),
                ),
              );
          }),
        read: Effect.fn(function* ({ output }) {
          // The action ID is server-generated — without persisted output there
          // is no deterministic way to find the action.
          if (!output) return undefined;
          const { accountId } = yield* AWSEnvironment.current;
          const found = yield* budgets
            .describeBudgetAction({
              AccountId: accountId,
              BudgetName: output.budgetName,
              ActionId: output.actionId,
            })
            .pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
          if (!found?.Action) return undefined;
          return attrs(accountId, output.budgetName, output.actionId);
        }),
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (olds.budgetName !== news.budgetName || olds.actionType !== news.actionType) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const { accountId } = yield* AWSEnvironment.current;
          const internalTags = yield* createInternalTags(id);
          const desiredSubscribers = toSubscribers(news.subscribers);
          const desired = {
            NotificationType: news.notificationType,
            ActionThreshold: {
              ActionThresholdValue: news.actionThreshold.actionThresholdValue,
              ActionThresholdType: news.actionThreshold.actionThresholdType,
            },
            Definition: toDefinition(news.definition),
            ExecutionRoleArn: news.executionRoleArn,
            ApprovalModel: news.approvalModel ?? "MANUAL",
            Subscribers: desiredSubscribers,
          };

          // OBSERVE — the action ID is server-generated, so `output` is the
          // only handle; cloud state stays authoritative via describe.
          const observed = output
            ? yield* budgets
                .describeBudgetAction({
                  AccountId: accountId,
                  BudgetName: output.budgetName,
                  ActionId: output.actionId,
                })
                .pipe(
                  Effect.map((r) => r.Action),
                  Effect.catchTag("NotFoundException", () => Effect.undefined),
                )
            : undefined;

          let actionId: string;
          if (!observed) {
            // ENSURE — create. A freshly created execution role can take a
            // few seconds to become assumable by budgets.amazonaws.com, which
            // surfaces as InvalidParameterException/AccessDeniedException.
            const created = yield* budgets
              .createBudgetAction({
                AccountId: accountId,
                BudgetName: news.budgetName,
                NotificationType: desired.NotificationType,
                ActionType: news.actionType,
                ActionThreshold: desired.ActionThreshold,
                Definition: desired.Definition,
                ExecutionRoleArn: desired.ExecutionRoleArn,
                ApprovalModel: desired.ApprovalModel,
                Subscribers: desired.Subscribers,
                ResourceTags: Object.entries({
                  ...news.tags,
                  ...internalTags,
                }).map(([Key, Value]) => ({ Key, Value })),
              })
              .pipe(
                Effect.retry({
                  while: (e): boolean =>
                    e._tag === "InvalidParameterException" || e._tag === "AccessDeniedException",
                  schedule: Schedule.exponential("2 seconds"),
                  times: 6,
                }),
              );
            actionId = created.ActionId;
          } else {
            actionId = observed.ActionId;
            // SYNC — apply the update only when the observed action differs
            // from the desired definition.
            if (updatableSlice(observed) !== updatableSlice(desired)) {
              yield* budgets
                .updateBudgetAction({
                  AccountId: accountId,
                  BudgetName: news.budgetName,
                  ActionId: actionId,
                  NotificationType: desired.NotificationType,
                  ActionThreshold: desired.ActionThreshold,
                  Definition: desired.Definition,
                  ExecutionRoleArn: desired.ExecutionRoleArn,
                  ApprovalModel: desired.ApprovalModel,
                  Subscribers: desired.Subscribers,
                })
                .pipe(
                  Effect.retry({
                    while: (e): boolean => e._tag === "ResourceLockedException",
                    schedule: Schedule.exponential("2 seconds"),
                    times: 6,
                  }),
                );
            }
          }

          // SYNC tags against observed cloud tags.
          const arn = budgetActionArn(accountId, news.budgetName, actionId);
          yield* syncTags(arn, { ...news.tags, ...internalTags });

          yield* session.note(actionId);
          return attrs(accountId, news.budgetName, actionId);
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* budgets
            .deleteBudgetAction({
              AccountId: output.accountId,
              BudgetName: output.budgetName,
              ActionId: output.actionId,
            })
            .pipe(
              // An action mid-execution is briefly locked; wait it out.
              Effect.retry({
                while: (e): boolean => e._tag === "ResourceLockedException",
                schedule: Schedule.exponential("2 seconds"),
                times: 6,
              }),
              Effect.catchTag("NotFoundException", () => Effect.void),
            );
        }),
      });
    }),
  );