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

import * as backup from "@distilled.cloud/aws/backup";
import { Unowned } from "alchemy/AdoptPolicy";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import { toWireDays, toWireMinutes } 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";

/**
 * Lifecycle policy controlling when a recovery point transitions to cold
 * storage and when it is deleted.
 */
export interface BackupRuleLifecycle {
  /**
   * Time after creation that a recovery point is moved to cold storage,
   * e.g. `"30 days"` (whole days on the wire). Must be at least 90 days
   * less than `deleteAfter`.
   */
  moveToColdStorageAfter?: Duration.Input;
  /**
   * Time after creation that a recovery point is deleted, e.g. `"365 days"`
   * (whole days on the wire).
   */
  deleteAfter?: Duration.Input;
  /**
   * Opt recovery points of supported resources into archive-tier storage.
   */
  optInToArchiveForSupportedResources?: boolean;
}

/**
 * A single scheduled backup rule within a backup plan.
 */
export interface BackupPlanRule {
  /**
   * Display name for the rule. Must be unique within the plan.
   */
  ruleName: string;
  /**
   * Name of the target backup vault where recovery points are stored.
   */
  targetBackupVaultName: string;
  /**
   * CRON expression (in UTC) specifying when the backup is taken, e.g.
   * `cron(0 5 ? * * *)`. Omit for continuous backup or on-demand plans.
   */
  scheduleExpression?: string;
  /**
   * Timezone the schedule expression is evaluated in.
   */
  scheduleExpressionTimezone?: string;
  /**
   * Time after the scheduled time within which a backup must start, or it
   * is canceled, e.g. `"1 hour"` (whole minutes on the wire).
   */
  startWindow?: Duration.Input;
  /**
   * Time within which a backup must complete, or it is canceled, e.g.
   * `"3 hours"` (whole minutes on the wire).
   */
  completionWindow?: Duration.Input;
  /**
   * Enables continuous backups (point-in-time restore) for supported
   * resources.
   */
  enableContinuousBackup?: boolean;
  /**
   * Lifecycle policy for the recovery points created by this rule.
   */
  lifecycle?: BackupRuleLifecycle;
  /**
   * Tags applied to recovery points created by this rule.
   */
  recoveryPointTags?: Record<string, string>;
}

export interface BackupPlanProps {
  /**
   * Display name of the backup plan. If omitted, a unique name is generated
   * from the app, stage, and logical ID.
   */
  backupPlanName?: string;
  /**
   * One or more scheduled backup rules that make up the plan.
   */
  rules: BackupPlanRule[];
  /**
   * Tags to apply to the backup plan. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface BackupPlan extends Resource<
  "AWS.Backup.BackupPlan",
  BackupPlanProps,
  {
    /**
     * Service-assigned unique ID of the backup plan.
     */
    backupPlanId: string;
    /**
     * ARN of the backup plan.
     */
    backupPlanArn: string;
    /**
     * Name of the backup plan.
     */
    backupPlanName: string;
    /**
     * Version ID of the plan; updated each time the plan document changes.
     */
    versionId: string;
  },
  never,
  Providers
> {}

/**
 * An AWS Backup plan — a policy expression that defines *when* and *how* you
 * want to back up your resources, composed of one or more scheduled rules
 * that each target a backup vault.
 *
 * Pair a plan with a {@link BackupSelection} to assign the AWS resources it
 * protects.
 *
 * ### Creating a Plan
 * **Example:** Daily backups retained for 30 days
 * ```typescript
 * import * as Backup from "@alchemy.run/aws/Backup";
 *
 * const vault = yield* Backup.BackupVault("AppBackups");
 *
 * const plan = yield* Backup.BackupPlan("DailyPlan", {
 *   rules: [
 *     {
 *       ruleName: "DailyBackups",
 *       targetBackupVaultName: vault.backupVaultName,
 *       scheduleExpression: "cron(0 5 ? * * *)",
 *       startWindow: "1 hour",
 *       completionWindow: "3 hours",
 *       lifecycle: { deleteAfter: "30 days" },
 *     },
 *   ],
 * });
 * ```
 *
 * **Example:** Move to cold storage then delete
 * ```typescript
 * const plan = yield* Backup.BackupPlan("ArchivePlan", {
 *   rules: [
 *     {
 *       ruleName: "MonthlyArchive",
 *       targetBackupVaultName: vault.backupVaultName,
 *       scheduleExpression: "cron(0 5 1 * ? *)",
 *       lifecycle: {
 *         moveToColdStorageAfter: "30 days",
 *         deleteAfter: "365 days",
 *       },
 *     },
 *   ],
 * });
 * ```
 *
 * @resource
 */
export const BackupPlan = Resource<BackupPlan>("AWS.Backup.BackupPlan");

const toRuleInput = (rule: BackupPlanRule): backup.BackupRuleInput => ({
  RuleName: rule.ruleName,
  TargetBackupVaultName: rule.targetBackupVaultName,
  ScheduleExpression: rule.scheduleExpression,
  ScheduleExpressionTimezone: rule.scheduleExpressionTimezone,
  StartWindowMinutes: toWireMinutes(rule.startWindow),
  CompletionWindowMinutes: toWireMinutes(rule.completionWindow),
  EnableContinuousBackup: rule.enableContinuousBackup,
  RecoveryPointTags: rule.recoveryPointTags,
  Lifecycle: rule.lifecycle
    ? {
        MoveToColdStorageAfterDays: toWireDays(rule.lifecycle.moveToColdStorageAfter),
        DeleteAfterDays: toWireDays(rule.lifecycle.deleteAfter),
        OptInToArchiveForSupportedResources: rule.lifecycle.optInToArchiveForSupportedResources,
      }
    : undefined,
});

