sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Account/ Region.ts

import * as account from "@distilled.cloud/aws/account";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

/**
 * Opt-in status of a Region as reported by `account:GetRegionOptStatus`:
 * `ENABLED`, `ENABLING`, `DISABLING`, `DISABLED`, or `ENABLED_BY_DEFAULT`.
 */
export type RegionOptStatus = string;

const isEnabledStatus = (status: string | undefined): boolean =>
  status === "ENABLED" || status === "ENABLED_BY_DEFAULT";

const isTerminalStatus = (status: string | undefined): boolean =>
  status !== "ENABLING" && status !== "DISABLING";

export interface RegionProps {
  /**
   * Name of the Region to manage, e.g. `ap-east-1`. Changing the Region
   * replaces the resource.
   */
  regionName: string;
  /**
   * Whether the Region should be opted in (enabled) for the account. Regions
   * that are `ENABLED_BY_DEFAULT` cannot be disabled — attempting to disable
   * one fails with a `ValidationException`.
   */
  enabled: boolean;
  /**
   * Account ID to operate on. Only usable from an Organizations management or
   * delegated-admin account with trusted access enabled; omit to target the
   * calling account.
   */
  accountId?: string;
}

export interface Region extends Resource<
  "AWS.Account.Region",
  RegionProps,
  {
    /** Name of the Region, e.g. `ap-east-1`. */
    regionName: string;
    /** Whether the Region is currently enabled for the account. */
    enabled: boolean;
    /**
     * Observed opt-in status: `ENABLED`, `ENABLING`, `DISABLING`, `DISABLED`,
     * or `ENABLED_BY_DEFAULT`.
     */
    regionOptStatus: RegionOptStatus;
  },
  never,
  Providers
> {}

/**
 * The opt-in status of an AWS Region for an account. Opt-in Regions (e.g.
 * `ap-east-1`, `me-south-1`) are disabled by default and must be enabled
 * before use; this resource drives `account:EnableRegion` /
 * `account:DisableRegion` to converge the Region to the desired status.
 *
 * Enabling or disabling a Region is asynchronous and can take several
 * minutes; reconcile waits (bounded) for the transition to settle and records
 * the observed status either way. Disabling a Region removes all IAM access
 * to resources in it, so destroying this resource intentionally does NOT
 * disable the Region — it only stops managing it (set `enabled: false`
 * explicitly to opt out).
 *
 * ### Managing Region Opt-In
 * **Example:** Enable an Opt-In Region
 * ```typescript
 * const region = yield* Account.Region("HongKong", {
 *   regionName: "ap-east-1",
 *   enabled: true,
 * });
 * ```
 *
 * **Example:** Track a Default Region
 * ```typescript
 * const region = yield* Account.Region("UsEast1", {
 *   regionName: "us-east-1",
 *   enabled: true, // ENABLED_BY_DEFAULT — reconcile makes no API mutation
 * });
 * ```
 *
 * **Example:** Opt Out of a Region
 * ```typescript
 * const region = yield* Account.Region("HongKong", {
 *   regionName: "ap-east-1",
 *   enabled: false,
 * });
 * ```
 *
 * @resource
 */
export const Region = Resource<Region>("AWS.Account.Region");

export const RegionProvider = () =>
  Provider.effect(
    Region,
    Effect.gen(function* () {
      const observe = (regionName: string, accountId: string | undefined) =>
        account
          .getRegionOptStatus({ RegionName: regionName, AccountId: accountId })
          .pipe(Effect.map((r) => r.RegionOptStatus));

      // Region opt-in/out is asynchronous (typically a few minutes). Wait,
      // bounded, for an in-flight transition to settle; if it is still
      // transitioning after the budget, return the transitional status —
      // re-running reconcile converges.
      const settle = (regionName: string, accountId: string | undefined) =>
        observe(regionName, accountId).pipe(
          Effect.repeat({
            schedule: Schedule.spaced("10 seconds"),
            until: (status): boolean => isTerminalStatus(status),
            times: 24,
          }),
        );

      const toAttributes = (regionName: string, status: string | undefined) => ({
        regionName,
        enabled: isEnabledStatus(status),
        regionOptStatus: status ?? "DISABLED",
      });

      return {
        // Disabling a Region removes IAM access to everything in it — far too
        // destructive for an automatic nuke of an account-global setting.
        nuke: { skip: true },
        stables: [],
        // The Region name is the identity of this account-global slot, so a
        // different Region (or target account) replaces the resource.
        diff: Effect.fn(function* ({ olds, news }) {
          if (!isResolved(news)) return;
          if (
            (olds?.regionName ?? news.regionName) !== news.regionName ||
            (olds?.accountId ?? news.accountId) !== news.accountId
          ) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ olds, output }) {
          const regionName = output?.regionName ?? olds?.regionName;
          if (!regionName) return undefined;
          const status = yield* observe(regionName, olds?.accountId);
          return toAttributes(regionName, status);
        }),
        reconcile: Effect.fn(function* ({ news, session }) {
          let status = yield* settle(news.regionName, news.accountId);
          if (news.enabled && status === "DISABLED") {
            yield* account
              .enableRegion({
                RegionName: news.regionName,
                AccountId: news.accountId,
              })
              .pipe(
                // A concurrent transition already in flight — settle below
                // observes whatever it converges to.
                Effect.catchTag("ConflictException", () => Effect.void),
              );
            status = yield* settle(news.regionName, news.accountId);
          } else if (!news.enabled && isEnabledStatus(status)) {
            // Disabling an ENABLED_BY_DEFAULT Region is rejected by AWS with
            // a typed ValidationException — let it propagate.
            yield* account
              .disableRegion({
                RegionName: news.regionName,
                AccountId: news.accountId,
              })
              .pipe(Effect.catchTag("ConflictException", () => Effect.void));
            status = yield* settle(news.regionName, news.accountId);
          }
          yield* session.note(`${news.regionName}:${status ?? "UNKNOWN"}`);
          return toAttributes(news.regionName, status);
        }),
        // Enumerate the opt-in Regions (every status except
        // ENABLED_BY_DEFAULT — default Regions are not manageable slots).
        list: () =>
          account.listRegions
            .items({
              RegionOptStatusContains: ["ENABLED", "ENABLING", "DISABLING", "DISABLED"],
            })
            .pipe(
              Stream.runCollect,
              Effect.map((regions) =>
                Array.from(regions)
                  .filter((region) => region.RegionName != null)
                  .map((region) => toAttributes(region.RegionName!, region.RegionOptStatus)),
              ),
            ),
        // Destroy intentionally leaves the Region's opt-in status untouched:
        // disabling a Region removes IAM access to all resources in it. Users
        // opt out explicitly with `enabled: false` before removing the
        // resource if that is what they want.
        delete: Effect.fn(function* () {}),
      };
    }),
  );