sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ IdentityCenter/ Instance.ts

import * as ssoAdmin from "@distilled.cloud/aws/sso-admin";
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 type { Providers } from "../Providers.ts";
import {
  listInstances,
  resolveInstance,
  retryIdentityCenter,
  toInstanceAttributes,
} from "./common.ts";

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

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

export interface InstanceProps {
  /**
   * Explicit instance ARN to adopt.
   */
  instanceArn?: string;
  /**
   * Friendly instance name.
   *
   * When `mode` is `"account"`, this name is passed to `CreateInstance`.
   * When `mode` is `"existing"`, it is used only for discovery.
   */
  name?: string;
  /**
   * How Alchemy should satisfy this resource.
   *
   * `existing` adopts a visible instance and fails if none is found.
   * `account` creates an account instance when no visible instance matches.
   *
   * Organization instances cannot currently be enabled via public API, so
   * organization-management-account deployments should use `existing`.
   *
   * @default "existing"
   */
  mode?: "existing" | "account";
}

export interface Instance extends Resource<
  "AWS.IdentityCenter.Instance",
  InstanceProps,
  {
    /** The ARN of the Identity Center instance. */
    instanceArn: string;
    /** The identity store backing the instance. */
    identityStoreId: string;
    /** The AWS account that owns the instance. */
    ownerAccountId: string | undefined;
    /** The friendly name of the instance, if set. */
    name: string | undefined;
    /** The current status of the instance (`ACTIVE`, ...). */
    status: string | undefined;
    /** Details when the instance is in a failed state. */
    statusReason: string | undefined;
    /** When the instance was created. */
    createdDate: Date | undefined;
    /** How the resource was satisfied: `existing` (adopted) or `account` (created). */
    mode: "existing" | "account";
  },
  never,
  Providers
> {}

/**
 * An IAM Identity Center instance visible to the current account.
 *
 * Use `mode: "existing"` to adopt a pre-enabled organization instance. Use
 * `mode: "account"` only for standalone or member-account account instances.
 * ### Discovering Existing Instances
 * **Example:** Adopt An Existing Instance
 * ```typescript
 * const instance = yield* Instance("IdentityCenter", {
 *   mode: "existing",
 * });
 * ```
 *
 * ### Creating Account Instances
 * **Example:** Create A Member Account Instance
 * ```typescript
 * const instance = yield* Instance("IdentityCenter", {
 *   mode: "account",
 *   name: "customer-a",
 * });
 * ```
 *
 * @resource
 */
export const Instance = Resource<Instance>("AWS.IdentityCenter.Instance");

export const InstanceProvider = () =>
  Provider.effect(
    Instance,
    Effect.gen(function* () {
      return {
        stables: ["instanceArn", "identityStoreId", "ownerAccountId", "mode"],
        // Enumerate every Identity Center instance visible to the calling
        // account (organization + account instances). `ListInstances` is
        // paginated and fully hydrates each `InstanceMetadata`, so no
        // per-item read is needed. Accounts with no SSO enabled return an
        // empty list (not an error). Each item is mapped to the exact `read`
        // Attributes shape; `mode` defaults to "existing" since enumeration
        // only observes pre-existing instances.
        list: () =>
          Effect.gen(function* () {
            const instances = yield* listInstances();
            return instances
              .filter(
                (
                  instance,
                ): instance is ssoAdmin.InstanceMetadata & {
                  InstanceArn: string;
                  IdentityStoreId: string;
                } => instance.InstanceArn != null && instance.IdentityStoreId != null,
              )
              .map((instance) => ({
                ...toInstanceAttributes(instance),
                mode: "existing" as const,
              }));
          }),
        diff: Effect.fn(function* ({ olds, news, output }) {
          if (!isResolved(news)) return;
          // `instanceArn` and `name` select which instance to adopt. Adding,
          // removing, or pinning one that matches the adopted instance is a
          // noop; only a selector pointing at a different instance replaces.
          // A replace in `account` mode deletes the old instance, so it must
          // never fire for the same instance.
          if (
            (news.instanceArn !== undefined &&
              news.instanceArn !== (output?.instanceArn ?? olds?.instanceArn)) ||
            (news.name !== undefined && news.name !== (output?.name ?? olds?.name)) ||
            (news.mode ?? "existing") !== (output?.mode ?? olds?.mode ?? "existing")
          ) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ olds, output }) {
          const mode = output?.mode ?? olds?.mode ?? "existing";
          const instance = yield* readInstance({
            instanceArn: output?.instanceArn ?? olds?.instanceArn,
            name: olds?.name,
          });
          return instance ? { ...instance, mode } : undefined;
        }),
        reconcile: Effect.fn(function* ({ news, output, session }) {
          const mode = output?.mode ?? news.mode ?? "existing";

          // Observe — try to find a visible instance, preferring an
          // explicit ARN (from output or props) and otherwise scanning
          // the account.
          const existing = yield* readInstance({
            instanceArn: output?.instanceArn ?? news.instanceArn,
            name: news.name,
          });
          if (existing) {
            yield* session.note(existing.instanceArn);
            return {
              ...existing,
              mode,
            };
          }

          // Ensure — for `existing` mode we cannot create one; fail.
          // Organization instances must be enabled manually in the
          // management account.
          if (mode !== "account") {
            return yield* new InstanceInvalidProps({
              message:
                "No visible Identity Center instance was found. Organization instances must be enabled manually in the management account before Alchemy can adopt them.",
            });
          }

          // Ensure — `account` mode creates an account instance.
          const response = yield* retryIdentityCenter(
            ssoAdmin.createInstance({
              Name: news.name,
            }),
          );

          const created = yield* readInstance({
            instanceArn: response.InstanceArn,
            name: news.name,
          });
          if (!created) {
            return yield* new InstanceUnexpectedResponse({
              message: "failed to resolve Identity Center instance after create",
            });
          }

          yield* session.note(created.instanceArn);
          return {
            ...created,
            mode,
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          if (output.mode !== "account") {
            return;
          }

          const existing = yield* readInstance({
            instanceArn: output.instanceArn,
          });
          if (!existing) {
            return;
          }

          yield* retryIdentityCenter(
            ssoAdmin.deleteInstance({
              InstanceArn: output.instanceArn,
            }),
          );
        }),
      };
    }),
  );

const readInstance = Effect.fn(function* ({
  instanceArn,
  name,
}: Pick<InstanceProps, "instanceArn" | "name">) {
  if (instanceArn) {
    const instance = yield* resolveInstance(instanceArn).pipe(
      Effect.orElseSucceed(() => undefined),
    );
    return instance ? toInstanceAttributes(instance) : undefined;
  }

  const instances = yield* listInstances();
  const match =
    instances.find((instance) => instance.Name === name) ??
    (instances.length === 1 ? instances[0] : undefined) ??
    instances.find((instance) => instance.Status === "ACTIVE");

  return match?.InstanceArn && match.IdentityStoreId ? toInstanceAttributes(match) : undefined;
});