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

import * as athena from "@distilled.cloud/aws/athena";
import * as logs from "@distilled.cloud/aws/cloudwatch-logs";
import * as datazone from "@distilled.cloud/aws/datazone";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
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 { deleteGlueDatabase } from "../Glue/internal.ts";
import { unredact } from "./internal.ts";

/**
 * A name/value provisioning parameter passed to the environment's blueprint.
 */
export interface EnvironmentUserParameter {
  /** The parameter name. */
  name?: string;
  /** The parameter value. */
  value?: string;
}

export interface EnvironmentProps {
  /**
   * The identifier of the {@link Domain} the environment lives in. Accepts a
   * domain's `domainId` output. Changing it triggers a replacement.
   */
  domainId: string;
  /**
   * The identifier of the {@link Project} that owns the environment. Accepts
   * a project's `projectId` output. Changing it triggers a replacement.
   */
  projectId: string;
  /**
   * Name of the environment. If omitted, a deterministic physical name is
   * generated from the app, stage, and logical ID. The name is mutable — it
   * converges via `UpdateEnvironment` without replacement.
   */
  name?: string;
  /**
   * A description of the environment.
   */
  description?: string;
  /**
   * The identifier of the environment profile to create the environment
   * from (V1 domains). Changing it triggers a replacement.
   */
  environmentProfileId?: string;
  /**
   * The identifier of the environment blueprint to create the environment
   * from directly (profile-less flows). Changing it triggers a replacement.
   */
  environmentBlueprintId?: string;
  /**
   * The AWS account to provision the environment in. Defaults to the
   * domain's account. Changing it triggers a replacement.
   */
  environmentAccountId?: string;
  /**
   * The region to provision the environment in. Changing it triggers a
   * replacement.
   */
  environmentAccountRegion?: string;
  /**
   * Blueprint provisioning parameters (e.g. the Glue database name for
   * `DefaultDataLake`).
   */
  userParameters?: EnvironmentUserParameter[];
  /**
   * Glossary term identifiers to attach to the environment.
   */
  glossaryTerms?: string[];
}

export interface Environment extends Resource<
  "AWS.DataZone.Environment",
  EnvironmentProps,
  {
    /** The unique identifier of the environment. */
    environmentId: string;
    /** The identifier of the domain the environment lives in. */
    domainId: string;
    /** The identifier of the owning project. */
    projectId: string;
    /** The name of the environment. */
    name: string;
    /** The status of the environment (`ACTIVE` once deployed). */
    status: string | undefined;
    /** The provider of the environment (e.g. `Amazon DataZone`). */
    provider: string;
    /** The AWS account the environment is provisioned in. */
    awsAccountId: string | undefined;
    /** The region the environment is provisioned in. */
    awsAccountRegion: string | undefined;
    /** The identifier of the environment profile the environment came from. */
    environmentProfileId: string | undefined;
    /** The identifier of the blueprint the environment came from. */
    environmentBlueprintId: string | undefined;
  }
> {}

/**
 * An Amazon DataZone environment — the provisioned collection of AWS
 * resources (Glue databases, IAM roles, Athena workgroups, ...) a project
 * works with, deployed from an environment blueprint via CloudFormation.
 *
 * Environment deployment is asynchronous (minutes — DataZone drives a
 * CloudFormation stack) and is polled to `ACTIVE` with a bounded wait. The
 * environment's blueprint must be configured in the domain first (see
 * {@link EnvironmentBlueprintConfiguration}).
 *
 * ### Creating Environments
 * **Example:** Environment from a Profile (V1 Domains)
 * ```typescript
 * import * as DataZone from "@alchemy.run/aws/DataZone";
 *
 * const env = yield* DataZone.Environment("datalake-env", {
 *   domainId: domain.domainId,
 *   projectId: project.projectId,
 *   environmentProfileId: profileId,
 * });
 * ```
 *
 * **Example:** Environment with Provisioning Parameters
 * ```typescript
 * const env = yield* DataZone.Environment("datalake-env", {
 *   domainId: domain.domainId,
 *   projectId: project.projectId,
 *   environmentProfileId: profileId,
 *   description: "Analytics data lake environment",
 *   userParameters: [
 *     { name: "glueDbName", value: "analytics_db" },
 *   ],
 * });
 * ```
 *
 * @resource
 */
export const Environment = Resource<Environment>("AWS.DataZone.Environment");

/** The environment deployment settled in a failed state. */
export class EnvironmentDeploymentFailed extends Data.TaggedError(
  "AWS.DataZone.EnvironmentDeploymentFailed",
)<{
  readonly environmentId: string;
  readonly status: string;
  readonly reason: string | undefined;
}> {
  override get message() {
    return `DataZone environment ${this.environmentId} ${this.status}${this.reason ? `: ${this.reason}` : ""}`;
  }
}

