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

import * as finspace from "@distilled.cloud/aws/finspace";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags, type Tags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import type { Providers } from "../Providers.ts";

export class EnvironmentUnexpectedResponse extends Data.TaggedError(
  "EnvironmentUnexpectedResponse",
)<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export type EnvironmentStatus = finspace.EnvironmentStatus;
export type FederationMode = finspace.FederationMode;
export type FederationParameters = finspace.FederationParameters;
export type SuperuserParameters = finspace.SuperuserParameters;

export interface EnvironmentProps {
  /**
   * Name of the FinSpace environment.
   * @default ${app}-${id}-${stage}-${suffix}
   */
  name?: string;
  /**
   * A description of the environment.
   */
  description?: string;
  /**
   * The KMS key id used to encrypt data in the environment. Changing it
   * replaces the environment.
   */
  kmsKeyId?: string;
  /**
   * Authentication mode for the environment — `FEDERATED` (SAML) or `LOCAL`.
   */
  federationMode?: FederationMode;
  /**
   * SAML federation configuration, required when `federationMode` is
   * `FEDERATED`.
   */
  federationParameters?: FederationParameters;
  /**
   * Configuration of the superuser created with the environment. Only used
   * at creation; changing it replaces the environment.
   */
  superuserParameters?: SuperuserParameters;
  /**
   * ARNs of the sample data bundles to install. Only used at creation;
   * changing it replaces the environment.
   */
  dataBundles?: string[];
  /**
   * Tags to associate with the environment.
   */
  tags?: Record<string, string>;
}

export interface Environment extends Resource<
  "AWS.FinSpace.Environment",
  EnvironmentProps,
  {
    /**
     * Service-assigned unique identifier of the environment.
     */
    environmentId: string;
    /**
     * ARN of the environment.
     */
    environmentArn: string;
    /**
     * The environment's name.
     */
    name: string;
    /**
     * Current lifecycle status of the environment.
     */
    status: EnvironmentStatus | undefined;
    /**
     * Sign-in URL for the web application of the environment.
     */
    environmentUrl: string | undefined;
    /**
     * URL of the integrated SageMaker Studio domain.
     */
    sageMakerStudioDomainUrl: string | undefined;
    /**
     * ID of the KMS key encrypting the environment.
     */
    kmsKeyId: string | undefined;
    /**
     * AWS account ID of the dedicated service account associated with the
     * environment.
     */
    dedicatedServiceAccountId: string | undefined;
    /**
     * Current tags reported for the environment.
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An Amazon FinSpace environment — a managed data management and analytics
 * workspace for the financial services industry.
 *
 * :::caution
 * FinSpace is closed to new customers and environment provisioning takes
 * ~20 minutes and bills while it exists. Live lifecycle tests are gated
 * behind `AWS_TEST_FINSPACE=1`.
 * :::
 * ### Creating Environments
 * **Example:** Basic Environment
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const env = yield* AWS.FinSpace.Environment("Analytics", {
 *   description: "research analytics environment",
 * });
 * ```
 *
 * **Example:** Federated Environment
 * ```typescript
 * const env = yield* AWS.FinSpace.Environment("Analytics", {
 *   federationMode: "FEDERATED",
 *   federationParameters: {
 *     samlMetadataURL: "https://idp.example.com/metadata.xml",
 *     federationProviderName: "idp.example.com",
 *     applicationCallBackURL: "https://example.com/callback",
 *   },
 * });
 * ```
 *
 * @resource
 */
export const Environment = Resource<Environment>("AWS.FinSpace.Environment");

const createEnvironmentName = (id: string, props: { name?: string | undefined }) =>
  props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 255 });

const fetchTags = Effect.fn(function* (arn: string) {
  const response = yield* finspace
    .listTagsForResource({ resourceArn: arn })
    .pipe(
      Effect.catchTag(
        ["ResourceNotFoundException", "InvalidRequestException"],
        () => Effect.undefined,
      ),
    );
  return Object.fromEntries(
    Object.entries(response?.tags ?? {}).flatMap(([key, value]) =>
      value === undefined ? [] : [[key, value] as const],
    ),
  );
});

