sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ OpenSearch/ Domain.ts

import * as opensearch from "@distilled.cloud/aws/opensearch";
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 { subsetDiffers } from "alchemy/Util/equal";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import type { PolicyDocument } from "../IAM/Policy.ts";
import { normalizePolicyDocument, stringifyPolicyDocument } from "../IAM/Policy.ts";
import type { Providers } from "../Providers.ts";
import {
  domainEndpoint,
  isDomainActive,
  isDomainDeletable,
  readDomainTags,
  repeatUntilDomainState,
} from "./internal.ts";

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

export interface DomainClusterConfig {
  /**
   * Instance type of the data nodes, e.g. `"t3.small.search"` (the cheapest
   * general-purpose type) or `"r7g.large.search"`.
   * @default "t3.small.search"
   */
  instanceType?: opensearch.OpenSearchPartitionInstanceType;
  /**
   * Number of data nodes in the cluster.
   * @default 1
   */
  instanceCount?: number;
  /**
   * Whether dedicated master nodes are enabled.
   */
  dedicatedMasterEnabled?: boolean;
  /**
   * Instance type of the dedicated master nodes.
   */
  dedicatedMasterType?: opensearch.OpenSearchPartitionInstanceType;
  /**
   * Number of dedicated master nodes (3 or 5 recommended).
   */
  dedicatedMasterCount?: number;
  /**
   * Whether data is distributed across multiple Availability Zones.
   */
  zoneAwarenessEnabled?: boolean;
  /**
   * Number of Availability Zones (2 or 3) when zone awareness is enabled.
   */
  availabilityZoneCount?: number;
  /**
   * Whether UltraWarm storage is enabled. Not supported on t2/t3 instances.
   */
  warmEnabled?: boolean;
  /**
   * Instance type of the UltraWarm nodes.
   */
  warmType?: opensearch.OpenSearchWarmPartitionInstanceType;
  /**
   * Number of UltraWarm nodes.
   */
  warmCount?: number;
  /**
   * Whether the domain runs in Multi-AZ with Standby mode.
   */
  multiAZWithStandbyEnabled?: boolean;
}

export interface DomainEbsOptions {
  /**
   * Whether EBS volumes are attached to the data nodes. Required for
   * EBS-only instance types like `t3.small.search`.
   * @default true
   */
  enabled?: boolean;
  /**
   * EBS volume type.
   * @default "gp3"
   */
  volumeType?: opensearch.VolumeType;
  /**
   * EBS volume size in GiB per data node.
   * @default 10
   */
  volumeSize?: number;
  /**
   * Provisioned IOPS (io1/gp3 volumes).
   */
  iops?: number;
  /**
   * Provisioned throughput in MiB/s (gp3 volumes).
   */
  throughput?: number;
}

export interface DomainEncryptionAtRestOptions {
  /**
   * Whether encryption at rest is enabled. Enabling on an existing domain is
   * an in-place update; DISABLING it is not supported and replaces the
   * domain. Not supported on t2 instance types.
   * @default true when `encryptionAtRest` is specified
   */
  enabled?: boolean;
  /**
   * Customer-managed KMS key ID used for encryption.
   * @default the AWS-owned aws/es key
   */
  kmsKeyId?: string;
}

export interface DomainEndpointOptionsProps {
  /**
   * Whether all traffic to the domain must arrive over HTTPS.
   */
  enforceHTTPS?: boolean;
  /**
   * Minimum TLS version for HTTPS connections, e.g.
   * `"Policy-Min-TLS-1-2-2019-07"`.
   */
  tlsSecurityPolicy?: opensearch.TLSSecurityPolicy;
  /**
   * Whether a custom endpoint is enabled for the domain.
   */
  customEndpointEnabled?: boolean;
  /**
   * Fully qualified custom endpoint, e.g. `"search.example.com"`.
   */
  customEndpoint?: string;
  /**
   * ACM certificate ARN for the custom endpoint.
   */
  customEndpointCertificateArn?: string;
}

export interface DomainSnapshotOptions {
  /**
   * Hour of the day (0-23, UTC) when automated snapshots are taken.
   */
  automatedSnapshotStartHour?: number;
}

export interface DomainVpcOptions {
  /**
   * Subnet IDs the domain's endpoints are placed into. One subnet unless
   * zone awareness is enabled.
   */
  subnetIds?: string[];
  /**
   * Security group IDs applied to the domain's network interfaces.
   */
  securityGroupIds?: string[];
}

