sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ DirectoryService/ Directory.ts

import * as ds from "@distilled.cloud/aws/directory-service";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
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 Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import { readDirectoryTags, sameStringSet } from "./internal.ts";

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

/** The kind of managed directory to launch. */
export type DirectoryFlavor = "SimpleAD" | "MicrosoftAD";

export interface DirectoryProps {
  /**
   * Which managed directory to launch — a Samba-based `"SimpleAD"` or an
   * actual `"MicrosoftAD"` (AWS Managed Microsoft AD). Changing the flavor
   * replaces the directory.
   * @default "SimpleAD"
   */
  type?: DirectoryFlavor;
  /**
   * Fully qualified domain name of the directory, e.g. `corp.example.com`.
   * The domain does not need to be publicly resolvable. Changing the name
   * replaces the directory.
   */
  name: string;
  /**
   * NetBIOS short name of the directory, e.g. `CORP`. Changing the short
   * name replaces the directory.
   * @default the first label of `name`
   */
  shortName?: string;
  /**
   * Password for the directory administrator account (`Administrator` for
   * Simple AD, `Admin` for Microsoft AD). There is no API to change it after
   * creation, so changing the password replaces the directory.
   */
  password: Redacted.Redacted<string>;
  /**
   * Human-readable description of the directory. There is no update API, so
   * changing the description replaces the directory.
   */
  description?: string;
  /**
   * Size of a Simple AD directory — `"Small"` (up to ~500 users) or
   * `"Large"` (up to ~5000 users). Ignored for Microsoft AD. Changing the
   * size replaces the directory.
   * @default "Small"
   */
  size?: ds.DirectorySize;
  /**
   * Edition of a Microsoft AD directory — `"Standard"` or `"Enterprise"`.
   * Ignored for Simple AD. Changing the edition replaces the directory.
   * @default "Standard"
   */
  edition?: ds.DirectoryEdition;
  /**
   * VPC the directory's domain controllers are placed into. Changing the
   * VPC replaces the directory.
   */
  vpcId: string;
  /**
   * Exactly two subnets in DIFFERENT Availability Zones of `vpcId` — one
   * domain controller is launched into each. Changing the subnets replaces
   * the directory.
   */
  subnetIds: string[];
  /**
   * User-defined tags for the directory.
   */
  tags?: Record<string, string>;
}

export interface Directory extends Resource<
  "AWS.DirectoryService.Directory",
  DirectoryProps,
  {
    /** The ID of the directory, e.g. `d-1234567890`. */
    directoryId: string;
    /** The ARN of the directory, e.g. `arn:aws:ds:us-east-1:123456789012:directory/d-1234567890`. */
    directoryArn: string;
    /** The fully qualified name of the directory. */
    directoryName: string;
    /** The directory type, e.g. `SimpleAD` or `MicrosoftAD`. */
    type: string;
    /** The current lifecycle stage of the directory, e.g. `Active`. */
    stage: string;
    /** The size of a Simple AD directory (`Small` or `Large`). */
    size: string | undefined;
    /** The edition of a Microsoft AD directory (`Standard` or `Enterprise`). */
    edition: string | undefined;
    /** The directory alias used for the access URL. */
    alias: string | undefined;
    /** The access URL of the directory, e.g. `<alias>.awsapps.com`. */
    accessUrl: string | undefined;
    /** The IP addresses of the directory's DNS servers. */
    dnsIpAddrs: string[];
    /** The security group created for the directory's controllers. */
    securityGroupId: string | undefined;
    /** The VPC the directory is deployed into. */
    vpcId: string | undefined;
    /** The subnets hosting the directory's domain controllers. */
    subnetIds: string[];
    /** The Availability Zones the directory spans. */
    availabilityZones: string[];
    /** The tags attached to the directory. */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An AWS Directory Service managed directory — either Simple AD (Samba) or
 * AWS Managed Microsoft AD.
 *
 * Directories are VPC-only and require two subnets in different Availability
 * Zones. Provisioning is SLOW: Simple AD takes roughly 10 minutes and
 * Microsoft AD 20-40 minutes, and directories bill hourly while they exist.
 * Destroy directories you are not using.
 * ### Creating a Directory
 * **Example:** Simple AD Directory
 * ```typescript
 * const directory = yield* Directory("Corp", {
 *   name: "corp.example.com",
 *   password: Redacted.make("SuperSecret123!"),
 *   size: "Small",
 *   vpcId: vpc.vpcId,
 *   subnetIds: [subnetA.subnetId, subnetB.subnetId],
 * });
 * ```
 *
 * **Example:** Managed Microsoft AD Directory
 * ```typescript
 * const directory = yield* Directory("Corp", {
 *   type: "MicrosoftAD",
 *   name: "corp.example.com",
 *   shortName: "CORP",
 *   password: Redacted.make("SuperSecret123!"),
 *   edition: "Standard",
 *   vpcId: vpc.vpcId,
 *   subnetIds: [subnetA.subnetId, subnetB.subnetId],
 * });
 * ```
 *
 * ### Using the Directory
 * **Example:** Read the DNS Addresses
 * ```typescript
 * const directory = yield* Directory("Corp", { ... });
 * // the directory-provided DNS servers, one per Availability Zone
 * const dns = directory.dnsIpAddrs;
 * ```
 *
 * @resource
 */
export const Directory = Resource<Directory>("AWS.DirectoryService.Directory");

const DEFAULT_SIZE: ds.DirectorySize = "Small";
const DEFAULT_EDITION: ds.DirectoryEdition = "Standard";

/** Stages from which a directory can never come back. */
const isTerminalStage = (stage: string | undefined): boolean =>
  stage === "Deleting" || stage === "Deleted" || stage === "Failed";

class DirectoryNotReady extends Data.TaggedError("DirectoryNotReady")<{
  readonly directoryId: string;
  readonly stage: string | undefined;
}> {}

class DirectoryProvisioningFailed extends Data.TaggedError("DirectoryProvisioningFailed")<{
  readonly directoryId: string;
  readonly stage: string | undefined;
  readonly reason: string | undefined;
}> {}

// Directory provisioning is slow (Simple AD ~10 min, Microsoft AD 20-40
// min); poll every 30s with a ~50 min budget. Only DirectoryNotReady is
// retried — a Failed/Deleted stage aborts immediately.
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 === "DirectoryNotReady",
    schedule: Schedule.max([Schedule.fixed("30 seconds"), Schedule.recurs(100)]),
  });