const toAttributes = Effect.fn(function* (env: finspace.Environment, fallbackId: string) {
  const environmentId = env.environmentId ?? fallbackId;
  const environmentArn = env.environmentArn ?? "";
  const attrs: Environment["Attributes"] = {
    environmentId,
    environmentArn,
    name: env.name ?? "",
    status: env.status,
    environmentUrl: env.environmentUrl,
    sageMakerStudioDomainUrl: env.sageMakerStudioDomainUrl,
    kmsKeyId: env.kmsKeyId,
    dedicatedServiceAccountId: env.dedicatedServiceAccountId,
    tags: environmentArn ? yield* fetchTags(environmentArn) : {},
  };
  return attrs;
});

const isGone = (status: EnvironmentStatus | undefined) =>
  status === "DELETED" || status === "DELETING" || status === "DELETE_REQUESTED";

const readEnvironmentById = Effect.fn(function* (environmentId: string) {
  const response = yield* finspace
    .getEnvironment({ environmentId })
    .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
  const env = response?.environment;
  if (!env || isGone(env.status)) return undefined;
  return env;
});

// listEnvironments is not marked paginated in the Smithy model — paginate by
// hand, page-bounded, treating an absent/empty nextToken as terminal.
const listAllEnvironments = Effect.gen(function* () {
  const environments: finspace.Environment[] = [];
  let nextToken: string | undefined;
  for (let page = 0; page < 20; page++) {
    const response = yield* finspace.listEnvironments({ nextToken });
    environments.push(...(response.environments ?? []));
    if (!response.nextToken) break;
    nextToken = response.nextToken;
  }
  return environments;
});

const findEnvironmentByName = Effect.fn(function* (name: string) {
  const environments = yield* listAllEnvironments;
  return environments.find((env) => env.name === name && !isGone(env.status));
});

/**
 * An environment still transitioning toward the awaited status — retried by
 * the bounded schedule in {@link waitForEnvironmentStatus}.
 */
class EnvironmentNotReady extends Data.TaggedError("EnvironmentNotReady")<{
  readonly environmentId: string;
  readonly status: string | undefined;
}> {}

/**
 * An environment whose asynchronous provisioning converged to the terminal
 * `FAILED_CREATION` status.
 */
export class EnvironmentProvisioningFailed extends Data.TaggedError(
  "EnvironmentProvisioningFailed",
)<{
  readonly environmentId: 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 retryWhileNotReady = <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 === "EnvironmentNotReady",
    // Environment provisioning is slow (~20 min); poll every 20s up to ~40 min.
    schedule: Schedule.max([Schedule.spaced("20 seconds"), Schedule.recurs(120)]),
  });

const waitForEnvironmentStatus = (environmentId: string, target: "CREATED" | "DELETED") =>
  retryWhileNotReady(
    Effect.gen(function* () {
      const response = yield* finspace
        .getEnvironment({ environmentId })
        .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      const status = response?.environment?.status;
      if (target === "DELETED") {
        if (response === undefined || isGone(status)) return;
        return yield* new EnvironmentNotReady({ environmentId, status });
      }
      if (status === "CREATED") return;
      if (status === "FAILED_CREATION" || status === "SUSPENDED") {
        return yield* new EnvironmentProvisioningFailed({ environmentId, status });
      }
      return yield* new EnvironmentNotReady({ environmentId, status });
    }),
  );

