sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ RDS/ DBClusterEndpoint.ts

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

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

export interface DBClusterEndpointProps {
  /**
   * Endpoint identifier. If omitted, Alchemy generates one.
   */
  dbClusterEndpointIdentifier?: string;
  /**
   * Cluster that owns the endpoint.
   */
  dbClusterIdentifier: string;
  /**
   * Endpoint type such as `READER`, `WRITER`, or `ANY`.
   */
  endpointType: string;
  /**
   * Static members explicitly attached to the endpoint.
   */
  staticMembers?: string[];
  /**
   * Members excluded from the endpoint.
   */
  excludedMembers?: string[];
  /**
   * User-defined tags.
   */
  tags?: Record<string, string>;
}

export interface DBClusterEndpoint extends Resource<
  "AWS.RDS.DBClusterEndpoint",
  DBClusterEndpointProps,
  {
    /**
     * Identifier of the custom endpoint.
     */
    dbClusterEndpointIdentifier: string;
    /**
     * ARN of the custom endpoint.
     */
    dbClusterEndpointArn: string | undefined;
    /**
     * Cluster that owns the endpoint.
     */
    dbClusterIdentifier: string | undefined;
    /**
     * DNS address applications connect to.
     */
    endpoint: string | undefined;
    /**
     * Status of the endpoint (e.g. `available`).
     */
    status: string | undefined;
    /**
     * Endpoint type (`CUSTOM` for managed endpoints).
     */
    endpointType: string | undefined;
    /**
     * Traffic routing type of the custom endpoint (`READER`, `ANY`).
     */
    customEndpointType: string | undefined;
    /**
     * Instances explicitly attached to the endpoint.
     */
    staticMembers: string[];
    /**
     * Instances excluded from the endpoint.
     */
    excludedMembers: string[];
    /**
     * Tags on the endpoint.
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * A custom Aurora cluster endpoint — a DNS name that routes to a chosen
 * subset of a cluster's instances, on top of the built-in writer and reader
 * endpoints of a `DBCluster`.
 *
 * Use it to pin analytics traffic to specific readers or to keep a stable
 * address across instance replacements. Changing the identifier or owning
 * cluster replaces the endpoint; type and membership update in place.
 * ### Creating Custom Endpoints
 * **Example:** Reader Endpoint for a Cluster
 * ```typescript
 * const readers = yield* DBClusterEndpoint("Readers", {
 *   dbClusterIdentifier: cluster.dbClusterIdentifier,
 *   endpointType: "READER",
 * });
 * ```
 *
 * **Example:** Pin Specific Instances
 * ```typescript
 * const analytics = yield* DBClusterEndpoint("Analytics", {
 *   dbClusterIdentifier: cluster.dbClusterIdentifier,
 *   endpointType: "ANY",
 *   staticMembers: [reporting.dbInstanceIdentifier],
 * });
 * ```
 *
 * @resource
 */
export const DBClusterEndpoint = Resource<DBClusterEndpoint>("AWS.RDS.DBClusterEndpoint");

const toAttrs = ({
  endpoint,
  tags,
}: {
  endpoint: rds.DBClusterEndpoint;
  tags: Record<string, string>;
}): DBClusterEndpoint["Attributes"] => ({
  dbClusterEndpointIdentifier: endpoint.DBClusterEndpointIdentifier ?? "",
  dbClusterEndpointArn: endpoint.DBClusterEndpointArn,
  dbClusterIdentifier: endpoint.DBClusterIdentifier,
  endpoint: endpoint.Endpoint,
  status: endpoint.Status,
  endpointType: endpoint.EndpointType,
  customEndpointType: endpoint.CustomEndpointType,
  staticMembers: endpoint.StaticMembers ?? [],
  excludedMembers: endpoint.ExcludedMembers ?? [],
  tags,
});

export const DBClusterEndpointProvider = () =>
  Provider.effect(
    DBClusterEndpoint,
    Effect.gen(function* () {
      const toIdentifier = (id: string, props: DBClusterEndpointProps) =>
        props.dbClusterEndpointIdentifier
          ? Effect.succeed(props.dbClusterEndpointIdentifier)
          : createPhysicalName({ id, maxLength: 63 });

      const readEndpoint = Effect.fn(function* (identifier: string) {
        const response = yield* rds
          .describeDBClusterEndpoints({
            DBClusterEndpointIdentifier: identifier,
          })
          .pipe(Effect.catchTag("DBClusterNotFoundFault", () => Effect.undefined));
        return response?.DBClusterEndpoints?.[0];
      });

      return {
        stables: ["dbClusterEndpointArn", "dbClusterEndpointIdentifier"],
        // Enumerate every custom cluster endpoint in the account/region.
        // `describeDBClusterEndpoints` with no filter returns custom endpoints
        // across all clusters; system endpoints (EndpointType WRITER/READER)
        // aren't managed via createDBClusterEndpoint, so we keep only CUSTOM
        // ones. Tags aren't returned by describe, so each item carries `{}`
        // (matching `read`'s default when there is no recorded tag set).
        list: () =>
          rds.describeDBClusterEndpoints.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.DBClusterEndpoints ?? [])
                  .filter((endpoint) => endpoint.EndpointType === "CUSTOM")
                  .map((endpoint) => toAttrs({ endpoint, tags: {} })),
              ),
            ),
          ),
        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return;
          if (
            (yield* toIdentifier(id, olds ?? ({} as DBClusterEndpointProps))) !==
            (yield* toIdentifier(id, news))
          ) {
            return { action: "replace" } as const;
          }
          if (olds?.dbClusterIdentifier !== news.dbClusterIdentifier) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const identifier =
            output?.dbClusterEndpointIdentifier ??
            (yield* toIdentifier(
              id,
              olds ??
                ({
                  dbClusterIdentifier: "",
                  endpointType: "READER",
                } as DBClusterEndpointProps),
            ));
          const endpoint = yield* readEndpoint(identifier);
          if (!endpoint?.DBClusterEndpointIdentifier) {
            return undefined;
          }
          return toAttrs({ endpoint, tags: output?.tags ?? {} });
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const identifier = output?.dbClusterEndpointIdentifier ?? (yield* toIdentifier(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // Observe — fetch the endpoint's live state.
          let observed = yield* readEndpoint(identifier);

          // Ensure — create if missing. Tolerate
          // `DBClusterEndpointAlreadyExistsFault` as a race with a peer
          // reconciler.
          if (!observed?.DBClusterEndpointIdentifier) {
            yield* rds
              .createDBClusterEndpoint({
                DBClusterIdentifier: news.dbClusterIdentifier,
                DBClusterEndpointIdentifier: identifier,
                EndpointType: news.endpointType,
                StaticMembers: news.staticMembers,
                ExcludedMembers: news.excludedMembers,
                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              })
              .pipe(Effect.catchTag("DBClusterEndpointAlreadyExistsFault", () => Effect.void));
            observed = yield* readEndpoint(identifier);
            if (!observed?.DBClusterEndpointIdentifier) {
              return yield* new DBClusterEndpointUnexpectedResponse({
                message: `DB cluster endpoint '${identifier}' not found after create`,
              });
            }
          } else {
            // Sync mutable endpoint config — push desired shape.
            yield* rds.modifyDBClusterEndpoint({
              DBClusterEndpointIdentifier: identifier,
              EndpointType: news.endpointType,
              StaticMembers: news.staticMembers,
              ExcludedMembers: news.excludedMembers,
            });
            observed = yield* readEndpoint(identifier);
            if (!observed?.DBClusterEndpointIdentifier) {
              return yield* new DBClusterEndpointUnexpectedResponse({
                message: `DB cluster endpoint '${identifier}' not found after update`,
              });
            }
          }

          const dbClusterEndpointArn = observed.DBClusterEndpointArn;

          // Sync tags — diff observed cloud tags against desired. The
          // describeDBClusterEndpoints response does not include tags, so we
          // diff against the previously-recorded tag set on `output`.
          const observedTags = output?.tags ?? {};
          const { removed, upsert } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0 && dbClusterEndpointArn) {
            yield* rds.addTagsToResource({
              ResourceName: dbClusterEndpointArn,
              Tags: upsert,
            });
          }
          if (removed.length > 0 && dbClusterEndpointArn) {
            yield* rds.removeTagsFromResource({
              ResourceName: dbClusterEndpointArn,
              TagKeys: removed,
            });
          }

          yield* session.note(dbClusterEndpointArn ?? identifier);
          return toAttrs({ endpoint: observed, tags: desiredTags });
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* rds
            .deleteDBClusterEndpoint({
              DBClusterEndpointIdentifier: output.dbClusterEndpointIdentifier,
            })
            .pipe(Effect.catchTag("DBClusterEndpointNotFoundFault", () => Effect.void));
        }),
      };
    }),
  );