export const DirectoryProvider = () =>
  Provider.effect(
    Directory,
    Effect.gen(function* () {
      const getById = Effect.fn(function* (directoryId: string) {
        const response = yield* ds
          .describeDirectories({ DirectoryIds: [directoryId] })
          .pipe(Effect.catchTag("EntityDoesNotExistException", () => Effect.undefined));
        return response?.DirectoryDescriptions?.[0];
      });

      // Best-effort fallback for lost state: scan the account's directories
      // for a live one with the desired domain name.
      const findByName = Effect.fn(function* (name: string | undefined) {
        if (name === undefined) return undefined;
        const matches = yield* ds.describeDirectories.items({}).pipe(
          Stream.filter((d) => d.Name === name && !isTerminalStage(d.Stage)),
          Stream.take(1),
          Stream.runCollect,
        );
        return Array.from(matches)[0];
      });

      const observe = Effect.fn(function* (
        directoryId: string | undefined,
        name: string | undefined,
      ) {
        const found = directoryId ? yield* getById(directoryId) : yield* findByName(name);
        return found !== undefined && !isTerminalStage(found.Stage) ? found : undefined;
      });

      const waitForActive = (directoryId: string) =>
        Effect.gen(function* () {
          const directory = yield* getById(directoryId);
          if (directory === undefined || isTerminalStage(directory.Stage)) {
            return yield* new DirectoryProvisioningFailed({
              directoryId,
              stage: directory?.Stage,
              reason: directory?.StageReason,
            });
          }
          if (directory.Stage !== "Active") {
            return yield* new DirectoryNotReady({
              directoryId,
              stage: directory.Stage,
            });
          }
          return directory;
        }).pipe(retryWhileNotReady);

      // Wait for a directory to leave a transitional stage before deleting.
      // Ends when the directory is in a steady stage, already deleting, or
      // gone.
      const waitUntilSettled = Effect.fn(function* (directoryId: string) {
        return yield* getById(directoryId).pipe(
          Effect.flatMap((directory) => {
            if (
              directory !== undefined &&
              (directory.Stage === "Requested" ||
                directory.Stage === "Creating" ||
                directory.Stage === "Created" ||
                directory.Stage === "Restoring" ||
                directory.Stage === "Updating")
            ) {
              return Effect.fail(
                new DirectoryNotReady({
                  directoryId,
                  stage: directory.Stage,
                }),
              );
            }
            return Effect.succeed(directory);
          }),
          retryWhileNotReady,
        );
      });

      const toAttrs = Effect.fn(function* (directory: ds.DirectoryDescription) {
        if (!directory.DirectoryId || !directory.Name) {
          return yield* new DirectoryUnexpectedResponse({
            message: `directory '${directory.DirectoryId}' is missing its id or name`,
          });
        }
        const { accountId, region } = yield* AWSEnvironment.current;
        return {
          directoryId: directory.DirectoryId,
          directoryArn: `arn:aws:ds:${region}:${accountId}:directory/${directory.DirectoryId}`,
          directoryName: directory.Name,
          type: directory.Type ?? "SimpleAD",
          stage: directory.Stage ?? "Active",
          size: directory.Size,
          edition: directory.Edition,
          alias: directory.Alias,
          accessUrl: directory.AccessUrl,
          dnsIpAddrs: [...(directory.DnsIpAddrs ?? [])],
          securityGroupId: directory.VpcSettings?.SecurityGroupId,
          vpcId: directory.VpcSettings?.VpcId,
          subnetIds: [...(directory.VpcSettings?.SubnetIds ?? [])],
          availabilityZones: [...(directory.VpcSettings?.AvailabilityZones ?? [])],
          tags: yield* readDirectoryTags(directory.DirectoryId),
        };
      });

      return {
        stables: ["directoryId", "directoryName"],

        diff: Effect.fn(function* ({ olds, news }) {
          if (!isResolved(news)) return undefined;
          const n = news;
          const o = olds;
          if (o === undefined || n === undefined) return undefined;
          // Every launch property is create-only — there is no update API
          // for the directory itself; only tags mutate in place.
          const type = (p: DirectoryProps) => p.type ?? "SimpleAD";
          if (type(n) !== type(o)) return { action: "replace" } as const;
          if (n.name !== o.name) return { action: "replace" } as const;
          if (n.shortName !== o.shortName) {
            return { action: "replace" } as const;
          }
          if (Redacted.value(n.password) !== Redacted.value(o.password)) {
            return { action: "replace" } as const;
          }
          if (n.description !== o.description) {
            return { action: "replace" } as const;
          }
          if (type(n) === "SimpleAD" && (n.size ?? DEFAULT_SIZE) !== (o.size ?? DEFAULT_SIZE)) {
            return { action: "replace" } as const;
          }
          if (
            type(n) === "MicrosoftAD" &&
            (n.edition ?? DEFAULT_EDITION) !== (o.edition ?? DEFAULT_EDITION)
          ) {
            return { action: "replace" } as const;
          }
          if (n.vpcId !== o.vpcId) return { action: "replace" } as const;
          if (!sameStringSet(n.subnetIds, o.subnetIds)) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const directory = yield* observe(output?.directoryId, olds?.name);
          if (directory === undefined) return undefined;
          const attrs = yield* toAttrs(directory);
          return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
        }),

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

          // 1. Observe — cloud state is authoritative; output only caches
          //    the directory id.
          const observed = yield* observe(output?.directoryId, props.name);

          // 2. Ensure — create if missing.
          let directoryId = observed?.DirectoryId;
          if (directoryId === undefined) {
            const tagList = Object.entries(desiredTags).map(([Key, Value]) => ({
              Key,
              Value,
            }));
            const created =
              type === "MicrosoftAD"
                ? yield* ds.createMicrosoftAD({
                    Name: props.name,
                    ShortName: props.shortName,
                    Password: props.password,
                    Description: props.description,
                    Edition: props.edition ?? DEFAULT_EDITION,
                    VpcSettings: {
                      VpcId: props.vpcId,
                      SubnetIds: props.subnetIds,
                    },
                    Tags: tagList,
                  })
                : yield* ds.createDirectory({
                    Name: props.name,
                    ShortName: props.shortName,
                    Password: props.password,
                    Description: props.description,
                    Size: props.size ?? DEFAULT_SIZE,
                    VpcSettings: {
                      VpcId: props.vpcId,
                      SubnetIds: props.subnetIds,
                    },
                    Tags: tagList,
                  });
            if (created.DirectoryId === undefined) {
              return yield* new DirectoryUnexpectedResponse({
                message: `Create${type} for '${props.name}' returned no DirectoryId`,
              });
            }
            directoryId = created.DirectoryId;
          }

          // Provisioning is slow (Simple AD ~10 min, Microsoft AD 20-40
          // min); wait (bounded) for the directory to become Active so the
          // returned attributes (DNS addresses, security group) are real.
          const active = yield* waitForActive(directoryId);

          // 3. Sync tags — diff against OBSERVED cloud tags.
          const observedTags = yield* readDirectoryTags(directoryId);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* ds.addTagsToResource({
              ResourceId: directoryId,
              Tags: upsert,
            });
          }
          if (removed.length > 0) {
            yield* ds.removeTagsFromResource({
              ResourceId: directoryId,
              TagKeys: removed,
            });
          }

          yield* session.note(directoryId);
          return yield* toAttrs(active);
        }),

        delete: Effect.fn(function* ({ output }) {
          const directoryId = output.directoryId;
          // A directory mid-create rejects deletion — wait (bounded) for it
          // to settle first. Already deleting (or gone) is success.
          const settled = yield* waitUntilSettled(directoryId).pipe(
            Effect.orElseSucceed(() => undefined),
          );
          if (
            settled === undefined ||
            settled.Stage === "Deleting" ||
            settled.Stage === "Deleted"
          ) {
            return;
          }
          yield* ds
            .deleteDirectory({ DirectoryId: directoryId })
            .pipe(Effect.catchTag("EntityDoesNotExistException", () => Effect.void));
        }),

        list: () =>
          ds.describeDirectories.items({}).pipe(
            Stream.runCollect,
            Effect.flatMap((directories) =>
              Effect.forEach(
                Array.from(directories).filter(
                  (d) =>
                    d.DirectoryId !== undefined &&
                    d.Name !== undefined &&
                    !isTerminalStage(d.Stage),
                ),
                (d) => toAttrs(d),
                { concurrency: 4 },
              ),
            ),
          ),
      };
    }),
  );