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

import * as controltower from "@distilled.cloud/aws/controltower";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
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 { canonicalParameters, observeControlTowerTags, syncControlTowerTags } from "./internal.ts";

export interface EnabledBaselineProps {
  /**
   * The ARN of the baseline to enable, e.g. the `AWSControlTowerBaseline`
   * ARN from `ListBaselines`. Changing the baseline replaces the
   * enablement.
   */
  baselineIdentifier: string;
  /**
   * The baseline version to enable, e.g. `"4.0"`. Updated in place via
   * `UpdateEnabledBaseline`.
   */
  baselineVersion: string;
  /**
   * The ARN of the target (organizational unit) the baseline is enabled
   * on. Changing the target replaces the enablement.
   */
  targetIdentifier: string;
  /**
   * Parameters applied to the baseline, as `{ key, value }` pairs — e.g.
   * `IdentityCenterEnabledBaselineArn` for the `AWSControlTowerBaseline`.
   * Updated in place via `UpdateEnabledBaseline`.
   */
  parameters?: { key: string; value: any }[];
  /**
   * Tags to apply to the enabled baseline. Merged with internal Alchemy
   * tags.
   */
  tags?: Record<string, string>;
}

export interface EnabledBaseline extends Resource<
  "AWS.ControlTower.EnabledBaseline",
  EnabledBaselineProps,
  {
    /**
     * The ARN of the enabled baseline (the `EnabledBaseline` resource).
     */
    enabledBaselineArn: string;
    /**
     * The ARN of the baseline that was enabled.
     */
    baselineIdentifier: string;
    /**
     * The ARN of the target organizational unit.
     */
    targetIdentifier: string;
    /**
     * The enabled baseline version.
     */
    baselineVersion: string | undefined;
  },
  never,
  Providers
> {}

/**
 * An AWS Control Tower baseline enabled on a target organizational unit.
 * Enabling a baseline (e.g. `AWSControlTowerBaseline`) starts an
 * asynchronous operation that registers the OU with Control Tower and
 * deploys the baseline's governance resources to its accounts.
 *
 * Requires an AWS Control Tower landing zone and can only be managed from
 * the Organizations management account.
 * ### Enabling Baselines
 * **Example:** Register an OU with Control Tower
 * ```typescript
 * import * as ControlTower from "@alchemy.run/aws/ControlTower";
 *
 * const enabled = yield* ControlTower.EnabledBaseline("WorkloadsBaseline", {
 *   baselineIdentifier:
 *     "arn:aws:controltower:us-west-2::baseline/17BSJV3IGJ2QSGA2",
 *   baselineVersion: "4.0",
 *   targetIdentifier: "arn:aws:organizations::111122223333:ou/o-example/ou-example",
 * });
 * ```
 *
 * **Example:** Baseline with Identity Center parameter
 * ```typescript
 * const enabled = yield* ControlTower.EnabledBaseline("WorkloadsBaseline", {
 *   baselineIdentifier: controlTowerBaselineArn,
 *   baselineVersion: "4.0",
 *   targetIdentifier: ouArn,
 *   parameters: [
 *     {
 *       key: "IdentityCenterEnabledBaselineArn",
 *       value: identityCenterEnabledBaselineArn,
 *     },
 *   ],
 * });
 * ```
 *
 * @resource
 */
export const EnabledBaseline = Resource<EnabledBaseline>("AWS.ControlTower.EnabledBaseline");

/**
 * An asynchronous baseline operation (ENABLE_BASELINE / DISABLE_BASELINE /
 * UPDATE_ENABLED_BASELINE) converged to the terminal `FAILED` status.
 */
export class BaselineOperationFailed extends Data.TaggedError("BaselineOperationFailed")<{
  readonly operationIdentifier: string;
  readonly status: string;
  readonly statusMessage: string | undefined;
}> {}

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

// Explicitly-typed retry wrappers — 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 retryWhileBaselineOperationPending = <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 === "BaselineOperationPending",
    // Baseline enablement provisions accounts and typically takes several
    // minutes; poll every 10s up to ~20 minutes.
    schedule: Schedule.max([Schedule.spaced("10 seconds"), Schedule.recurs(120)]),
  });

// Control Tower serializes baseline operations per target — a concurrent
// operation surfaces as a typed ConflictException. Retry through it on a
// bounded schedule.
const retryWhileBaselineConflict = <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 === "ConflictException",
    schedule: Schedule.max([Schedule.spaced("15 seconds"), Schedule.recurs(40)]),
  });

const waitForBaselineOperation = (operationIdentifier: string) =>
  retryWhileBaselineOperationPending(
    Effect.gen(function* () {
      const { baselineOperation } = yield* controltower.getBaselineOperation({
        operationIdentifier,
      });
      if (baselineOperation.status === "SUCCEEDED") {
        return;
      }
      if (baselineOperation.status === "FAILED") {
        return yield* new BaselineOperationFailed({
          operationIdentifier,
          status: baselineOperation.status,
          statusMessage: baselineOperation.statusMessage,
        });
      }
      return yield* new BaselineOperationPending({
        operationIdentifier,
        status: baselineOperation.status,
      });
    }),
  );

const readEnabledBaseline = (enabledBaselineArn: string) =>
  controltower.getEnabledBaseline({ enabledBaselineIdentifier: enabledBaselineArn }).pipe(
    Effect.map((r) => r.enabledBaselineDetails),
    Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
  );

