sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ DataZone/ EnvironmentBlueprintConfiguration.ts

import * as datazone from "@distilled.cloud/aws/datazone";
import * as lf from "@distilled.cloud/aws/lakeformation";
import { Region } from "@distilled.cloud/aws/Region";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
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 { RegionID } from "../Region.ts";

/**
 * Lake Formation provisioning configuration for a blueprint.
 */
export interface BlueprintLakeFormationConfiguration {
  /** The ARN of the role used to register S3 locations with Lake Formation. */
  locationRegistrationRole?: string;
  /** S3 locations to exclude from Lake Formation registration. */
  locationRegistrationExcludeS3Locations?: string[];
}

/**
 * A provisioning configuration attached to a blueprint configuration.
 */
export interface BlueprintProvisioningConfiguration {
  /** Lake Formation settings applied when the blueprint provisions environments. */
  lakeFormationConfiguration: BlueprintLakeFormationConfiguration;
}

export interface EnvironmentBlueprintConfigurationProps {
  /**
   * The identifier of the {@link Domain} to configure the blueprint in.
   * Accepts a domain's `domainId` output. Changing it triggers a
   * replacement.
   */
  domainId: string;
  /**
   * The managed environment blueprint to configure — a blueprint name
   * (e.g. `"DefaultDataLake"`, `"DefaultDataWarehouse"`) or a raw blueprint
   * identifier. Changing it triggers a replacement.
   */
  environmentBlueprint: string;
  /**
   * The regions in which environments may be created from this blueprint.
   */
  enabledRegions: string[];
  /**
   * The ARN of the role DataZone uses to provision environment resources
   * (CloudFormation stacks) from this blueprint.
   */
  provisioningRoleArn?: string;
  /**
   * The ARN of the role DataZone uses to manage access grants to
   * environment resources (e.g. Lake Formation permissions).
   */
  manageAccessRoleArn?: string;
  /**
   * The ARN of a permission boundary policy to apply to environment roles
   * created from this blueprint.
   */
  environmentRolePermissionBoundary?: string;
  /**
   * Region-scoped provisioning parameters, keyed by region then parameter
   * name (e.g. `{ "us-west-2": { S3Location: "s3://bucket" } }`).
   */
  regionalParameters?: Record<string, Record<string, string>>;
  /**
   * Global provisioning parameters applied in every enabled region.
   */
  globalParameters?: Record<string, string>;
  /**
   * Additional provisioning configurations (e.g. Lake Formation location
   * registration).
   */
  provisioningConfigurations?: BlueprintProvisioningConfiguration[];
}

export interface EnvironmentBlueprintConfiguration extends Resource<
  "AWS.DataZone.EnvironmentBlueprintConfiguration",
  EnvironmentBlueprintConfigurationProps,
  {
    /** The identifier of the domain the configuration lives in. */
    domainId: string;
    /** The identifier of the configured environment blueprint. */
    environmentBlueprintId: string;
    /** The name of the configured environment blueprint. */
    environmentBlueprintName: string;
    /** The regions in which the blueprint is enabled. */
    enabledRegions: string[];
    /** The ARN of the provisioning role. */
    provisioningRoleArn: string | undefined;
    /** The ARN of the manage-access role. */
    manageAccessRoleArn: string | undefined;
    /**
     * Lake Formation administrator entries this configuration is responsible
     * for: the provisioning and manage-access roles, per enabled region,
     * wherever the role was not already an administrator. DataZone makes both
     * roles administrators when it deploys an environment; delete removes
     * these entries again.
     */
    lakeFormationAdmins?: LakeFormationAdminEntry[];
  }
> {}