/** Environment status values indicating an in-flight transition to wait out. */
const ENVIRONMENT_TRANSIENT = new Set(["CREATING", "UPDATING", "DELETING"]);

/** Environment status values indicating a failed deployment. */
const ENVIRONMENT_FAILED = new Set(["CREATE_FAILED", "UPDATE_FAILED", "VALIDATION_FAILED"]);

export const EnvironmentProvider = () =>
  Provider.effect(
    Environment,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: Pick<EnvironmentProps, "name">) {
        return props.name ?? (yield* createPhysicalName({ id, maxLength: 64 }));
      });

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

      const findByName = Effect.fn(function* (domainId: string, projectId: string, name: string) {
        const found = yield* datazone
          .listEnvironments({
            domainIdentifier: domainId,
            projectIdentifier: projectId,
            name,
          })
          .pipe(
            Effect.catchTags({
              ResourceNotFoundException: () => Effect.undefined,
              AccessDeniedException: () => Effect.undefined,
            }),
          );
        const summary = (found?.items ?? []).find(
          (s) => unredact(s.name) === name && s.status !== "DELETING",
        );
        return summary?.id;
      });

      // Poll the environment to a settled (non-transient) status. Deployment
      // drives a CloudFormation stack — bounded at ~5 minutes.
      const waitForSettled = Effect.fn(function* (domainId: string, environmentId: string) {
        return yield* getEnvironmentOrUndefined(domainId, environmentId).pipe(
          Effect.repeat({
            schedule: Schedule.fixed("5 seconds"),
            until: (env) =>
              env === undefined ||
              env.status === undefined ||
              !ENVIRONMENT_TRANSIENT.has(env.status),
            times: 60,
          }),
        );
      });

      // Poll the environment until it no longer exists — teardown drives a
      // CloudFormation stack delete, bounded at ~5 minutes.
      const waitForGone = Effect.fn(function* (domainId: string, environmentId: string) {
        yield* getEnvironmentOrUndefined(domainId, environmentId).pipe(
          Effect.repeat({
            schedule: Schedule.fixed("5 seconds"),
            until: (env) => env === undefined || env.status === "DELETED",
            times: 60,
          }),
        );
      });

      // DataZone's data-lake blueprint stack retains its Glue databases,
      // Athena workgroup, and log group (CloudFormation DELETE_SKIPPED), so
      // deleting the environment leaks them. Read their names from the
      // environment's provisioned resources and delete them once it is gone.
      const deleteRetainedResources = Effect.fn(function* (
        resources: ReadonlyArray<datazone.Resource>,
      ) {
        const valueOf = (name: string) => resources.find((r) => r.name === name)?.value;
        for (const name of ["glueProducerDBName", "glueConsumerDBName"]) {
          const database = valueOf(name);
          if (database) yield* deleteGlueDatabase(database, undefined);
        }
        const workGroup = valueOf("athenaWorkGroupName");
        if (workGroup) {
          yield* athena.deleteWorkGroup({ WorkGroup: workGroup, RecursiveDeleteOption: true });
        }
        // arn:aws:logs:{region}:{account}:log-group:{name}:*
        const logGroup = valueOf("logGroupArn")?.split(":")[6];
        if (logGroup) {
          yield* logs
            .deleteLogGroup({ logGroupName: logGroup })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }
      });

      const failIfDeploymentFailed = Effect.fn(function* (
        env: datazone.GetEnvironmentOutput,
        environmentId: string,
      ) {
        if (env.status !== undefined && ENVIRONMENT_FAILED.has(env.status)) {
          return yield* new EnvironmentDeploymentFailed({
            environmentId,
            status: env.status,
            reason: env.lastDeployment?.failureReason?.message,
          });
        }
        return env;
      });

      const toAttributes = (env: datazone.GetEnvironmentOutput, environmentId: string) => ({
        environmentId,
        domainId: env.domainId,
        projectId: env.projectId,
        name: unredact(env.name),
        status: env.status,
        provider: env.provider,
        awsAccountId: env.awsAccountId,
        awsAccountRegion: env.awsAccountRegion,
        environmentProfileId: env.environmentProfileId,
        environmentBlueprintId: env.environmentBlueprintId,
      });

      return Environment.Provider.of({
        stables: ["environmentId", "domainId", "projectId", "awsAccountId", "awsAccountRegion"],

        // Environments are keyed by their parent domain + project — there is
        // no account-level enumeration without those identifiers.
        list: () => Effect.succeed([]),

        read: Effect.fn(function* ({ id, olds, output }) {
          const domainId = output?.domainId ?? olds?.domainId;
          const projectId = output?.projectId ?? olds?.projectId;
          if (domainId === undefined || projectId === undefined) {
            return undefined;
          }
          const environmentId =
            output?.environmentId ??
            (yield* findByName(domainId, projectId, yield* createName(id, olds ?? {})));
          if (environmentId === undefined) return undefined;
          const env = yield* getEnvironmentOrUndefined(domainId, environmentId);
          if (env === undefined || env.status === "DELETING" || env.status === "DELETED") {
            return undefined;
          }
          // Environments have no tags — ownership is tracked purely by
          // identity.
          return toAttributes(env, environmentId);
        }),

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (olds === undefined) return undefined;
          if (
            olds.domainId !== news.domainId ||
            olds.projectId !== news.projectId ||
            olds.environmentProfileId !== news.environmentProfileId ||
            olds.environmentBlueprintId !== news.environmentBlueprintId ||
            olds.environmentAccountId !== news.environmentAccountId ||
            olds.environmentAccountRegion !== news.environmentAccountRegion
          ) {
            return { action: "replace" } as const;
          }
          // name, description, and glossaryTerms converge via
          // updateEnvironment.
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const domainId = news.domainId;
          const projectId = news.projectId;
          const name = yield* createName(id, news);

          // 1. OBSERVE — cloud state is authoritative; output is only an id
          //    cache. Fall back to a name lookup after state loss.
          let environmentId = output?.environmentId;
          let env = environmentId
            ? yield* getEnvironmentOrUndefined(domainId, environmentId)
            : undefined;
          if (env === undefined) {
            environmentId = yield* findByName(domainId, projectId, name);
            if (environmentId !== undefined) {
              env = yield* getEnvironmentOrUndefined(domainId, environmentId);
            }
          }

          if (env === undefined) {
            // 2. ENSURE — create and wait out the CloudFormation deployment.
            const created = yield* datazone.createEnvironment({
              domainIdentifier: domainId,
              projectIdentifier: projectId,
              name,
              description: news.description,
              environmentProfileIdentifier: news.environmentProfileId,
              environmentBlueprintIdentifier: news.environmentBlueprintId,
              environmentAccountIdentifier: news.environmentAccountId,
              environmentAccountRegion: news.environmentAccountRegion,
              userParameters: news.userParameters,
              glossaryTerms: news.glossaryTerms,
            });
            environmentId = created.id ?? (yield* findByName(domainId, projectId, name));
            if (environmentId === undefined) {
              return yield* new EnvironmentDeploymentFailed({
                environmentId: "",
                status: "UNKNOWN",
                reason: `createEnvironment for ${name} returned no id`,
              });
            }
            env = yield* waitForSettled(domainId, environmentId);
            if (env === undefined) {
              return yield* new EnvironmentDeploymentFailed({
                environmentId,
                status: "DELETED",
                reason: "environment disappeared during deployment",
              });
            }
            env = yield* failIfDeploymentFailed(env, environmentId);
          } else {
            // 3. SYNC — wait out any in-flight transition, then converge the
            //    mutable aspects by diffing OBSERVED state against desired.
            env = (yield* waitForSettled(domainId, environmentId!)) ?? env;
            const drifted =
              unredact(env.name) !== name ||
              (env.description === undefined ? undefined : unredact(env.description)) !==
                (news.description ?? undefined);
            if (drifted) {
              yield* datazone.updateEnvironment({
                domainIdentifier: domainId,
                identifier: environmentId!,
                name,
                description: news.description,
                glossaryTerms: news.glossaryTerms,
              });
              env = (yield* waitForSettled(domainId, environmentId!)) ?? env;
              env = yield* failIfDeploymentFailed(env, environmentId!);
            }
          }

          yield* session.note(environmentId!);
          return toAttributes(env, environmentId!);
        }),

        delete: Effect.fn(function* ({ output }) {
          // wait out any in-flight transition first — deleting a CREATING
          // environment is rejected with a conflict.
          const env = yield* waitForSettled(output.domainId, output.environmentId);
          yield* datazone
            .deleteEnvironment({
              domainIdentifier: output.domainId,
              identifier: output.environmentId,
            })
            .pipe(
              Effect.catchTags({
                ResourceNotFoundException: () => Effect.void,
                // deleting an environment whose domain is already gone surfaces
                // as AccessDenied — auth is checked before existence.
                AccessDeniedException: () => Effect.void,
              }),
            );
          yield* waitForGone(output.domainId, output.environmentId);
          yield* deleteRetainedResources(env?.provisionedResources ?? []);
        }),
      });
    }),
  );