sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ SES/ MultiRegionEndpoint.ts

import * as sesv2 from "@distilled.cloud/aws/sesv2";
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, createTagsList, 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 { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";

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

/**
 * The lifecycle status of a multi-region endpoint: `CREATING`, `READY`,
 * `FAILED`, or `DELETING`.
 */
export type MultiRegionEndpointStatus = sesv2.Status;

export interface MultiRegionEndpointProps {
  /**
   * Name of the multi-region endpoint. If omitted, a deterministic physical
   * name is generated from the app, stage, and logical ID. Changing the name
   * replaces the endpoint.
   */
  endpointName?: string;
  /**
   * The secondary AWS regions the endpoint routes traffic across, e.g.
   * `["eu-west-1"]`. The primary region is wherever the resource is created;
   * sending traffic is split across it and every region listed here.
   *
   * There is no update API, so any change to this list replaces the endpoint.
   */
  regions: string[];
  /**
   * Tags to apply to the endpoint. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface MultiRegionEndpoint extends Resource<
  "AWS.SES.MultiRegionEndpoint",
  MultiRegionEndpointProps,
  {
    /** Name of the multi-region endpoint. */
    endpointName: string;
    /** Opaque endpoint identifier assigned by SES. */
    endpointId: string;
    /**
     * The endpoint's provisioning status at the time reconcile returned.
     * Provisioning is asynchronous and starts as `CREATING`; the endpoint is
     * not usable until it reaches `READY`. Reconcile does NOT wait for
     * `READY` — poll `getMultiRegionEndpoint` downstream if you need to block
     * on readiness.
     */
    status: MultiRegionEndpointStatus;
  },
  never,
  Providers
> {}

/**
 * An Amazon SES v2 multi-region endpoint (global endpoint) — a single sending
 * endpoint that splits email traffic across a primary region (where the
 * endpoint is created) and one or more secondary regions, improving
 * resilience and deliverability.
 *
 * :::note
 * Provisioning is asynchronous and can take a while: creation returns
 * immediately with status `CREATING`, and the endpoint only becomes usable
 * once it reaches `READY`. This resource does **not** wait for `READY` — the
 * `status` attribute reflects the value observed when reconcile returned.
 * Poll `getMultiRegionEndpoint` yourself if you need to block on readiness.
 * :::
 *
 * There is no update API, so any change to the name or routes replaces the
 * endpoint.
 * ### Creating Endpoints
 * **Example:** Two-Region Endpoint
 * ```typescript
 * import * as SES from "@alchemy.run/aws/SES";
 *
 * // The primary region is wherever the stack deploys; the route adds a
 * // secondary region.
 * const endpoint = yield* SES.MultiRegionEndpoint("Global", {
 *   regions: ["eu-west-1"],
 * });
 * ```
 *
 * **Example:** Three-Region Endpoint
 * ```typescript
 * // Traffic is split across the primary region plus every listed route.
 * const endpoint = yield* SES.MultiRegionEndpoint("Global", {
 *   regions: ["eu-west-1", "ap-southeast-2"],
 * });
 * ```
 *
 * **Example:** Explicit Endpoint Name
 * ```typescript
 * const endpoint = yield* SES.MultiRegionEndpoint("Global", {
 *   endpointName: "acme-global",
 *   regions: ["eu-west-1"],
 * });
 * ```
 *
 * ### Waiting for READY
 * **Example:** Poll Until the Endpoint Is Usable
 * ```typescript
 * import * as sesv2 from "@distilled.cloud/aws/sesv2";
 * import * as Effect from "effect/Effect";
 * import * as Schedule from "effect/Schedule";
 *
 * const endpoint = yield* SES.MultiRegionEndpoint("Global", {
 *   regions: ["eu-west-1"],
 * });
 *
 * // Reconcile returns as soon as SES accepts the create, so status is
 * // usually CREATING. Poll yourself when you need to block on readiness.
 * const ready = yield* sesv2
 *   .getMultiRegionEndpoint({ EndpointName: yield* endpoint.endpointName })
 *   .pipe(
 *     Effect.repeat({
 *       schedule: Schedule.spaced("30 seconds"),
 *       until: (r) => r.Status === "READY",
 *       times: 40,
 *     }),
 *   );
 * ```
 *
 * @resource
 */
export const MultiRegionEndpoint = Resource<MultiRegionEndpoint>("AWS.SES.MultiRegionEndpoint");

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

// getMultiRegionEndpoint returns no ARN, so the ARN listTagsForResource needs
// is derived from the endpoint NAME (not its id) — verified live.
const endpointArnOf = (region: string, accountId: string, name: string) =>
  `arn:aws:ses:${region}:${accountId}:multi-region-endpoint/${name}`;

const sameRegions = (
  a: ReadonlyArray<string> | undefined,
  b: ReadonlyArray<string> | undefined,
): boolean => {
  const key = (regions: ReadonlyArray<string> | undefined) =>
    JSON.stringify([...(regions ?? [])].sort());
  return key(a) === key(b);
};

export const MultiRegionEndpointProvider = () =>
  Provider.effect(
    MultiRegionEndpoint,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (
        id: string,
        props: Pick<MultiRegionEndpointProps, "endpointName">,
      ) {
        return props.endpointName ?? (yield* createPhysicalName({ id, maxLength: 64 }));
      });

      const getEndpoint = Effect.fn(function* (name: string) {
        return yield* sesv2
          .getMultiRegionEndpoint({ EndpointName: name })
          .pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
      });

      // getMultiRegionEndpoint does not return tags, so ownership costs a
      // second API call. Only `read` pays it — `list` deletes by name.
      const getEndpointTags = Effect.fn(function* (name: string) {
        const { accountId, region } = yield* AWSEnvironment.current;
        return yield* sesv2
          .listTagsForResource({
            ResourceArn: endpointArnOf(region, accountId, name),
          })
          .pipe(
            Effect.map((response) => toTagRecord(response.Tags)),
            Effect.catchTag("NotFoundException", () =>
              Effect.succeed({} as Record<string, string>),
            ),
          );
      });

      return MultiRegionEndpoint.Provider.of({
        stables: ["endpointName", "endpointId"],

        // Account/region-scoped: enumerate every endpoint so leaked test
        // resources are cleaned by nuke.
        list: Effect.fn(function* () {
          const pages = yield* sesv2.listMultiRegionEndpoints.pages({}).pipe(Stream.runCollect);
          return Array.from(pages)
            .flatMap((page) => page.MultiRegionEndpoints ?? [])
            .flatMap((entry) =>
              entry.EndpointName && entry.EndpointId
                ? [
                    {
                      endpointName: entry.EndpointName,
                      endpointId: entry.EndpointId,
                      status: entry.Status ?? "CREATING",
                    },
                  ]
                : [],
            );
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.endpointName ?? (yield* createName(id, olds ?? {}));
          const found = yield* getEndpoint(name);
          if (!found || !found.EndpointId) return undefined;
          const attrs = {
            endpointName: name,
            endpointId: found.EndpointId,
            status: found.Status ?? "CREATING",
          };
          // Endpoints are taggable and reconcile brands the ones it creates,
          // so existence at our deterministic name is not proof of ownership.
          const tags = yield* getEndpointTags(name);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createName(id, olds ?? {});
          const newName = yield* createName(id, news ?? {});
          // No update API: a rename or any routing change replaces the
          // endpoint.
          if (oldName !== newName || !sameRegions(olds?.regions, news.regions)) {
            return { action: "replace" } as const;
          }
        }),

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

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

          if (observed === undefined) {
            // 2. ENSURE — create; AlreadyExists is a race, not a failure.
            //    Provisioning is asynchronous: creation returns CREATING and we
            //    deliberately do NOT wait for READY (that exceeds the polling
            //    budget; downstream consumers poll if they need readiness).
            yield* sesv2
              .createMultiRegionEndpoint({
                EndpointName: name,
                Details: {
                  RoutesDetails: news.regions.map((region) => ({
                    Region: region,
                  })),
                },
                Tags: createTagsList(desiredTags),
              })
              .pipe(Effect.catchTag("AlreadyExistsException", () => Effect.succeed({})));
            // The endpoint is not always readable the instant create returns
            // (and on the AlreadyExists race another writer may still be
            // mid-create), so poll briefly rather than failing outright.
            observed = yield* getEndpoint(name).pipe(
              Effect.repeat({
                schedule: Schedule.spaced("1 second"),
                until: (endpoint) => endpoint !== undefined,
                times: 8,
              }),
            );
          }

          if (observed === undefined || !observed.EndpointId) {
            return yield* new MultiRegionEndpointUnexpectedResponse({
              message: `SES multi-region endpoint ${name} was not found after create`,
            });
          }

          // 3. SYNC TAGS — diff against OBSERVED cloud tags so an adopted
          //    endpoint gets branded and stops reading as Unowned.
          const observedTags = yield* getEndpointTags(name);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0 || removed.length > 0) {
            const { accountId, region } = yield* AWSEnvironment.current;
            const endpointArn = endpointArnOf(region, accountId, name);
            if (upsert.length > 0) {
              yield* sesv2.tagResource({
                ResourceArn: endpointArn,
                Tags: upsert,
              });
            }
            if (removed.length > 0) {
              yield* sesv2.untagResource({
                ResourceArn: endpointArn,
                TagKeys: removed,
              });
            }
          }

          yield* session.note(observed.EndpointId);
          return {
            endpointName: name,
            endpointId: observed.EndpointId,
            status: observed.Status ?? "CREATING",
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          // deleteMultiRegionEndpoint is idempotent for a missing endpoint.
          //
          // Provisioning is asynchronous and reconcile deliberately returns at
          // CREATING, so a destroy that follows closely enough hits an endpoint
          // still coming up: SES answers ConcurrentModificationException
          // ("Unable to delete resource in PROVISIONING status"). That is
          // eventual consistency, not a failure — retry on a bounded schedule
          // until the endpoint settles and the delete takes.
          yield* sesv2.deleteMultiRegionEndpoint({ EndpointName: output.endpointName }).pipe(
            Effect.retry({
              while: (e) => e._tag === "ConcurrentModificationException",
              schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(12)]),
            }),
            Effect.catchTag("NotFoundException", () => Effect.void),
          );
        }),
      });
    }),
  );