// Find an enabled baseline by (baselineIdentifier, targetIdentifier) —
// covers the create-race and lost-output cases where we don't have the
// ARN cached.
const findEnabledBaselineArn = (baselineIdentifier: string, targetIdentifier: string) =>
  controltower.listEnabledBaselines
    .pages({
      filter: {
        baselineIdentifiers: [baselineIdentifier],
        targetIdentifiers: [targetIdentifier],
      },
    })
    .pipe(
      Stream.runCollect,
      Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.enabledBaselines)[0]?.arn),
    );

const toAttributes = (
  arn: string,
  details: controltower.EnabledBaselineDetails | undefined,
  fallback: {
    baselineIdentifier: string;
    targetIdentifier: string;
    baselineVersion?: string;
  },
): EnabledBaseline["Attributes"] => ({
  enabledBaselineArn: arn,
  baselineIdentifier: details?.baselineIdentifier ?? fallback.baselineIdentifier,
  targetIdentifier: details?.targetIdentifier ?? fallback.targetIdentifier,
  baselineVersion: details?.baselineVersion ?? fallback.baselineVersion,
});

export const EnabledBaselineProvider = () =>
  Provider.effect(
    EnabledBaseline,
    Effect.gen(function* () {
      return EnabledBaseline.Provider.of({
        stables: ["enabledBaselineArn", "baselineIdentifier", "targetIdentifier"],
        // Enumerate every enabled baseline in the ambient account (the
        // filter-less listing is supported on management accounts; on
        // non-Control-Tower accounts there is simply nothing to list).
        list: () =>
          controltower.listEnabledBaselines.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk)
                .flatMap((page) => page.enabledBaselines)
                .map((summary) => ({
                  enabledBaselineArn: summary.arn,
                  baselineIdentifier: summary.baselineIdentifier,
                  targetIdentifier: summary.targetIdentifier,
                  baselineVersion: summary.baselineVersion,
                })),
            ),
          ),
        read: Effect.fn(function* ({ id, olds, output }) {
          const arn =
            output?.enabledBaselineArn ??
            (olds !== undefined
              ? yield* findEnabledBaselineArn(olds.baselineIdentifier, olds.targetIdentifier)
              : undefined);
          if (arn === undefined) return undefined;
          const details = yield* readEnabledBaseline(arn);
          if (details === undefined) return undefined;
          const attrs = toAttributes(arn, details, {
            baselineIdentifier: olds?.baselineIdentifier ?? "",
            targetIdentifier: olds?.targetIdentifier ?? "",
          });
          const tags = yield* observeControlTowerTags(arn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (
            news.baselineIdentifier !== olds.baselineIdentifier ||
            news.targetIdentifier !== olds.targetIdentifier
          ) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          // 1. Observe — cloud state is authoritative; output is only an
          //    ARN cache.
          let arn = output?.enabledBaselineArn;
          let details = arn === undefined ? undefined : yield* readEnabledBaseline(arn);
          if (details === undefined) {
            arn = yield* findEnabledBaselineArn(news.baselineIdentifier, news.targetIdentifier);
            details = arn === undefined ? undefined : yield* readEnabledBaseline(arn);
          }

          // 2. Ensure — enable if missing and wait for the asynchronous
          //    operation to converge.
          if (details === undefined || arn === undefined) {
            const internalTags = yield* createInternalTags(id);
            const enabled = yield* retryWhileBaselineConflict(
              controltower.enableBaseline({
                baselineIdentifier: news.baselineIdentifier,
                baselineVersion: news.baselineVersion,
                targetIdentifier: news.targetIdentifier,
                parameters: news.parameters,
                tags: { ...news.tags, ...internalTags },
              }),
            );
            arn = enabled.arn;
            yield* session.note(`baseline operation ${enabled.operationIdentifier}`);
            yield* waitForBaselineOperation(enabled.operationIdentifier);
            details = yield* readEnabledBaseline(arn);
          } else {
            // 3. Sync — version and parameters are updated in place. Diff
            //    observed state against desired; skip the API on a no-op.
            //    Parameters cannot be cleared (only replaced), so an
            //    absent `parameters` prop leaves observed parameters
            //    alone.
            const versionChanged = details.baselineVersion !== news.baselineVersion;
            const parametersChanged =
              news.parameters !== undefined &&
              canonicalParameters(details.parameters) !== canonicalParameters(news.parameters);
            if (versionChanged || parametersChanged) {
              const updated = yield* retryWhileBaselineConflict(
                controltower.updateEnabledBaseline({
                  enabledBaselineIdentifier: arn,
                  baselineVersion: news.baselineVersion,
                  parameters: news.parameters,
                }),
              );
              yield* session.note(`baseline operation ${updated.operationIdentifier}`);
              yield* waitForBaselineOperation(updated.operationIdentifier);
              details = yield* readEnabledBaseline(arn);
            }
          }

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

          // 4. Return fresh attributes.
          return toAttributes(arn, details, {
            baselineIdentifier: news.baselineIdentifier,
            targetIdentifier: news.targetIdentifier,
            baselineVersion: news.baselineVersion,
          });
        }),
        delete: Effect.fn(function* ({ output, session }) {
          const result = yield* retryWhileBaselineConflict(
            controltower.disableBaseline({
              enabledBaselineIdentifier: output.enabledBaselineArn,
            }),
          ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
          if (result !== undefined) {
            yield* session.note(`baseline operation ${result.operationIdentifier}`);
            yield* waitForBaselineOperation(result.operationIdentifier);
          }
        }),
      });
    }),
  );