/**
 * The account/domain configuration of an Amazon DataZone environment
 * blueprint — enables a managed blueprint (like `DefaultDataLake`) in
 * specific regions with the IAM roles DataZone should provision with.
 *
 * The blueprint itself is an AWS-managed definition; this resource owns only
 * its per-domain configuration (a `PUT`-style singleton keyed by domain +
 * blueprint).
 *
 * ### Configuring Blueprints
 * **Example:** Enable the DefaultDataLake Blueprint
 * ```typescript
 * import * as DataZone from "@alchemy.run/aws/DataZone";
 *
 * const config = yield* DataZone.EnvironmentBlueprintConfiguration(
 *   "datalake",
 *   {
 *     domainId: domain.domainId,
 *     environmentBlueprint: "DefaultDataLake",
 *     enabledRegions: ["us-west-2"],
 *     provisioningRoleArn: provisioningRole.roleArn,
 *     manageAccessRoleArn: manageAccessRole.roleArn,
 *     regionalParameters: {
 *       "us-west-2": { S3Location: "s3://my-datalake-bucket" },
 *     },
 *   },
 * );
 * ```
 *
 * **Example:** Blueprint with Lake Formation Provisioning
 * ```typescript
 * const config = yield* DataZone.EnvironmentBlueprintConfiguration(
 *   "datalake",
 *   {
 *     domainId: domain.domainId,
 *     environmentBlueprint: "DefaultDataLake",
 *     enabledRegions: ["us-west-2"],
 *     provisioningRoleArn: provisioningRole.roleArn,
 *     provisioningConfigurations: [
 *       {
 *         lakeFormationConfiguration: {
 *           locationRegistrationRole: registrationRole.roleArn,
 *         },
 *       },
 *     ],
 *   },
 * );
 * ```
 *
 * @resource
 */
export const EnvironmentBlueprintConfiguration = Resource<EnvironmentBlueprintConfiguration>(
  "AWS.DataZone.EnvironmentBlueprintConfiguration",
);

/** No blueprint with the requested name or id exists in the domain. */
export class EnvironmentBlueprintNotFound extends Data.TaggedError(
  "AWS.DataZone.EnvironmentBlueprintNotFound",
)<{
  readonly domainId: string;
  readonly environmentBlueprint: string;
}> {}

/**
 * Freshly created IAM roles are eventually consistent; the PUT can
 * transiently reject a provisioning/manage-access role it cannot yet assume.
 * Wrapped in an explicitly-typed helper so the `Effect.retry` conditional
 * return type does not leak into declaration emit (see PATTERNS §7).
 */
const retryWhileRoleAssumeFails = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) =>
      (e._tag === "ValidationException" || e._tag === "AccessDeniedException") &&
      "message" in e &&
      typeof e.message === "string" &&
      (e.message.toLowerCase().includes("role") || e.message.toLowerCase().includes("assume")),
    schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(10)]),
  });

/** A Lake Formation administrator entry in one region's catalog. */
export interface LakeFormationAdminEntry {
  /** The administrator principal (an IAM role ARN). */
  principal: string;
  /** The region whose Data Catalog lists the administrator. */
  region: string;
}

/** Run a Lake Formation call against a specific region's catalog. */
const inRegion = (region: string) =>
  Effect.provideService(Region, Effect.succeed(region as RegionID));

const isLakeFormationAdmin = Effect.fn(function* (roleArn: string, region: string) {
  const { DataLakeSettings: settings } = yield* lf.getDataLakeSettings({}).pipe(inRegion(region));
  return (settings?.DataLakeAdmins ?? []).some((p) => p.DataLakePrincipalIdentifier === roleArn);
});

/**
 * Remove `roleArn` from the region's Lake Formation administrators. Left
 * behind, the entry dangles once the role is deleted and Lake Formation
 * rejects every later administrator write in the region as an invalid
 * principal.
 */
const removeLakeFormationAdmin = Effect.fn(function* (roleArn: string, region: string) {
  const { DataLakeSettings: settings = {} } = yield* lf
    .getDataLakeSettings({})
    .pipe(inRegion(region));
  const admins = settings.DataLakeAdmins ?? [];
  if (!admins.some((p) => p.DataLakePrincipalIdentifier === roleArn)) return;
  yield* lf
    .putDataLakeSettings({
      DataLakeSettings: {
        ...settings,
        DataLakeAdmins: admins.filter((p) => p.DataLakePrincipalIdentifier !== roleArn),
      },
    })
    .pipe(inRegion(region));
});

