sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ SES/ DedicatedIpPool.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 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";

/**
 * The pool's scaling mode. `STANDARD` pools use a fixed set of dedicated IPs
 * you request and warm up yourself; `MANAGED` pools let SES automatically
 * scale the dedicated IP capacity for you.
 */
export type DedicatedIpPoolScalingMode = sesv2.ScalingMode;

export interface DedicatedIpPoolProps {
  /**
   * Name of the dedicated IP pool. May contain lowercase letters, numbers and
   * dashes, up to 64 characters. If omitted, a deterministic lowercase
   * physical name is generated from the app, stage, and logical ID. Changing
   * the name replaces the pool.
   */
  poolName?: string;
  /**
   * The pool's scaling mode. Switching `STANDARD` → `MANAGED` is applied in
   * place via `putDedicatedIpPoolScalingAttributes`; AWS does not support
   * `MANAGED` → `STANDARD`, so that direction replaces the pool.
   * @default "STANDARD"
   */
  scalingMode?: DedicatedIpPoolScalingMode;
  /**
   * Tags to apply to the pool. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface DedicatedIpPool extends Resource<
  "AWS.SES.DedicatedIpPool",
  DedicatedIpPoolProps,
  {
    /** Name of the dedicated IP pool. */
    poolName: string;
    /** The pool's scaling mode. */
    scalingMode: DedicatedIpPoolScalingMode;
  },
  never,
  Providers
> {}

/**
 * An Amazon SES v2 dedicated IP pool — a named group of dedicated IP addresses
 * used to send email, so you can isolate the sending reputation of different
 * kinds of mail (e.g. marketing vs. transactional).
 *
 * :::caution
 * Creating a dedicated IP pool provisions dedicated IP capacity and **starts
 * billing immediately** — `MANAGED` pools bill for managed dedicated IP usage
 * as soon as they exist, and `STANDARD` pools bill per dedicated IP you add.
 * Only create pools you intend to pay for.
 * :::
 *
 * `STANDARD` → `MANAGED` is an in-place scaling change. `MANAGED` → `STANDARD`
 * is not supported by AWS and replaces the pool.
 * ### Creating Pools
 * **Example:** Standard Pool
 * ```typescript
 * import * as SES from "@alchemy.run/aws/SES";
 *
 * const pool = yield* SES.DedicatedIpPool("Marketing", {
 *   scalingMode: "STANDARD",
 * });
 * ```
 *
 * **Example:** Managed Pool
 * ```typescript
 * const pool = yield* SES.DedicatedIpPool("Transactional", {
 *   scalingMode: "MANAGED",
 * });
 * ```
 *
 * **Example:** Explicit Pool Name
 * ```typescript
 * // Without poolName a deterministic lowercase name is derived from
 * // app/stage/id. Pool names allow lowercase letters, numbers, and dashes.
 * const pool = yield* SES.DedicatedIpPool("Marketing", {
 *   poolName: "acme-marketing",
 * });
 * ```
 *
 * ### Changing the Scaling Mode
 * **Example:** Migrate a Standard Pool to Managed
 * ```typescript
 * // STANDARD -> MANAGED is applied in place — the pool keeps its name and
 * // its dedicated IPs.
 * const pool = yield* SES.DedicatedIpPool("Marketing", {
 *   scalingMode: "MANAGED", // was "STANDARD"
 * });
 *
 * // MANAGED -> STANDARD has no AWS API, so it REPLACES the pool: a new pool
 * // is created and the old one deleted, dropping its dedicated IPs.
 * ```
 *
 * ### Isolating Reputation
 * **Example:** Separate Marketing and Transactional Reputation
 * ```typescript
 * // Give each kind of mail its own pool so a marketing reputation hit
 * // cannot take down password resets.
 * const marketing = yield* SES.DedicatedIpPool("Marketing", {
 *   scalingMode: "STANDARD",
 * });
 * const transactional = yield* SES.DedicatedIpPool("Transactional", {
 *   scalingMode: "MANAGED",
 * });
 * ```
 *
 * @resource
 */
export const DedicatedIpPool = Resource<DedicatedIpPool>("AWS.SES.DedicatedIpPool");

const DEFAULT_SCALING_MODE = "STANDARD" as const;

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

// Dedicated IP pools are taggable but their API never returns an ARN — not
// from getDedicatedIpPool, not from listDedicatedIpPools — so the ARN that
// listTagsForResource requires has to be derived.
const dedicatedIpPoolArnOf = (region: string, accountId: string, name: string) =>
  `arn:aws:ses:${region}:${accountId}:dedicated-ip-pool/${name}`;

