sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Backup/ BackupVault.ts

import * as backup from "@distilled.cloud/aws/backup";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import {
  normalizePolicyDocument,
  stringifyPolicyDocument,
  type PolicyDocument,
} from "../IAM/Policy.ts";
import type { Providers } from "../Providers.ts";

export interface BackupVaultProps {
  /**
   * Name of the backup vault. Must be between 2 and 50 characters and
   * contain only letters, numbers, hyphens, and underscores. If omitted, a
   * unique name is generated from the app, stage, and logical ID.
   *
   * Changing the name replaces the vault.
   */
  backupVaultName?: string;
  /**
   * ARN of the KMS key used to encrypt the recovery points stored in this
   * vault. If omitted, AWS Backup uses an AWS-owned key.
   *
   * The encryption key is fixed at creation — changing it replaces the vault.
   */
  encryptionKeyArn?: string;
  /**
   * Resource-based access policy attached to the vault. Provided as a
   * structured {@link PolicyDocument} (typed actions, drift-normalized on
   * re-deploy) or a raw JSON string escape hatch. Omit to leave the vault
   * without a resource policy.
   */
  accessPolicy?: PolicyDocument | string;
  /**
   * Tags to apply to the vault. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface BackupVault extends Resource<
  "AWS.Backup.BackupVault",
  BackupVaultProps,
  {
    /**
     * Name of the backup vault.
     */
    backupVaultName: string;
    /**
     * ARN of the backup vault.
     */
    backupVaultArn: string;
  },
  never,
  Providers
> {}

/**
 * An AWS Backup vault — a logical container that stores and organizes
 * recovery points created by backup jobs.
 *
 * A vault name is auto-generated from the app, stage, and logical ID unless
 * you provide one explicitly. Recovery points can optionally be encrypted
 * with a customer-managed KMS key, and access to the vault can be restricted
 * with a resource-based policy.
 *
 * ### Creating a Vault
 * **Example:** Basic Vault
 * ```typescript
 * import * as Backup from "@alchemy.run/aws/Backup";
 *
 * const vault = yield* Backup.BackupVault("AppBackups");
 * ```
 *
 * **Example:** Vault with a Customer-Managed KMS Key
 * ```typescript
 * const vault = yield* Backup.BackupVault("EncryptedBackups", {
 *   encryptionKeyArn: key.keyArn,
 * });
 * ```
 *
 * ### Vault Access Policy
 * **Example:** Deny deletion of recovery points
 * ```typescript
 * const vault = yield* Backup.BackupVault("LockedBackups", {
 *   accessPolicy: {
 *     Version: "2012-10-17",
 *     Statement: [
 *       {
 *         Effect: "Deny",
 *         Principal: { AWS: "*" },
 *         Action: ["backup:DeleteRecoveryPoint"],
 *         Resource: "*",
 *       },
 *     ],
 *   },
 * });
 * ```
 *
 * @resource
 */
export const BackupVault = Resource<BackupVault>("AWS.Backup.BackupVault");

const toPolicyString = (policy: PolicyDocument | string | undefined): string | undefined =>
  policy === undefined
    ? undefined
    : typeof policy === "string"
      ? policy
      : stringifyPolicyDocument(policy);

