sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ EC2/ EIP.ts

import * as ec2 from "@distilled.cloud/aws/ec2";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, createTagsList, diffTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import type { AccountID } from "../Environment.ts";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";

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

export type EIPArn = `arn:aws:ec2:${RegionID}:${AccountID}:elastic-ip/${AllocationId}`;

export type AllocationId<ID extends string = string> = `eipalloc-${ID}`;
export const AllocationId = <ID extends string>(id: ID): ID & AllocationId<ID> =>
  `eipalloc-${id}` as ID & AllocationId<ID>;

export interface EIPProps {
  /**
   * Indicates whether the Elastic IP address is for use with instances in a VPC or EC2-Classic.
   * @default "vpc"
   */
  domain?: "vpc" | "standard";

  /**
   * The ID of an address pool that you own.
   * Use this parameter to let Amazon EC2 select an address from the address pool.
   */
  publicIpv4Pool?: string;

  /**
   * A unique set of Availability Zones, Local Zones, or Wavelength Zones
   * from which AWS advertises IP addresses.
   */
  networkBorderGroup?: string;

  /**
   * The ID of a customer-owned address pool.
   * Use this parameter to let Amazon EC2 select an address from the address pool.
   */
  customerOwnedIpv4Pool?: string;

  /**
   * Tags to assign to the Elastic IP.
   * These will be merged with alchemy auto-tags.
   */
  tags?: Record<string, string>;
}

export interface EIP extends Resource<
  "AWS.EC2.EIP",
  EIPProps,
  {
    /**
     * The allocation ID for the Elastic IP address.
     */
    allocationId: AllocationId;

    /**
     * The Amazon Resource Name (ARN) of the Elastic IP.
     */
    eipArn: `arn:aws:ec2:${RegionID}:${AccountID}:elastic-ip/${string}`;

    /**
     * The Elastic IP address.
     */
    publicIp: string;

    /**
     * The ID of an address pool.
     */
    publicIpv4Pool?: string;

    /**
     * Indicates whether the Elastic IP address is for use with instances in a VPC or EC2-Classic.
     */
    domain: "vpc" | "standard";

    /**
     * The network border group.
     */
    networkBorderGroup?: string;

    /**
     * The customer-owned IP address.
     */
    customerOwnedIp?: string;

    /**
     * The ID of the customer-owned address pool.
     */
    customerOwnedIpv4Pool?: string;

    /**
     * The carrier IP address associated with the network interface.
     */
    carrierIp?: string;
  },
  never,
  Providers
> {}
/**
 * An Elastic IP address — a static, public IPv4 address allocated to your AWS
 * account that you can attach to instances, network interfaces, or NAT
 * gateways.
 *
 * Allocating an `EIP` reserves the address; you then reference its
 * `allocationId` from the resource that should use it (for example a public
 * `NatGateway`). The address is released back to AWS when the resource is
 * destroyed. The pool-related properties (`publicIpv4Pool`,
 * `networkBorderGroup`, `customerOwnedIpv4Pool`) are immutable and replace the
 * address when changed.
 *
 * ### Allocating Elastic IPs
 * By default an Elastic IP is allocated for use within a VPC (`domain: "vpc"`),
 * which is the only domain available to modern accounts.
 * **Example:** VPC-Scoped Elastic IP
 * ```typescript
 * const eip = yield* AWS.EC2.EIP("MyEip", {
 *   domain: "vpc",
 *   tags: { Name: "app-eip" },
 * });
 * ```
 * This reserves a standard, Amazon-owned public IPv4 address scoped to your VPC;
 * `domain` defaults to `"vpc"`, so it can be omitted, and `tags` help you find
 * the address in the console and on the bill.
 *
 * ### Bring-Your-Own-IP and Address Pools
 * If you have onboarded an address range to AWS (BYOIP) or use Outposts, you can
 * draw the address from a specific pool instead of Amazon's general pool.
 * **Example:** Allocate from a Public IPv4 (BYOIP) Pool
 * ```typescript
 * const eip = yield* AWS.EC2.EIP("ByoipEip", {
 *   publicIpv4Pool: "ipv4pool-ec2-0abcdef1234567890",
 *   networkBorderGroup: "us-east-1",
 * });
 * ```
 * `publicIpv4Pool` selects an address from a pool you own rather than a random
 * Amazon address, and `networkBorderGroup` restricts which zone group AWS
 * advertises it from (useful for Local and Wavelength Zones).
 *
 * **Example:** Allocate from a Customer-Owned Pool (Outposts)
 * ```typescript
 * const eip = yield* AWS.EC2.EIP("CoIpEip", {
 *   customerOwnedIpv4Pool: "ipv4pool-coip-0abcdef1234567890",
 * });
 * ```
 * `customerOwnedIpv4Pool` pulls a customer-owned IP (CoIP) from an
 * Outposts-associated pool, for workloads that must use your own on-premises
 * address space.
 *
 * ### Using an Elastic IP
 * **Example:** Attach to a NAT Gateway
 * ```typescript
 * const eip = yield* AWS.EC2.EIP("NatEip", {});
 *
 * const natGateway = yield* AWS.EC2.NatGateway("NatGateway", {
 *   subnetId: publicSubnet.subnetId,
 *   allocationId: eip.allocationId,
 * });
 * ```
 * Downstream resources consume the reserved address through its `allocationId`;
 * here the EIP becomes the fixed public IP of a NAT gateway.
 *
 * @resource
 */
