sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ EMR/ Studio.ts

import * as emr from "@distilled.cloud/aws/emr";
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 } 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";

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

export interface StudioProps {
  /**
   * Descriptive name of the Studio. If omitted, a deterministic physical
   * name is generated. Updateable in place.
   */
  studioName?: string;
  /**
   * Authentication mode — `IAM` or `SSO` (IAM Identity Center). Changing the
   * mode replaces the Studio.
   * @default "IAM"
   */
  authMode?: "IAM" | "SSO";
  /**
   * VPC the Studio workspaces and notebooks connect to. Changing the VPC
   * replaces the Studio.
   */
  vpcId: string;
  /**
   * Subnets of the VPC the Studio can use (at most 5). Updateable in place
   * (subnets can be added, not removed).
   */
  subnetIds: string[];
  /**
   * ARN of the IAM service role the Studio assumes, trusting
   * `elasticmapreduce.amazonaws.com`. Changing the role replaces the Studio.
   */
  serviceRole: string;
  /**
   * ARN of the IAM user role Studio users assume (`SSO` auth mode only).
   * Changing the role replaces the Studio.
   */
  userRole?: string;
  /**
   * Security group for the Studio workspace (must allow outbound TCP 18888
   * to the engine security group and outbound HTTPS 443). Changing it
   * replaces the Studio.
   */
  workspaceSecurityGroupId: string;
  /**
   * Security group for the Studio engine (must allow inbound TCP 18888 from
   * the workspace security group). Changing it replaces the Studio.
   */
  engineSecurityGroupId: string;
  /**
   * S3 location that backs up Studio workspaces and notebooks, e.g.
   * `"s3://my-bucket/studio/"`. Updateable in place.
   */
  defaultS3Location: string;
  /**
   * Description of the Studio. Updateable in place.
   */
  description?: string;
  /**
   * Authentication endpoint of your identity provider (IAM federation only).
   * Changing it replaces the Studio.
   */
  idpAuthUrl?: string;
  /**
   * Name the IdP uses for its RelayState parameter (IAM federation only).
   * Changing it replaces the Studio.
   */
  idpRelayStateParameterName?: string;
  /**
   * Whether trusted identity propagation is enabled for the Studio.
   * Changing it replaces the Studio.
   */
  trustedIdentityPropagationEnabled?: boolean;
  /**
   * Whether IAM Identity Center user assignment is `REQUIRED` or `OPTIONAL`
   * (SSO auth mode only). Changing it replaces the Studio.
   */
  idcUserAssignment?: "REQUIRED" | "OPTIONAL";
  /**
   * ARN of the IAM Identity Center instance (SSO auth mode only). Changing
   * it replaces the Studio.
   */
  idcInstanceArn?: string;
  /**
   * KMS key ARN used to encrypt Studio workspace and notebook files.
   * Changing it replaces the Studio.
   */
  encryptionKeyArn?: string;
  /**
   * User-defined tags for the Studio.
   */
  tags?: Record<string, string>;
}

