sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ ControlTower/ LandingZone.ts

import * as controltower from "@distilled.cloud/aws/controltower";
import { Unowned } from "alchemy/AdoptPolicy";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { canonicalJson, observeControlTowerTags, syncControlTowerTags } from "./internal.ts";

export interface LandingZoneProps {
  /**
   * The landing zone version, e.g. `"3.3"`. Updating the version upgrades
   * the landing zone in place (an asynchronous operation that can take an
   * hour or more).
   */
  version: string;
  /**
   * The landing zone manifest JSON document — the full configuration of
   * the landing zone (governed regions, organization structure, logging
   * and access-management settings). See the AWS Control Tower User Guide
   * for the manifest schema.
   */
  manifest: Record<string, unknown>;
  /**
   * Remediation types enabled for the landing zone, e.g.
   * `["INHERITANCE_DRIFT"]`.
   */
  remediationTypes?: string[];
  /**
   * Tags to apply to the landing zone. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface LandingZone extends Resource<
  "AWS.ControlTower.LandingZone",
  LandingZoneProps,
  {
    /**
     * The unique identifier of the landing zone (its ARN).
     */
    landingZoneIdentifier: string;
    /**
     * The ARN of the landing zone.
     */
    landingZoneArn: string;
    /**
     * The deployed landing zone version.
     */
    version: string;
    /**
     * The landing zone deployment status (`ACTIVE`, `PROCESSING`,
     * `FAILED`).
     */
    status: string | undefined;
    /**
     * The most recent landing zone version available for upgrade.
     */
    latestAvailableVersion: string | undefined;
    /**
     * The landing zone drift status (`IN_SYNC` or `DRIFTED`).
     */
    driftStatus: string | undefined;
  },
  never,
  Providers
> {}

/**
 * An AWS Control Tower landing zone — the org-wide multi-account
 * environment (organization structure, governed regions, centralized
 * logging, and access management) that Control Tower governs.
 *
 * A landing zone is a singleton per AWS Organization and can only be
 * managed from the Organizations management account. Creating, updating,
 * and decommissioning a landing zone are asynchronous operations that can
 * take an hour or more.
 * ### Creating a Landing Zone
 * **Example:** Landing Zone from a manifest
 * ```typescript
 * import * as ControlTower from "@alchemy.run/aws/ControlTower";
 *
 * const landingZone = yield* ControlTower.LandingZone("LandingZone", {
 *   version: "3.3",
 *   manifest: {
 *     governedRegions: ["us-east-1", "us-west-2"],
 *     organizationStructure: {
 *       security: { name: "Security" },
 *       sandbox: { name: "Sandbox" },
 *     },
 *     centralizedLogging: {
 *       accountId: "111122223333",
 *       configurations: {
 *         loggingBucket: { retentionDays: 365 },
 *         accessLoggingBucket: { retentionDays: 365 },
 *       },
 *       enabled: true,
 *     },
 *     securityRoles: { accountId: "444455556666" },
 *     accessManagement: { enabled: true },
 *   },
 * });
 * ```
 *
 * ### Upgrading
 * **Example:** Upgrade the landing zone version
 * ```typescript
 * const landingZone = yield* ControlTower.LandingZone("LandingZone", {
 *   version: "3.3", // bump to upgrade in place
 *   manifest,
 * });
 * ```
 *
 * @resource
 */
export const LandingZone = Resource<LandingZone>("AWS.ControlTower.LandingZone");

/**
 * An asynchronous landing zone operation (CREATE / UPDATE / DELETE /
 * RESET) converged to the terminal `FAILED` status.
 */
export class LandingZoneOperationFailed extends Data.TaggedError("LandingZoneOperationFailed")<{
  readonly operationIdentifier: string;
  readonly status: string;
  readonly statusMessage: string | undefined;
}> {}

/**
 * Internal signal that a landing zone operation is still `IN_PROGRESS`,
 * consumed by {@link waitForLandingZoneOperation}'s bounded schedule.
 */
class LandingZoneOperationPending extends Data.TaggedError("LandingZoneOperationPending")<{
  readonly operationIdentifier: string;
  readonly status: string | undefined;
}> {}

// Explicitly-typed retry wrapper — an inline `Effect.retry` in provider
// lifecycle code leaks `Retry.Return`'s conditional type into declaration
// emit and widens the provider layer to `unknown` for every consumer of
// `AWS.providers()`.
const retryWhileLandingZoneOperationPending = <A, E extends { readonly _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "LandingZoneOperationPending",
    // Landing zone operations routinely take ~60 minutes; poll every 30s
    // up to 90 minutes (bounded).
    schedule: Schedule.max([Schedule.spaced("30 seconds"), Schedule.recurs(180)]),
  });