export const EIP = Resource<EIP>("AWS.EC2.EIP");

export const EIPProvider = () =>
  Provider.effect(
    EIP,
    Effect.gen(function* () {
      const createTags = Effect.fn(function* (id: string, tags?: Record<string, string>) {
        return {
          Name: id,
          ...(yield* createInternalTags(id)),
          ...tags,
        };
      });

      return {
        stables: ["allocationId", "eipArn", "publicIp"],

        list: () =>
          Effect.gen(function* () {
            const { region, accountId } = yield* AWSEnvironment.current;
            // describeAddresses is non-paginated and returns every Elastic IP
            // in the account/region in a single response.
            const result = yield* ec2.describeAddresses({});
            return (result.Addresses ?? [])
              .filter((a): a is ec2.Address & { AllocationId: string } => a.AllocationId != null)
              .map((address): EIP["Attributes"] => ({
                allocationId: address.AllocationId as AllocationId,
                eipArn:
                  `arn:aws:ec2:${region}:${accountId}:elastic-ip/${address.AllocationId}` as EIPArn,
                publicIp: address.PublicIp!,
                publicIpv4Pool: address.PublicIpv4Pool,
                domain: (address.Domain as "vpc" | "standard") ?? "vpc",
                networkBorderGroup: address.NetworkBorderGroup,
                customerOwnedIp: address.CustomerOwnedIp,
                customerOwnedIpv4Pool: address.CustomerOwnedIpv4Pool,
                carrierIp: address.CarrierIp,
              }));
          }),

        read: Effect.fn(function* ({ output }) {
          const { region, accountId } = yield* AWSEnvironment.current;

          if (!output) return undefined;
          const result = yield* ec2.describeAddresses({
            AllocationIds: [output.allocationId],
          });

          const address = result.Addresses?.[0];
          if (!address) {
            return yield* new EIPUnexpectedResponse({
              message: `EIP ${output.allocationId} not found`,
            });
          }

          return {
            allocationId: address.AllocationId as AllocationId,
            eipArn:
              `arn:aws:ec2:${region}:${accountId}:elastic-ip/${address.AllocationId}` as EIPArn,
            publicIp: address.PublicIp!,
            publicIpv4Pool: address.PublicIpv4Pool,
            domain: (address.Domain as "vpc" | "standard") ?? "vpc",
            networkBorderGroup: address.NetworkBorderGroup,
            customerOwnedIp: address.CustomerOwnedIp,
            customerOwnedIpv4Pool: address.CustomerOwnedIpv4Pool,
            carrierIp: address.CarrierIp,
          } satisfies EIP["Attributes"];
        }),

        diff: Effect.fn(function* ({ news = {}, olds = {} }) {
          if (!isResolved(news)) return;
          // EIPs are immutable - any change to core properties requires replacement
          if (
            news.publicIpv4Pool !== olds.publicIpv4Pool ||
            news.networkBorderGroup !== olds.networkBorderGroup ||
            news.customerOwnedIpv4Pool !== olds.customerOwnedIpv4Pool
          ) {
            return { action: "replace" };
          }
          // Tags can be updated in-place
        }),

        reconcile: Effect.fn(function* ({ id, news = {}, output, session }) {
          const { region, accountId } = yield* AWSEnvironment.current;

          const desiredTags = yield* createTags(id, news.tags);

          // Observe — try to find an existing EIP via the cached allocationId.
          // If it was released out-of-band, fall through to allocate.
          let address: ec2.Address | undefined;
          if (output?.allocationId) {
            const lookup = yield* ec2
              .describeAddresses({ AllocationIds: [output.allocationId] })
              .pipe(
                Effect.catchTag("InvalidAllocationID.NotFound", () =>
                  Effect.succeed({ Addresses: [] }),
                ),
              );
            address = lookup.Addresses?.[0];
          }

          // Ensure — allocate a new EIP when none was observed.
          if (address === undefined) {
            yield* session.note("Allocating Elastic IP address...");
            const result = yield* ec2.allocateAddress({
              Domain: news.domain ?? "vpc",
              PublicIpv4Pool: news.publicIpv4Pool,
              NetworkBorderGroup: news.networkBorderGroup,
              CustomerOwnedIpv4Pool: news.customerOwnedIpv4Pool,
              TagSpecifications: [
                {
                  ResourceType: "elastic-ip",
                  Tags: createTagsList(desiredTags),
                },
              ],
              DryRun: false,
            });
            const allocationId = result.AllocationId! as AllocationId;
            yield* session.note(`Elastic IP allocated: ${allocationId}`);
            const lookup = yield* ec2.describeAddresses({
              AllocationIds: [allocationId],
            });
            address = lookup.Addresses?.[0];
            if (!address) {
              return yield* new EIPUnexpectedResponse({
                message: `EIP ${allocationId} disappeared after allocation`,
              });
            }
          }

          const allocationId = address.AllocationId! as AllocationId;

          // Sync tags — observed cloud tags vs desired.
          const currentTags = Object.fromEntries(
            (address.Tags ?? []).map((t) => [t.Key!, t.Value!]),
          ) as Record<string, string>;
          const { removed, upsert } = diffTags(currentTags, desiredTags);
          if (removed.length > 0) {
            yield* ec2.deleteTags({
              Resources: [allocationId],
              Tags: removed.map((key) => ({ Key: key })),
              DryRun: false,
            });
          }
          if (upsert.length > 0) {
            yield* ec2.createTags({
              Resources: [allocationId],
              Tags: upsert,
              DryRun: false,
            });
          }

          return {
            allocationId,
            eipArn: `arn:aws:ec2:${region}:${accountId}:elastic-ip/${allocationId}` as EIPArn,
            publicIp: address.PublicIp!,
            publicIpv4Pool: address.PublicIpv4Pool,
            domain: (address.Domain as "vpc" | "standard") ?? "vpc",
            networkBorderGroup: address.NetworkBorderGroup,
            customerOwnedIp: address.CustomerOwnedIp,
            customerOwnedIpv4Pool: address.CustomerOwnedIpv4Pool,
            carrierIp: address.CarrierIp,
          } satisfies EIP["Attributes"];
        }),

        delete: Effect.fn(function* ({ output, session }) {
          const allocationId = output.allocationId;

          yield* session.note(`Releasing Elastic IP: ${allocationId}`);

          yield* ec2
            .releaseAddress({
              AllocationId: allocationId,
              DryRun: false,
            })
            .pipe(
              Effect.catchTags({
                "InvalidAllocationID.NotFound": () => Effect.void,
                AuthFailure: () => Effect.void,
              }),
              Effect.tapError(Effect.logDebug),
              // Retry when EIP is still in use (e.g., NAT Gateway being deleted)
              Effect.retry({
                while: (e) =>
                  // TODO(sam): not sure if the API will actually throw this
                  // e._tag === "DependencyViolation" ||
                  // this throws if the address hasn't been disassociated from all resources
                  // we will retry it assuming that another resource provider is dissassociating it (e.g. a NAT Gateway resource is being deleted)
                  e._tag === "InvalidIPAddress.InUse",
                schedule: Schedule.max([Schedule.exponential(1000, 1.5), Schedule.recurs(20)]).pipe(
                  Schedule.tap(({ attempt }) =>
                    session.note(`EIP still in use, waiting for release... (attempt ${attempt})`),
                  ),
                ),
              }),
            );

          yield* session.note(`Elastic IP ${allocationId} released`);
        }),
      };
    }),
  );