export const BackupVaultProvider = () =>
  Provider.effect(
    BackupVault,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: BackupVaultProps) {
        return props.backupVaultName ?? (yield* createPhysicalName({ id, maxLength: 50 }));
      });

      return BackupVault.Provider.of({
        stables: ["backupVaultName", "backupVaultArn"],
        list: () =>
          backup.listBackupVaults.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk)
                .flatMap((page) => page.BackupVaultList ?? [])
                .filter(
                  (v) =>
                    v.BackupVaultName !== undefined &&
                    v.BackupVaultArn !== undefined &&
                    // Service-managed vaults (e.g. EFS automatic backups'
                    // `aws/efs/automatic-backup-vault`) reject
                    // DeleteBackupVault with a 403 even when empty (verified
                    // live) — keep them out of enumeration for account-wide
                    // teardown (nuke).
                    !v.BackupVaultName.startsWith("aws/"),
                )
                .map((v) => ({
                  backupVaultName: v.BackupVaultName!,
                  backupVaultArn: v.BackupVaultArn!,
                })),
            ),
          ),
        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.backupVaultName ?? (yield* createName(id, olds ?? {}));
          // AWS Backup returns AccessDeniedException (with an empty message),
          // not ResourceNotFoundException, when a vault does not exist — it
          // hides existence behind a 403. Treat both as "absent".
          const found = yield* backup
            .describeBackupVault({ BackupVaultName: name })
            .pipe(
              Effect.catchTag(
                ["ResourceNotFoundException", "AccessDeniedException"],
                () => Effect.undefined,
              ),
            );
          if (!found?.BackupVaultArn) return undefined;
          const attrs = {
            backupVaultName: name,
            backupVaultArn: found.BackupVaultArn,
          };
          const tags = yield* backup.listTags({ ResourceArn: found.BackupVaultArn }).pipe(
            Effect.map((r) => r.Tags ?? {}),
            Effect.orElseSucceed(() => ({}) as Record<string, string | undefined>),
          );
          return (yield* hasAlchemyTags(id, tags as Record<string, string>))
            ? attrs
            : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ id, news = {}, olds = {} }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createName(id, olds);
          const newName = yield* createName(id, news);
          if (oldName !== newName) return { action: "replace" } as const;
          if ((olds.encryptionKeyArn ?? "") !== (news.encryptionKeyArn ?? "")) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news = {}, output, session }) {
          const name = output?.backupVaultName ?? (yield* createName(id, news));
          const internalTags = yield* createInternalTags(id);

          // OBSERVE — cloud state is authoritative; output is only an id cache.
          // A missing vault surfaces as AccessDeniedException (see read()).
          let live = yield* backup
            .describeBackupVault({ BackupVaultName: name })
            .pipe(
              Effect.catchTag(
                ["ResourceNotFoundException", "AccessDeniedException"],
                () => Effect.undefined,
              ),
            );

          // ENSURE — create if missing; tolerate an AlreadyExists race.
          if (!live?.BackupVaultArn) {
            live = yield* backup
              .createBackupVault({
                BackupVaultName: name,
                EncryptionKeyArn: news.encryptionKeyArn,
                BackupVaultTags: { ...internalTags, ...news.tags },
              })
              .pipe(
                Effect.catchTag("AlreadyExistsException", () =>
                  backup.describeBackupVault({ BackupVaultName: name }),
                ),
              );
          }
          const backupVaultArn = live.BackupVaultArn!;

          // SYNC access policy — diff observed against desired, comparing
          // canonicalized documents so a re-deploy of an equivalent policy
          // (key order, whitespace) is a no-op.
          const desiredPolicy = toPolicyString(news.accessPolicy);
          const currentPolicy = yield* backup
            .getBackupVaultAccessPolicy({ BackupVaultName: name })
            .pipe(
              Effect.map((r) => (r.Policy ? r.Policy : undefined)),
              Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
            );
          const policyDrifted =
            desiredPolicy === undefined || currentPolicy === undefined
              ? desiredPolicy !== currentPolicy
              : normalizePolicyDocument(currentPolicy) !== normalizePolicyDocument(desiredPolicy);
          if (policyDrifted) {
            if (desiredPolicy === undefined) {
              yield* backup
                .deleteBackupVaultAccessPolicy({ BackupVaultName: name })
                .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
            } else {
              yield* backup.putBackupVaultAccessPolicy({
                BackupVaultName: name,
                Policy: desiredPolicy,
              });
            }
          }

          // SYNC tags — diff against observed cloud tags.
          const currentTags = yield* backup.listTags({ ResourceArn: backupVaultArn }).pipe(
            Effect.map((r) => r.Tags ?? {}),
            Effect.orElseSucceed(() => ({}) as Record<string, string | undefined>),
          );
          const { upsert, removed } = diffTags(currentTags as Record<string, string>, {
            ...news.tags,
            ...internalTags,
          });
          if (upsert.length > 0) {
            yield* backup.tagResource({
              ResourceArn: backupVaultArn,
              Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
            });
          }
          if (removed.length > 0) {
            yield* backup.untagResource({
              ResourceArn: backupVaultArn,
              TagKeyList: removed,
            });
          }

          yield* session.note(backupVaultArn);
          return { backupVaultName: name, backupVaultArn };
        }),
        delete: Effect.fn(function* ({ output }) {
          // A vault can only be deleted when it is empty — delete any
          // remaining recovery points first. Each delete tolerates the point
          // already being gone or being in a state that can't be deleted
          // right now (EXPIRED/continuous points settle on their own).
          const recoveryPoints = yield* backup.listRecoveryPointsByBackupVault
            .pages({ BackupVaultName: output.backupVaultName })
            .pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.RecoveryPoints ?? [])),
              Effect.catchTag(["ResourceNotFoundException", "AccessDeniedException"], () =>
                Effect.succeed([]),
              ),
            );
          yield* Effect.forEach(
            recoveryPoints,
            (rp) =>
              rp.RecoveryPointArn
                ? backup
                    .deleteRecoveryPoint({
                      BackupVaultName: output.backupVaultName,
                      RecoveryPointArn: rp.RecoveryPointArn,
                    })
                    .pipe(
                      Effect.catchTag(
                        ["ResourceNotFoundException", "InvalidResourceStateException"],
                        () => Effect.void,
                      ),
                    )
                : Effect.void,
            { discard: true },
          );
          // A missing vault deletes as AccessDeniedException, not
          // ResourceNotFoundException — both mean "already gone" here.
          yield* backup.deleteBackupVault({ BackupVaultName: output.backupVaultName }).pipe(
            Effect.catchTag(
              ["ResourceNotFoundException", "AccessDeniedException"],
              () => Effect.void,
            ),
            // Recovery-point deletion is asynchronous; the vault delete
            // rejects with InvalidRequestException until the vault empties.
            Effect.retry({
              while: (e) => e._tag === "InvalidRequestException",
              schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(10)]),
            }),
          );
        }),
      });
    }),
  );