const waitForLandingZoneOperation = (operationIdentifier: string) =>
  retryWhileLandingZoneOperationPending(
    Effect.gen(function* () {
      const { operationDetails } = yield* controltower.getLandingZoneOperation({
        operationIdentifier,
      });
      if (operationDetails.status === "SUCCEEDED") {
        return;
      }
      if (operationDetails.status === "FAILED") {
        return yield* new LandingZoneOperationFailed({
          operationIdentifier,
          status: operationDetails.status,
          statusMessage: operationDetails.statusMessage,
        });
      }
      return yield* new LandingZoneOperationPending({
        operationIdentifier,
        status: operationDetails.status,
      });
    }),
  );

// A landing zone is a singleton per organization — `listLandingZones`
// returns at most one ARN.
const findLandingZoneArn = controltower.listLandingZones.pages({}).pipe(
  Stream.runCollect,
  Effect.map((chunk) =>
    Array.from(chunk)
      .flatMap((page) => page.landingZones)
      .map((zone) => zone.arn)
      .find((arn): arn is string => arn !== undefined),
  ),
);

const readLandingZone = (landingZoneIdentifier: string) =>
  controltower.getLandingZone({ landingZoneIdentifier }).pipe(
    Effect.map((r) => r.landingZone),
    Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
  );

const toAttributes = (
  arn: string,
  detail: controltower.LandingZoneDetail,
): LandingZone["Attributes"] => ({
  landingZoneIdentifier: arn,
  landingZoneArn: arn,
  version: detail.version,
  status: detail.status,
  latestAvailableVersion: detail.latestAvailableVersion,
  driftStatus: detail.driftStatus?.status,
});

export const LandingZoneProvider = () =>
  Provider.effect(
    LandingZone,
    Effect.gen(function* () {
      return LandingZone.Provider.of({
        stables: ["landingZoneIdentifier", "landingZoneArn"],
        // Decommissioning a landing zone dismantles org-wide governance
        // (an irreversible, ~1 hour operation) — never do it from `nuke`.
        nuke: { skip: true },
        list: () =>
          Effect.gen(function* () {
            const arn = yield* findLandingZoneArn;
            if (arn === undefined) return [];
            const detail = yield* readLandingZone(arn);
            if (detail === undefined) return [];
            return [toAttributes(arn, detail)];
          }),
        read: Effect.fn(function* ({ id, output }) {
          const arn = output?.landingZoneArn ?? (yield* findLandingZoneArn);
          if (arn === undefined) return undefined;
          const detail = yield* readLandingZone(arn);
          if (detail === undefined) return undefined;
          const attrs = toAttributes(arn, detail);
          const tags = yield* observeControlTowerTags(arn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          // 1. Observe — the landing zone is an org singleton; enumerate
          //    rather than trusting a cached identifier.
          let arn = output?.landingZoneArn ?? (yield* findLandingZoneArn);
          let detail = arn === undefined ? undefined : yield* readLandingZone(arn);

          // 2. Ensure — create if missing and wait for the asynchronous
          //    operation to converge.
          if (detail === undefined) {
            const internalTags = yield* createInternalTags(id);
            const created = yield* controltower.createLandingZone({
              version: news.version,
              manifest: news.manifest,
              remediationTypes: news.remediationTypes,
              tags: { ...news.tags, ...internalTags },
            });
            arn = created.arn;
            yield* session.note(`landing zone operation ${created.operationIdentifier}`);
            yield* waitForLandingZoneOperation(created.operationIdentifier);
            detail = yield* readLandingZone(arn);
          } else {
            // 3. Sync — version / manifest / remediation types are updated
            //    in place; diff observed cloud state against desired and
            //    skip the (very slow) update API on a no-op.
            const versionChanged = detail.version !== news.version;
            const manifestChanged =
              canonicalJson(detail.manifest ?? {}) !== canonicalJson(news.manifest);
            const remediationChanged =
              news.remediationTypes !== undefined &&
              canonicalJson([...(detail.remediationTypes ?? [])].sort()) !==
                canonicalJson([...news.remediationTypes].sort());
            if (versionChanged || manifestChanged || remediationChanged) {
              const updated = yield* controltower.updateLandingZone({
                landingZoneIdentifier: arn!,
                version: news.version,
                manifest: news.manifest,
                remediationTypes: news.remediationTypes,
              });
              yield* session.note(`landing zone operation ${updated.operationIdentifier}`);
              yield* waitForLandingZoneOperation(updated.operationIdentifier);
              detail = yield* readLandingZone(arn!);
            }
          }

          // 3b. Sync tags against observed cloud tags.
          yield* syncControlTowerTags(arn!, id, news.tags);

          // 4. Return fresh attributes.
          return detail === undefined
            ? {
                landingZoneIdentifier: arn!,
                landingZoneArn: arn!,
                version: news.version,
                status: undefined,
                latestAvailableVersion: undefined,
                driftStatus: undefined,
              }
            : toAttributes(arn!, detail);
        }),
        delete: Effect.fn(function* ({ output, session }) {
          const result = yield* controltower
            .deleteLandingZone({
              landingZoneIdentifier: output.landingZoneArn,
            })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
          if (result !== undefined) {
            yield* session.note(`landing zone operation ${result.operationIdentifier}`);
            yield* waitForLandingZoneOperation(result.operationIdentifier);
          }
        }),
      });
    }),
  );