export const BackupPlanProvider = () =>
  Provider.effect(
    BackupPlan,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (
        id: string,
        props: { backupPlanName?: string | undefined },
      ) {
        return props.backupPlanName ?? (yield* createPhysicalName({ id, maxLength: 50 }));
      });

      return BackupPlan.Provider.of({
        stables: ["backupPlanId", "backupPlanArn"],
        list: () =>
          backup.listBackupPlans.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk)
                .flatMap((page) => page.BackupPlansList ?? [])
                .filter(
                  (p) =>
                    p.BackupPlanId !== undefined &&
                    p.BackupPlanArn !== undefined &&
                    // Service-managed plans (e.g. EFS automatic backups'
                    // `aws/efs/automatic-backup-plan`) reject DeleteBackupPlan
                    // with AccessDenied (verified live) — keep them out of
                    // enumeration for account-wide teardown (nuke).
                    !(p.BackupPlanName ?? "").startsWith("aws/"),
                )
                .map((p) => ({
                  backupPlanId: p.BackupPlanId!,
                  backupPlanArn: p.BackupPlanArn!,
                  backupPlanName: p.BackupPlanName ?? "",
                  versionId: p.VersionId ?? "",
                })),
            ),
          ),
        read: Effect.fn(function* ({ id, output }) {
          if (!output?.backupPlanId) return undefined;
          const found = yield* backup
            .getBackupPlan({ BackupPlanId: output.backupPlanId })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
          if (!found?.BackupPlanArn) return undefined;
          const attrs = {
            backupPlanId: output.backupPlanId,
            backupPlanArn: found.BackupPlanArn,
            backupPlanName: found.BackupPlan?.BackupPlanName ?? output.backupPlanName,
            versionId: found.VersionId ?? output.versionId,
          };
          const tags = yield* backup.listTags({ ResourceArn: found.BackupPlanArn }).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);
        }),
        reconcile: Effect.fn(function* ({ id, news = {}, output, session }) {
          const name = output?.backupPlanName ?? (yield* createName(id, news));
          const internalTags = yield* createInternalTags(id);
          const backupPlanInput: backup.BackupPlanInput = {
            BackupPlanName: name,
            Rules: (news.rules ?? []).map(toRuleInput),
          };

          // OBSERVE — resolve the plan by its stable id when we have one.
          const live = output?.backupPlanId
            ? yield* backup
                .getBackupPlan({ BackupPlanId: output.backupPlanId })
                .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined))
            : undefined;

          let backupPlanId: string;
          let backupPlanArn: string;
          let versionId: string;

          if (!live?.BackupPlanArn) {
            // ENSURE — create.
            const created = yield* backup.createBackupPlan({
              BackupPlan: backupPlanInput,
              BackupPlanTags: { ...internalTags, ...news.tags },
            });
            backupPlanId = created.BackupPlanId!;
            backupPlanArn = created.BackupPlanArn!;
            versionId = created.VersionId ?? "";
          } else {
            // SYNC — a plan is a true upsert via updateBackupPlan; converge
            // rule/name changes unconditionally (the API is idempotent).
            backupPlanId = output!.backupPlanId!;
            const updated = yield* backup.updateBackupPlan({
              BackupPlanId: backupPlanId,
              BackupPlan: backupPlanInput,
            });
            backupPlanArn = updated.BackupPlanArn ?? live.BackupPlanArn;
            versionId = updated.VersionId ?? live.VersionId ?? "";
          }

          // SYNC tags — diff against observed cloud tags.
          const currentTags = yield* backup.listTags({ ResourceArn: backupPlanArn }).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: backupPlanArn,
              Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
            });
          }
          if (removed.length > 0) {
            yield* backup.untagResource({
              ResourceArn: backupPlanArn,
              TagKeyList: removed,
            });
          }

          yield* session.note(backupPlanId);
          return {
            backupPlanId,
            backupPlanArn,
            backupPlanName: name,
            versionId,
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          // A plan cannot be deleted while it still has resource selections
          // attached — delete those first (idempotent: a vanished selection
          // is already gone).
          const selections = yield* backup.listBackupSelections
            .pages({ BackupPlanId: output.backupPlanId })
            .pipe(
              Stream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((page) => page.BackupSelectionsList ?? []),
              ),
              Effect.catchTag("ResourceNotFoundException", () => Effect.succeed([])),
            );
          yield* Effect.forEach(
            selections,
            (s) =>
              s.SelectionId
                ? backup
                    .deleteBackupSelection({
                      BackupPlanId: output.backupPlanId,
                      SelectionId: s.SelectionId,
                    })
                    .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void))
                : Effect.void,
            { discard: true },
          );
          yield* backup.deleteBackupPlan({ BackupPlanId: output.backupPlanId }).pipe(
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
            // Selection deletion is eventually consistent; the plan delete
            // rejects with InvalidRequestException until it settles.
            Effect.retry({
              while: (e) => e._tag === "InvalidRequestException",
              schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(10)]),
            }),
          );
        }),
      });
    }),
  );