export const DedicatedIpPoolProvider = () =>
  Provider.effect(
    DedicatedIpPool,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (
        id: string,
        props: Pick<DedicatedIpPoolProps, "poolName">,
      ) {
        return (
          props.poolName ?? (yield* createPhysicalName({ id, maxLength: 64, lowercase: true }))
        );
      });

      const getPool = Effect.fn(function* (name: string) {
        return yield* sesv2.getDedicatedIpPool({ PoolName: name }).pipe(
          Effect.map((response) => response.DedicatedIpPool),
          Effect.catchTag("NotFoundException", () => Effect.undefined),
        );
      });

      // getDedicatedIpPool does not return tags, so ownership costs a second
      // API call. Only `read` pays it — `list` deletes by name and does not
      // need to know who owns a pool.
      const getPoolTags = Effect.fn(function* (name: string) {
        const { accountId, region } = yield* AWSEnvironment.current;
        return yield* sesv2
          .listTagsForResource({
            ResourceArn: dedicatedIpPoolArnOf(region, accountId, name),
          })
          .pipe(
            Effect.map((response) => toTagRecord(response.Tags)),
            // The pool went away between the two calls.
            Effect.catchTag("NotFoundException", () =>
              Effect.succeed({} as Record<string, string>),
            ),
          );
      });

      return DedicatedIpPool.Provider.of({
        stables: ["poolName"],

        // Account/region-scoped: enumerate every pool so leaked test resources
        // are cleaned by nuke.
        //
        // listDedicatedIpPools returns names only, so the real ScalingMode
        // needs a read per pool — `list` must produce the same Attributes
        // shape as `read`, and reporting every pool as STANDARD would
        // misdescribe a MANAGED one. Pools that vanish mid-walk drop out.
        list: Effect.fn(function* () {
          const pages = yield* sesv2.listDedicatedIpPools.pages({}).pipe(Stream.runCollect);
          const poolNames = Array.from(pages).flatMap((page) => page.DedicatedIpPools ?? []);
          const pools = yield* Effect.forEach(
            poolNames,
            (poolName) =>
              getPool(poolName).pipe(
                Effect.map((pool) => (pool ? [{ poolName, scalingMode: pool.ScalingMode }] : [])),
              ),
            { concurrency: 2 },
          );
          return pools.flat();
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.poolName ?? (yield* createName(id, olds ?? {}));
          const found = yield* getPool(name);
          if (!found) return undefined;
          const attrs = { poolName: name, scalingMode: found.ScalingMode };
          // A pool provisions billable dedicated IP capacity, and reconcile
          // brands the ones it creates with internal tags. So existence at our
          // deterministic name is NOT proof of ownership — a pre-existing pool
          // someone else pays for must be adopted deliberately (`--adopt` /
          // `adopt(true)`) rather than silently taken over.
          const tags = yield* getPoolTags(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 ?? {});
          const oldMode = olds?.scalingMode ?? DEFAULT_SCALING_MODE;
          const newMode = news?.scalingMode ?? DEFAULT_SCALING_MODE;
          // A rename replaces the pool. So does a MANAGED → STANDARD switch,
          // which AWS has no API to perform in place (STANDARD → MANAGED is a
          // supported in-place scaling change, handled in reconcile).
          if (oldName !== newName || (oldMode === "MANAGED" && newMode === "STANDARD")) {
            return { action: "replace" } as const;
          }
        }),

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

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

          if (observed === undefined) {
            // 2. ENSURE — create with the desired scaling mode, branding the
            //    pool with internal tags. AlreadyExists is a race, not a
            //    failure.
            yield* sesv2
              .createDedicatedIpPool({
                PoolName: name,
                ScalingMode: desiredMode,
                Tags: createTagsList(desiredTags),
              })
              .pipe(Effect.catchTag("AlreadyExistsException", () => Effect.succeed({})));
            // Not always readable the instant create returns, and on the
            // AlreadyExists race another writer may still be mid-create.
            observed = yield* getPool(name).pipe(
              Effect.repeat({
                schedule: Schedule.spaced("1 second"),
                until: (pool) => pool !== undefined,
                times: 8,
              }),
            );
          }

          // 3. SYNC — the only in-place scaling change AWS supports is
          //    STANDARD → MANAGED (MANAGED → STANDARD is a replacement, gated
          //    in diff above).
          if (observed?.ScalingMode !== desiredMode) {
            yield* sesv2.putDedicatedIpPoolScalingAttributes({
              PoolName: name,
              ScalingMode: desiredMode,
            });
          }

          // 3b. SYNC TAGS — brand the pool if it is not already ours. An
          //     adopted pool reaches this point without ever passing through
          //     the create above, so without this it would stay unbranded and
          //     `read` would keep reporting it Unowned on every later deploy.
          //     Diffed against OBSERVED cloud tags, never against olds.
          const observedTags = yield* getPoolTags(name);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0 || removed.length > 0) {
            const { accountId, region } = yield* AWSEnvironment.current;
            const poolArn = dedicatedIpPoolArnOf(region, accountId, name);
            if (upsert.length > 0) {
              yield* sesv2.tagResource({ ResourceArn: poolArn, Tags: upsert });
            }
            if (removed.length > 0) {
              yield* sesv2.untagResource({
                ResourceArn: poolArn,
                TagKeys: removed,
              });
            }
          }

          return { poolName: name, scalingMode: desiredMode };
        }),

        delete: Effect.fn(function* ({ output }) {
          // deleteDedicatedIpPool is idempotent for a missing pool.
          yield* sesv2
            .deleteDedicatedIpPool({ PoolName: output.poolName })
            .pipe(Effect.catchTag("NotFoundException", () => Effect.void));
        }),
      });
    }),
  );