export interface DomainProps {
  /**
   * Name of the domain. 3-28 characters; lowercase letters, numbers, and
   * hyphens; must start with a lowercase letter. If omitted, a deterministic
   * physical name is generated. Changing the name replaces the domain.
   */
  domainName?: string;
  /**
   * Engine version, e.g. `"OpenSearch_2.19"` or `"Elasticsearch_7.10"`.
   * Raising the version triggers an in-place engine upgrade.
   * @default the latest OpenSearch version
   */
  engineVersion?: string;
  /**
   * Cluster topology: data node type/count, dedicated masters, zone
   * awareness, and UltraWarm.
   * @default a single t3.small.search data node
   */
  clusterConfig?: DomainClusterConfig;
  /**
   * EBS storage attached to each data node.
   * @default 10 GiB gp3
   */
  ebsOptions?: DomainEbsOptions;
  /**
   * IAM resource-based access policy document controlling who can reach the
   * domain endpoint, either as a structured {@link PolicyDocument} or a raw
   * JSON string (escape hatch / adoption of pre-existing policies).
   */
  accessPolicies?: PolicyDocument | string;
  /**
   * IP address type of the endpoint — `"ipv4"` or `"dualstack"`.
   */
  ipAddressType?: opensearch.IPAddressType;
  /**
   * VPC placement for the domain endpoints. Omit for a public endpoint.
   */
  vpcOptions?: DomainVpcOptions;
  /**
   * Encryption of data at rest. Disabling on an existing domain replaces it.
   */
  encryptionAtRest?: DomainEncryptionAtRestOptions;
  /**
   * Whether node-to-node (in transit) encryption is enabled. Disabling on an
   * existing domain replaces it.
   */
  nodeToNodeEncryption?: boolean;
  /**
   * Advanced OpenSearch settings, e.g.
   * `{ "rest.action.multi.allow_explicit_index": "true" }`.
   */
  advancedOptions?: Record<string, string>;
  /**
   * HTTPS enforcement, TLS policy, and custom endpoint configuration.
   */
  domainEndpointOptions?: DomainEndpointOptionsProps;
  /**
   * Automated snapshot configuration.
   */
  snapshotOptions?: DomainSnapshotOptions;
  /**
   * User-defined tags for the domain.
   */
  tags?: Record<string, string>;
}