export interface Studio extends Resource<
  "AWS.EMR.Studio",
  StudioProps,
  {
    /** The ID of the Studio (e.g. `es-0123456789ABCDEFGHIJKLMNOP`). */
    studioId: string;
    /** The ARN of the Studio. */
    studioArn: string;
    /** The name of the Studio. */
    studioName: string;
    /** The unique access URL of the Studio. */
    url: string | undefined;
    /** The tags applied to the Studio. */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An Amazon EMR Studio — a web-based IDE for notebooks and interactive
 * workloads that attaches to EMR clusters.
 *
 * A Studio itself is free; you pay for the clusters it attaches to. Each
 * Studio needs a VPC with subnets, a workspace and an engine security group,
 * an IAM service role, and an S3 backup location.
 * ### Creating a Studio
 * **Example:** IAM-Authenticated Studio
 * ```typescript
 * const studio = yield* Studio("Notebooks", {
 *   authMode: "IAM",
 *   vpcId: vpc.vpcId,
 *   subnetIds: [subnetA.subnetId, subnetB.subnetId],
 *   serviceRole: serviceRole.roleArn,
 *   workspaceSecurityGroupId: workspaceSg.groupId,
 *   engineSecurityGroupId: engineSg.groupId,
 *   defaultS3Location: Output.interpolate`s3://${bucket.bucketName}/studio/`,
 * });
 * ```
 *
 * **Example:** Studio with Description and Tags
 * ```typescript
 * const studio = yield* Studio("Notebooks", {
 *   authMode: "IAM",
 *   vpcId: vpc.vpcId,
 *   subnetIds: [subnetA.subnetId],
 *   serviceRole: serviceRole.roleArn,
 *   workspaceSecurityGroupId: workspaceSg.groupId,
 *   engineSecurityGroupId: engineSg.groupId,
 *   defaultS3Location: Output.interpolate`s3://${bucket.bucketName}/studio/`,
 *   description: "Data-science notebooks",
 *   tags: { team: "analytics" },
 * });
 * ```
 *
 * @resource
 */
export const Studio = Resource<Studio>("AWS.EMR.Studio");

const toTagRecord = (
  tags: ReadonlyArray<{ Key?: string; Value?: string }> | undefined,
): Record<string, string> =>
  Object.fromEntries(
    (tags ?? [])
      .filter(
        (tag): tag is { Key: string; Value: string } =>
          typeof tag.Key === "string" && typeof tag.Value === "string",
      )
      .map((tag) => [tag.Key, tag.Value]),
  );

const sameStringSet = (
  a: readonly string[] | undefined,
  b: readonly string[] | undefined,
): boolean => {
  const left = [...(a ?? [])].sort();
  const right = [...(b ?? [])].sort();
  return left.length === right.length && left.every((v, i) => v === right[i]);
};

/**
 * A freshly created IAM service role (or its inline policy) takes a few
 * seconds to propagate (IAM eventual consistency); CreateStudio validates
 * both assumability and S3-location access at create time and surfaces that
 * window as the typed StudioServiceRoleNotAssumable /
 * StudioServiceRoleMissingS3Access tags. Bounded retry (~40s max) — a
 * genuinely misconfigured role still fails, just slower.
 *
 * NOTE: keep this helper at module scope with an EXPLICIT return annotation —
 * an inlined `Effect.retry` in provider lifecycle code leaves `Retry.Return`'s
 * conditional type unresolved in the provider's inferred layer type, which
 * TypeScript's declaration emit widens to an `unknown` R.
 */
const retryWhileRolePropagates = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) =>
      e._tag === "StudioServiceRoleNotAssumable" || e._tag === "StudioServiceRoleMissingS3Access",
    schedule: Schedule.max([Schedule.fixed("4 seconds"), Schedule.recurs(10)]),
  });

export const StudioProvider = () =>
  Provider.effect(
    Studio,
    Effect.gen(function* () {
      const toName = (id: string, props: Partial<StudioProps>) =>
        props.studioName
          ? Effect.succeed(props.studioName)
          : createPhysicalName({ id, maxLength: 80 });

      const readStudio = Effect.fn(function* (studioId: string) {
        const response = yield* emr
          .describeStudio({ StudioId: studioId })
          .pipe(Effect.catchTag("StudioNotFound", () => Effect.undefined));
        return response?.Studio;
      });

      // Studio names are not unique; the deterministic physical name is.
      // Used when state was lost and we only know the derived name.
      const findStudioByName = Effect.fn(function* (name: string) {
        const matches = yield* emr.listStudios.items({}).pipe(
          Stream.filter((summary) => summary.Name === name),
          Stream.take(1),
          Stream.runCollect,
        );
        const summary = Array.from(matches)[0];
        return summary?.StudioId ? yield* readStudio(summary.StudioId) : undefined;
      });

      const toAttrs = Effect.fn(function* (studio: emr.Studio) {
        if (!studio.StudioId || !studio.StudioArn || !studio.Name) {
          return yield* new StudioUnexpectedResponse({
            message: `EMR Studio '${studio.StudioId}' is missing its ARN`,
          });
        }
        return {
          studioId: studio.StudioId,
          studioArn: studio.StudioArn,
          studioName: studio.Name,
          url: studio.Url,
          tags: toTagRecord(studio.Tags),
        };
      });

      return {
        stables: ["studioId", "studioArn"],

        diff: Effect.fn(function* ({ olds, news }) {
          if (!isResolved(news)) return undefined;
          const n = news;
          const o = olds;
          if (n === undefined || o === undefined) return undefined;
          // Create-only properties force a replacement. (Name, description,
          // subnets, and the S3 location update in place.)
          if ((n.authMode ?? "IAM") !== (o.authMode ?? "IAM")) {
            return { action: "replace" } as const;
          }
          if (n.vpcId !== o.vpcId) {
            return { action: "replace" } as const;
          }
          if (n.serviceRole !== o.serviceRole) {
            return { action: "replace" } as const;
          }
          if ((n.userRole ?? undefined) !== (o.userRole ?? undefined)) {
            return { action: "replace" } as const;
          }
          if (n.workspaceSecurityGroupId !== o.workspaceSecurityGroupId) {
            return { action: "replace" } as const;
          }
          if (n.engineSecurityGroupId !== o.engineSecurityGroupId) {
            return { action: "replace" } as const;
          }
          if ((n.idpAuthUrl ?? undefined) !== (o.idpAuthUrl ?? undefined)) {
            return { action: "replace" } as const;
          }
          if (
            (n.idpRelayStateParameterName ?? undefined) !==
            (o.idpRelayStateParameterName ?? undefined)
          ) {
            return { action: "replace" } as const;
          }
          if (
            (n.trustedIdentityPropagationEnabled ?? undefined) !==
            (o.trustedIdentityPropagationEnabled ?? undefined)
          ) {
            return { action: "replace" } as const;
          }
          if ((n.idcUserAssignment ?? undefined) !== (o.idcUserAssignment ?? undefined)) {
            return { action: "replace" } as const;
          }
          if ((n.idcInstanceArn ?? undefined) !== (o.idcInstanceArn ?? undefined)) {
            return { action: "replace" } as const;
          }
          if ((n.encryptionKeyArn ?? undefined) !== (o.encryptionKeyArn ?? undefined)) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const studio = output?.studioId
            ? yield* readStudio(output.studioId)
            : yield* findStudioByName(yield* toName(id, olds ?? {}));
          if (!studio) return undefined;
          const attrs = yield* toAttrs(studio);
          return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const props = news!;
          const name = yield* toName(id, props);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...props.tags };

          // 1. Observe — cloud state is authoritative; output is only an id
          //    cache.
          let observed = output?.studioId
            ? yield* readStudio(output.studioId)
            : yield* findStudioByName(name);

          // 2. Ensure — create if missing. Create errors (invalid security
          //    groups, role, subnets) propagate directly.
          if (observed === undefined) {
            const created = yield* retryWhileRolePropagates(
              emr.createStudio({
                Name: name,
                AuthMode: props.authMode ?? "IAM",
                VpcId: props.vpcId,
                SubnetIds: props.subnetIds,
                ServiceRole: props.serviceRole,
                UserRole: props.userRole,
                WorkspaceSecurityGroupId: props.workspaceSecurityGroupId,
                EngineSecurityGroupId: props.engineSecurityGroupId,
                DefaultS3Location: props.defaultS3Location,
                Description: props.description,
                IdpAuthUrl: props.idpAuthUrl,
                IdpRelayStateParameterName: props.idpRelayStateParameterName,
                TrustedIdentityPropagationEnabled: props.trustedIdentityPropagationEnabled,
                IdcUserAssignment: props.idcUserAssignment,
                IdcInstanceArn: props.idcInstanceArn,
                EncryptionKeyArn: props.encryptionKeyArn,
                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              }),
            );
            if (!created.StudioId) {
              return yield* new StudioUnexpectedResponse({
                message: `CreateStudio for '${name}' returned no StudioId`,
              });
            }
            observed = yield* readStudio(created.StudioId);
            if (observed === undefined) {
              return yield* new StudioUnexpectedResponse({
                message: `EMR Studio '${created.StudioId}' not visible after create`,
              });
            }
          }
          const studioId = observed.StudioId!;

          // 3. Sync — compute the update delta from OBSERVED state.
          const update: emr.UpdateStudioInput = { StudioId: studioId };
          let mutated = false;
          if (observed.Name !== name) {
            update.Name = name;
            mutated = true;
          }
          if (props.description !== undefined && props.description !== observed.Description) {
            update.Description = props.description;
            mutated = true;
          }
          if (!sameStringSet(props.subnetIds, observed.SubnetIds)) {
            update.SubnetIds = props.subnetIds;
            mutated = true;
          }
          if (props.defaultS3Location !== observed.DefaultS3Location) {
            update.DefaultS3Location = props.defaultS3Location;
            mutated = true;
          }
          if (mutated) {
            yield* emr.updateStudio(update);
          }

          // 3b. Sync tags — diff against OBSERVED cloud tags.
          const observedTags = toTagRecord(observed.Tags);
          const { removed, upsert } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* emr.addTags({ ResourceId: studioId, Tags: upsert });
          }
          if (removed.length > 0) {
            yield* emr.removeTags({ ResourceId: studioId, TagKeys: removed });
          }

          // 4. Return fresh attributes.
          const final = yield* readStudio(studioId);
          yield* session.note(studioId);
          return yield* toAttrs(final ?? observed);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* emr
            .deleteStudio({ StudioId: output.studioId })
            .pipe(Effect.catchTag("StudioNotFound", () => Effect.void));
        }),

        list: () =>
          emr.listStudios.items({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((summary) => (summary.StudioId ? [summary.StudioId] : [])),
            ),
            Effect.flatMap(
              Effect.forEach((studioId) => readStudio(studioId), {
                concurrency: 4,
              }),
            ),
            Effect.map((studios) =>
              studios.filter((studio): studio is emr.Studio => studio !== undefined),
            ),
            Effect.flatMap(Effect.forEach((studio) => toAttrs(studio), { concurrency: 4 })),
          ),
      };
    }),
  );