export const EnvironmentBlueprintConfigurationProvider = () =>
  Provider.effect(
    EnvironmentBlueprintConfiguration,
    Effect.gen(function* () {
      // Resolve a blueprint name-or-id to its { id, name } within the domain.
      const resolveBlueprint = Effect.fn(function* (domainId: string, nameOrId: string) {
        const match = yield* datazone.listEnvironmentBlueprints
          .items({
            domainIdentifier: domainId,
            managed: true,
          })
          .pipe(
            Stream.filter((b) => b.name === nameOrId || b.id === nameOrId),
            Stream.runHead,
            Effect.map((head) => (head._tag === "Some" ? head.value : undefined)),
          );
        if (match === undefined) {
          return yield* new EnvironmentBlueprintNotFound({
            domainId,
            environmentBlueprint: nameOrId,
          });
        }
        return { id: match.id, name: match.name };
      });

      // A deleted configuration — or one inside a deleted domain — is
      // reported as AccessDeniedException, NOT ResourceNotFoundException:
      // DataZone evaluates domain-scoped authorization before existence.
      // Both mean "absent".
      const getConfigurationOrUndefined = Effect.fn(function* (
        domainId: string,
        blueprintId: string,
      ) {
        return yield* datazone
          .getEnvironmentBlueprintConfiguration({
            domainIdentifier: domainId,
            environmentBlueprintIdentifier: blueprintId,
          })
          .pipe(
            Effect.catchTags({
              ResourceNotFoundException: () => Effect.undefined,
              AccessDeniedException: () => Effect.undefined,
            }),
          );
      });

      return EnvironmentBlueprintConfiguration.Provider.of({
        stables: ["domainId", "environmentBlueprintId"],

        // Configurations are keyed by their parent domain — there is no
        // account-level enumeration without a domain identifier.
        list: () => Effect.succeed([]),

        read: Effect.fn(function* ({ olds, output }) {
          const domainId = output?.domainId ?? olds?.domainId;
          if (domainId === undefined) return undefined;
          const blueprint = output?.environmentBlueprintId
            ? {
                id: output.environmentBlueprintId,
                name: output.environmentBlueprintName,
              }
            : olds?.environmentBlueprint
              ? yield* resolveBlueprint(domainId, olds.environmentBlueprint).pipe(
                  Effect.catchTags({
                    "AWS.DataZone.EnvironmentBlueprintNotFound": () => Effect.undefined,
                    // the domain itself may already be gone (reported as
                    // NotFound or as AccessDenied — auth precedes existence)
                    ResourceNotFoundException: () => Effect.undefined,
                    AccessDeniedException: () => Effect.undefined,
                  }),
                )
              : undefined;
          if (blueprint === undefined) return undefined;
          const config = yield* getConfigurationOrUndefined(domainId, blueprint.id);
          // An un-configured blueprint returns an empty configuration shell —
          // treat "no enabled regions and no roles" as absent.
          if (
            config === undefined ||
            ((config.enabledRegions ?? []).length === 0 &&
              config.provisioningRoleArn === undefined &&
              config.manageAccessRoleArn === undefined)
          ) {
            return undefined;
          }
          // Blueprint configurations have no tags — ownership is tracked
          // purely by identity.
          return {
            domainId: config.domainId,
            environmentBlueprintId: config.environmentBlueprintId,
            environmentBlueprintName: blueprint.name,
            enabledRegions: [...(config.enabledRegions ?? [])],
            provisioningRoleArn: config.provisioningRoleArn,
            manageAccessRoleArn: config.manageAccessRoleArn,
            lakeFormationAdmins: output?.lakeFormationAdmins,
          };
        }),

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (olds === undefined) return undefined;
          if (olds.domainId !== news.domainId) {
            return { action: "replace" } as const;
          }
          if (olds.environmentBlueprint !== news.environmentBlueprint) {
            return { action: "replace" } as const;
          }
          // regions, roles, and parameters converge via the idempotent PUT.
        }),

        reconcile: Effect.fn(function* ({ news, output, session }) {
          const domainId = news.domainId;
          const blueprint = output?.environmentBlueprintId
            ? {
                id: output.environmentBlueprintId,
                name: output.environmentBlueprintName,
              }
            : yield* resolveBlueprint(domainId, news.environmentBlueprint);

          // The (role, region) administrator entries DataZone may add for
          // this configuration.
          const roles = [news.provisioningRoleArn, news.manageAccessRoleArn].filter(
            (role): role is string => role !== undefined,
          );
          const candidates = roles.flatMap((principal) =>
            news.enabledRegions.map((region) => ({ principal, region })),
          );
          const same = (a: LakeFormationAdminEntry) => (b: LakeFormationAdminEntry) =>
            a.principal === b.principal && a.region === b.region;
          const previous = output?.lakeFormationAdmins ?? [];

          // Release entries for roles or regions no longer configured.
          for (const entry of previous.filter((e) => !candidates.some(same(e)))) {
            yield* removeLakeFormationAdmin(entry.principal, entry.region);
          }

          // Observe, before DataZone can add it, where each role is not yet an
          // administrator — those entries are ours to remove.
          const lakeFormationAdmins = yield* Effect.filter(candidates, (entry) =>
            previous.some(same(entry))
              ? Effect.succeed(true)
              : isLakeFormationAdmin(entry.principal, entry.region).pipe(
                  Effect.map((admin) => !admin),
                ),
          );

          // PutEnvironmentBlueprintConfiguration is a true upsert — one call
          // converges greenfield, update, and adoption alike.
          const config = yield* retryWhileRoleAssumeFails(
            datazone.putEnvironmentBlueprintConfiguration({
              domainIdentifier: domainId,
              environmentBlueprintIdentifier: blueprint.id,
              enabledRegions: news.enabledRegions,
              provisioningRoleArn: news.provisioningRoleArn,
              manageAccessRoleArn: news.manageAccessRoleArn,
              environmentRolePermissionBoundary: news.environmentRolePermissionBoundary,
              regionalParameters: news.regionalParameters,
              globalParameters: news.globalParameters,
              provisioningConfigurations: news.provisioningConfigurations,
            }),
          );

          yield* session.note(`${blueprint.name} (${blueprint.id})`);
          return {
            domainId: config.domainId,
            environmentBlueprintId: config.environmentBlueprintId,
            environmentBlueprintName: blueprint.name,
            enabledRegions: [...(config.enabledRegions ?? news.enabledRegions)],
            provisioningRoleArn: config.provisioningRoleArn,
            manageAccessRoleArn: config.manageAccessRoleArn,
            lakeFormationAdmins,
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* datazone
            .deleteEnvironmentBlueprintConfiguration({
              domainIdentifier: output.domainId,
              environmentBlueprintIdentifier: output.environmentBlueprintId,
            })
            .pipe(
              // Environments created from the configuration may still be
              // deleting; DataZone refuses until they are gone.
              Effect.retry({
                while: (e) => e._tag === "EnvironmentBlueprintConfigurationInUse",
                schedule: Schedule.spaced("5 seconds"),
                times: 24,
              }),
              Effect.catchTags({
                ResourceNotFoundException: () => Effect.void,
                // deleting a configuration whose domain is already gone
                // surfaces as AccessDenied — auth is checked before existence.
                AccessDeniedException: () => Effect.void,
              }),
            );
          for (const entry of output.lakeFormationAdmins ?? []) {
            yield* removeLakeFormationAdmin(entry.principal, entry.region);
          }
        }),
      });
    }),
  );