export interface Domain extends Resource<
  "AWS.OpenSearch.Domain",
  DomainProps,
  {
    /**
     * Name of the domain.
     */
    domainName: string;
    /**
     * ARN of the domain.
     */
    domainArn: string;
    /**
     * Unique identifier of the domain (`account-id/domain-name`).
     */
    domainId: string;
    /**
     * Engine version running on the domain (e.g. `OpenSearch_2.19`).
     */
    engineVersion: string | undefined;
    /**
     * Domain-specific HTTPS endpoint for search and index requests.
     */
    endpoint: string | undefined;
    /**
     * Whether domain creation has completed.
     */
    created: boolean;
    /**
     * Whether a configuration change is currently being applied.
     */
    processing: boolean;
    /**
     * Tags on the domain.
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An Amazon OpenSearch Service domain — a managed OpenSearch/Elasticsearch
 * cluster with a search/HTTP endpoint.
 *
 * Domains take roughly 15-25 minutes to provision (and about as long for
 * blue/green configuration changes) and are billed per instance-hour while
 * they exist. Destroy domains you are not using.
 * ### Creating a Domain
 * **Example:** Minimal Domain
 * ```typescript
 * // A single t3.small.search node with 10 GiB of gp3 EBS storage.
 * const domain = yield* Domain("Search", {});
 * ```
 *
 * **Example:** Encrypted Domain with Access Policy
 * ```typescript
 * const domain = yield* Domain("Search", {
 *   engineVersion: "OpenSearch_2.19",
 *   clusterConfig: { instanceType: "t3.small.search", instanceCount: 1 },
 *   ebsOptions: { volumeType: "gp3", volumeSize: 10 },
 *   encryptionAtRest: { enabled: true },
 *   nodeToNodeEncryption: true,
 *   domainEndpointOptions: {
 *     enforceHTTPS: true,
 *     tlsSecurityPolicy: "Policy-Min-TLS-1-2-2019-07",
 *   },
 *   accessPolicies: {
 *     Version: "2012-10-17",
 *     Statement: [
 *       {
 *         Effect: "Allow",
 *         Principal: { AWS: `arn:aws:iam::${accountId}:root` },
 *         Action: ["es:*"],
 *         Resource: `arn:aws:es:${region}:${accountId}:domain/*`,
 *       },
 *     ],
 *   },
 * });
 * ```
 *
 * ### Multi-AZ Cluster
 * **Example:** Zone-Aware Cluster
 * ```typescript
 * const domain = yield* Domain("Search", {
 *   clusterConfig: {
 *     instanceType: "r7g.large.search",
 *     instanceCount: 2,
 *     zoneAwarenessEnabled: true,
 *     availabilityZoneCount: 2,
 *   },
 * });
 * ```
 *
 * @resource
 */
export const Domain = Resource<Domain>("AWS.OpenSearch.Domain");

const DEFAULT_INSTANCE_TYPE = "t3.small.search";

const toClusterConfig = (config: DomainClusterConfig | undefined): opensearch.ClusterConfig => ({
  InstanceType: config?.instanceType ?? DEFAULT_INSTANCE_TYPE,
  InstanceCount: config?.instanceCount ?? 1,
  DedicatedMasterEnabled: config?.dedicatedMasterEnabled,
  DedicatedMasterType: config?.dedicatedMasterType,
  DedicatedMasterCount: config?.dedicatedMasterCount,
  ZoneAwarenessEnabled: config?.zoneAwarenessEnabled,
  ZoneAwarenessConfig:
    config?.availabilityZoneCount !== undefined
      ? { AvailabilityZoneCount: config.availabilityZoneCount }
      : undefined,
  WarmEnabled: config?.warmEnabled,
  WarmType: config?.warmType,
  WarmCount: config?.warmCount,
  MultiAZWithStandbyEnabled: config?.multiAZWithStandbyEnabled,
});

const toEbsOptions = (ebs: DomainEbsOptions | undefined): opensearch.EBSOptions =>
  ebs?.enabled === false
    ? { EBSEnabled: false }
    : {
        EBSEnabled: true,
        VolumeType: ebs?.volumeType ?? "gp3",
        VolumeSize: ebs?.volumeSize ?? 10,
        Iops: ebs?.iops,
        Throughput: ebs?.throughput,
      };

const toEndpointOptions = (
  options: DomainEndpointOptionsProps | undefined,
): opensearch.DomainEndpointOptions | undefined =>
  options === undefined
    ? undefined
    : {
        EnforceHTTPS: options.enforceHTTPS,
        TLSSecurityPolicy: options.tlsSecurityPolicy,
        CustomEndpointEnabled: options.customEndpointEnabled,
        CustomEndpoint: options.customEndpoint,
        CustomEndpointCertificateArn: options.customEndpointCertificateArn,
      };

const toAccessPolicies = (policy: PolicyDocument | string | undefined): string | undefined =>
  policy === undefined
    ? undefined
    : typeof policy === "string"
      ? policy
      : stringifyPolicyDocument(policy);

const toVpcOptions = (options: DomainVpcOptions | undefined): opensearch.VPCOptions | undefined =>
  options === undefined
    ? undefined
    : {
        SubnetIds: options.subnetIds,
        SecurityGroupIds: options.securityGroupIds,
      };

export const DomainProvider = () =>
  Provider.effect(
    Domain,
    Effect.gen(function* () {
      const toName = (id: string, props: DomainProps) =>
        props.domainName
          ? Effect.succeed(props.domainName)
          : createPhysicalName({ id, maxLength: 28, lowercase: true });

      const readDomain = Effect.fn(function* (name: string) {
        return yield* opensearch.describeDomain({ DomainName: name }).pipe(
          Effect.map((response) => response.DomainStatus),
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
        );
      });

      const waitForActive = Effect.fn(function* (name: string) {
        const domain = yield* repeatUntilDomainState(readDomain(name), isDomainActive);
        if (domain === undefined) {
          return yield* new OpenSearchDomainUnexpectedResponse({
            message: `OpenSearch domain '${name}' not found while waiting`,
          });
        }
        return domain;
      });

      const toAttrs = Effect.fn(function* (domain: opensearch.DomainStatus) {
        return {
          domainName: domain.DomainName,
          domainArn: domain.ARN,
          domainId: domain.DomainId,
          engineVersion: domain.EngineVersion,
          endpoint: domainEndpoint(domain),
          created: domain.Created === true,
          processing: domain.Processing === true,
          tags: yield* readDomainTags(domain.ARN),
        };
      });

      return {
        stables: ["domainName", "domainArn", "domainId"],

        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return undefined;
          const o: DomainProps = olds ?? {};
          const n: DomainProps = news ?? {};
          if ((yield* toName(id, o)) !== (yield* toName(id, n))) {
            return { action: "replace" } as const;
          }
          // Encryption at rest and node-to-node encryption can be ENABLED
          // in place but never disabled — disabling replaces the domain.
          if (
            o.encryptionAtRest?.enabled !== false &&
            o.encryptionAtRest !== undefined &&
            n.encryptionAtRest?.enabled === false
          ) {
            return { action: "replace" } as const;
          }
          if (o.nodeToNodeEncryption === true && n.nodeToNodeEncryption === false) {
            return { action: "replace" } as const;
          }
          // Moving a domain between public and VPC endpoints replaces it.
          if ((o.vpcOptions === undefined) !== (n.vpcOptions === undefined)) {
            return { action: "replace" } as const;
          }
        }),

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

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

          // 1. Observe — cloud state is authoritative.
          let observed = yield* readDomain(name);

          // 2. Ensure — create if missing; tolerate AlreadyExists as a race.
          if (observed === undefined) {
            yield* opensearch
              .createDomain({
                DomainName: name,
                EngineVersion: props.engineVersion,
                ClusterConfig: toClusterConfig(props.clusterConfig),
                EBSOptions: toEbsOptions(props.ebsOptions),
                AccessPolicies: toAccessPolicies(props.accessPolicies),
                IPAddressType: props.ipAddressType,
                SnapshotOptions:
                  props.snapshotOptions !== undefined
                    ? {
                        AutomatedSnapshotStartHour:
                          props.snapshotOptions.automatedSnapshotStartHour,
                      }
                    : undefined,
                VPCOptions: toVpcOptions(props.vpcOptions),
                EncryptionAtRestOptions:
                  props.encryptionAtRest !== undefined
                    ? {
                        Enabled: props.encryptionAtRest.enabled ?? true,
                        KmsKeyId: props.encryptionAtRest.kmsKeyId,
                      }
                    : undefined,
                NodeToNodeEncryptionOptions:
                  props.nodeToNodeEncryption !== undefined
                    ? { Enabled: props.nodeToNodeEncryption }
                    : undefined,
                AdvancedOptions: props.advancedOptions,
                DomainEndpointOptions: toEndpointOptions(props.domainEndpointOptions),
                TagList: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              })
              .pipe(Effect.catchTag("ResourceAlreadyExistsException", () => Effect.void));
          }

          // Provisioning and blue/green config changes both surface as
          // Processing=true; wait (bounded) so config updates do not fail.
          observed = yield* waitForActive(name);

          // 3. Sync — compute the update delta from OBSERVED state.
          const update: opensearch.UpdateDomainConfigRequest = {
            DomainName: name,
          };
          let mutated = false;

          const desiredCluster = toClusterConfig(props.clusterConfig);
          if (subsetDiffers(desiredCluster, observed.ClusterConfig)) {
            update.ClusterConfig = desiredCluster;
            mutated = true;
          }
          const desiredEbs = toEbsOptions(props.ebsOptions);
          if (subsetDiffers(desiredEbs, observed.EBSOptions)) {
            update.EBSOptions = desiredEbs;
            mutated = true;
          }
          // Drift-compare canonicalized documents so key order / encoding
          // differences in what OpenSearch echoes back never cause a
          // spurious blue/green config change on re-deploy.
          if (
            props.accessPolicies !== undefined &&
            normalizePolicyDocument(props.accessPolicies) !==
              normalizePolicyDocument(observed.AccessPolicies ?? "")
          ) {
            update.AccessPolicies = toAccessPolicies(props.accessPolicies);
            mutated = true;
          }
          if (props.ipAddressType !== undefined && props.ipAddressType !== observed.IPAddressType) {
            update.IPAddressType = props.ipAddressType;
            mutated = true;
          }
          if (
            props.snapshotOptions?.automatedSnapshotStartHour !== undefined &&
            props.snapshotOptions.automatedSnapshotStartHour !==
              observed.SnapshotOptions?.AutomatedSnapshotStartHour
          ) {
            update.SnapshotOptions = {
              AutomatedSnapshotStartHour: props.snapshotOptions.automatedSnapshotStartHour,
            };
            mutated = true;
          }
          const desiredVpc = toVpcOptions(props.vpcOptions);
          if (
            desiredVpc !== undefined &&
            subsetDiffers(desiredVpc, {
              SubnetIds: observed.VPCOptions?.SubnetIds,
              SecurityGroupIds: observed.VPCOptions?.SecurityGroupIds,
            })
          ) {
            update.VPCOptions = desiredVpc;
            mutated = true;
          }
          if (
            props.advancedOptions !== undefined &&
            subsetDiffers(props.advancedOptions, observed.AdvancedOptions)
          ) {
            update.AdvancedOptions = props.advancedOptions;
            mutated = true;
          }
          const desiredEndpointOptions = toEndpointOptions(props.domainEndpointOptions);
          if (
            desiredEndpointOptions !== undefined &&
            subsetDiffers(desiredEndpointOptions, observed.DomainEndpointOptions)
          ) {
            update.DomainEndpointOptions = desiredEndpointOptions;
            mutated = true;
          }
          // Encryption can only be enabled in place (disable = replacement,
          // handled by diff).
          if (
            props.encryptionAtRest !== undefined &&
            props.encryptionAtRest.enabled !== false &&
            observed.EncryptionAtRestOptions?.Enabled !== true
          ) {
            update.EncryptionAtRestOptions = {
              Enabled: true,
              KmsKeyId: props.encryptionAtRest.kmsKeyId,
            };
            mutated = true;
          }
          if (
            props.nodeToNodeEncryption === true &&
            observed.NodeToNodeEncryptionOptions?.Enabled !== true
          ) {
            update.NodeToNodeEncryptionOptions = { Enabled: true };
            mutated = true;
          }

          if (mutated) {
            yield* opensearch.updateDomainConfig(update);
            observed = yield* waitForActive(name);
          }

          // 3b. Engine upgrades run through the dedicated upgrade API.
          if (
            props.engineVersion !== undefined &&
            observed.EngineVersion !== undefined &&
            observed.EngineVersion !== props.engineVersion
          ) {
            yield* opensearch.upgradeDomain({
              DomainName: name,
              TargetVersion: props.engineVersion,
            });
            observed = yield* waitForActive(name);
          }

          // 3c. Sync tags — diff against OBSERVED cloud tags.
          const observedTags = yield* readDomainTags(observed.ARN);
          const { removed, upsert } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* opensearch.addTags({ ARN: observed.ARN, TagList: upsert });
          }
          if (removed.length > 0) {
            yield* opensearch.removeTags({
              ARN: observed.ARN,
              TagKeys: removed,
            });
          }

          yield* session.note(name);
          return yield* toAttrs(observed);
        }),

        delete: Effect.fn(function* ({ output }) {
          const name = output.domainName;
          // A domain mid-create/config-change may reject deletion — wait
          // (bounded, tolerant) for it to settle first. Already deleting
          // (or gone) is success.
          yield* repeatUntilDomainState(readDomain(name), isDomainDeletable).pipe(
            Effect.orElseSucceed(() => undefined),
          );
          yield* opensearch
            .deleteDomain({ DomainName: name })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),

        list: () =>
          opensearch.listDomainNames({}).pipe(
            Effect.map((response) =>
              (response.DomainNames ?? [])
                .map((info) => info.DomainName)
                .filter((name): name is string => name !== undefined),
            ),
            Effect.flatMap(
              Effect.forEach(
                (name) =>
                  opensearch.describeDomain({ DomainName: name }).pipe(
                    Effect.map((response) => response.DomainStatus),
                    Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
                  ),
                { concurrency: 4 },
              ),
            ),
            Effect.map((domains) =>
              domains.filter((domain): domain is opensearch.DomainStatus => domain !== undefined),
            ),
            Effect.flatMap(Effect.forEach((domain) => toAttrs(domain), { concurrency: 4 })),
          ),
      };
    }),
  );