export const EnvironmentProvider = () =>
  Provider.effect(
    Environment,
    Effect.gen(function* () {
      return {
        stables: ["environmentId", "environmentArn"],
        list: () =>
          Effect.gen(function* () {
            const environments = yield* listAllEnvironments;
            const hydrated = yield* Effect.forEach(
              environments.filter((env) => !isGone(env.status)),
              (env) => toAttributes(env, env.environmentId ?? ""),
              { concurrency: 5 },
            );
            return hydrated;
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const env = output?.environmentId
            ? yield* readEnvironmentById(output.environmentId)
            : yield* findEnvironmentByName(yield* createEnvironmentName(id, olds ?? {}));
          if (!env) return undefined;
          const attrs = yield* toAttributes(env, output?.environmentId ?? "");
          return (yield* hasAlchemyTags(id, attrs.tags as Tags)) ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return;
          if (olds === undefined) return;
          // KMS key, superuser and data bundles are fixed at creation.
          if (
            olds.kmsKeyId !== news.kmsKeyId ||
            JSON.stringify(olds.superuserParameters) !== JSON.stringify(news.superuserParameters) ||
            JSON.stringify(olds.dataBundles) !== JSON.stringify(news.dataBundles)
          ) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const props = news ?? {};
          const name = yield* createEnvironmentName(id, props);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...props.tags };

          // Observe — prefer the cached id; fall back to a name lookup so a
          // create whose state failed to persist is adopted, not duplicated.
          let env = output?.environmentId
            ? yield* readEnvironmentById(output.environmentId)
            : yield* findEnvironmentByName(name);

          // Ensure — create if missing, then wait for CREATED.
          if (env === undefined) {
            const created = yield* finspace.createEnvironment({
              name,
              description: props.description,
              kmsKeyId: props.kmsKeyId,
              federationMode: props.federationMode,
              federationParameters: props.federationParameters,
              superuserParameters: props.superuserParameters,
              dataBundles: props.dataBundles,
              tags: desiredTags,
            });
            if (!created.environmentId) {
              return yield* new EnvironmentUnexpectedResponse({
                message: `CreateEnvironment for '${name}' returned no id`,
              });
            }
            yield* session.note(
              `Creating FinSpace environment ${name} (${created.environmentId})...`,
            );
            yield* waitForEnvironmentStatus(created.environmentId, "CREATED");
            env = yield* readEnvironmentById(created.environmentId);
            if (env === undefined) {
              return yield* new EnvironmentUnexpectedResponse({
                message: `failed to read created environment ${name}`,
              });
            }
          }
          const environmentId = env.environmentId;
          if (environmentId === undefined) {
            return yield* new EnvironmentUnexpectedResponse({
              message: `environment '${name}' has no environmentId`,
            });
          }

          // Sync mutable settings — only call UpdateEnvironment on drift.
          const needsUpdate =
            name !== env.name ||
            (props.description !== undefined && props.description !== env.description) ||
            (props.federationMode !== undefined && props.federationMode !== env.federationMode);
          if (needsUpdate) {
            yield* finspace.updateEnvironment({
              environmentId,
              name,
              description: props.description,
              federationMode: props.federationMode,
              federationParameters: props.federationParameters,
            });
            yield* session.note(`Updated FinSpace environment ${name}`);
          }

          // Sync tags — diff against observed cloud tags.
          const attrs = yield* toAttributes(env, environmentId);
          if (attrs.environmentArn) {
            const { removed, upsert } = diffTags(attrs.tags, desiredTags);
            if (removed.length > 0) {
              yield* finspace.untagResource({
                resourceArn: attrs.environmentArn,
                tagKeys: removed,
              });
            }
            if (upsert.length > 0) {
              yield* finspace.tagResource({
                resourceArn: attrs.environmentArn,
                tags: Object.fromEntries(upsert.map(({ Key, Value }) => [Key, Value])),
              });
            }
          }

          yield* session.note(attrs.environmentArn);

          const final = yield* readEnvironmentById(environmentId);
          if (!final) {
            return yield* new EnvironmentUnexpectedResponse({
              message: `failed to read reconciled environment ${name}`,
            });
          }
          return yield* toAttributes(final, environmentId);
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* finspace
            .deleteEnvironment({ environmentId: output.environmentId })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
          // Deletion is irreversible once initiated; wait until the service
          // reports it gone (DELETE_REQUESTED/DELETING/DELETED or NotFound).
          yield* waitForEnvironmentStatus(output.environmentId, "DELETED");
        }),
      };
    }),
  );