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

import * as ec2 from "@distilled.cloud/aws/ec2";
import { Unowned } from "alchemy/AdoptPolicy";
import * as Provider from "alchemy/Provider";
import type { ScopedPlanStatusSession } from "alchemy/Report";
import { Resource } from "alchemy/Resource";
import {
  createAlchemyTagFilters,
  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, type AccountID } from "../Environment.ts";
import { tagListRecord } from "../internal/Observe.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
import { getDefaultVpcScope } from "./defaultVpcScope.ts";
import { retryWhileLingeringEnis } from "./LingeringEnis.ts";
import type { VpcId } from "./Vpc.ts";

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

export interface InternetGatewayProps {
  /**
   * The VPC to attach the internet gateway to.
   * If provided, the internet gateway will be automatically attached to the VPC.
   * Optional - you can create an unattached internet gateway and attach it later.
   */
  vpcId?: VpcId;

  /**
   * Tags to assign to the internet gateway.
   * These will be merged with alchemy auto-tags (alchemy::stack, alchemy::stage, alchemy::id).
   */
  tags?: Record<string, string>;
}

export interface InternetGateway extends Resource<
  "AWS.EC2.InternetGateway",
  InternetGatewayProps,
  {
    /**
     * The ID of the internet gateway.
     */
    internetGatewayId: InternetGatewayId;
    /**
     * The Amazon Resource Name (ARN) of the internet gateway.
     */
    internetGatewayArn: `arn:aws:ec2:${RegionID}:${AccountID}:internet-gateway/${string}`;
    /**
     * The ID of the VPC the internet gateway is attached to (if any).
     */
    vpcId?: VpcId;
    /**
     * The ID of the AWS account that owns the internet gateway.
     */
    ownerId?: string;
    /**
     * The attachments for the internet gateway.
     */
    attachments?: Array<{
      state: "attaching" | "available" | "detaching" | "detached";
      vpcId: string;
    }>;
    /**
     * Tags on the internet gateway, as observed. Lets `alchemy drift`
     * detect out-of-band changes.
     */
    tags?: Record<string, string>;
  },
  never,
  Providers
> {}
/**
 * An internet gateway provides a target for internet-routable traffic in a
 * VPC, enabling bidirectional IPv4 and IPv6 connectivity between resources in
 * your VPC and the public internet. A VPC can have at most one internet
 * gateway attached at a time.
 *
 * The only inputs are the optional `vpcId` to attach to and `tags`. Attaching a
 * gateway is not enough on its own to make a subnet public — you also need a
 * `0.0.0.0/0` {@link Route} pointing at the gateway and a
 * {@link RouteTableAssociation} binding the subnet to that route table.
 *
 * ### Creating an Internet Gateway
 * Pass `vpcId` to create and attach the gateway in one step, or omit it to
 * create a standalone gateway and attach it later by setting the prop. Updating
 * `vpcId` moves the gateway between VPCs (detach then attach) without
 * recreating it.
 *
 * **Example:** Internet Gateway Attached to a VPC
 * ```typescript
 * const internetGateway = yield* AWS.EC2.InternetGateway("InternetGateway", {
 *   vpcId: myVpc.vpcId,
 * });
 * ```
 * Creates the gateway and attaches it to the VPC immediately. The resulting
 * `internetGatewayId` (prefixed `igw-`) is what you reference from a route's
 * `gatewayId`.
 *
 * **Example:** Detached Internet Gateway
 * ```typescript
 * const internetGateway = yield* AWS.EC2.InternetGateway("InternetGateway", {});
 * ```
 * Omitting `vpcId` creates an unattached gateway. This is occasionally useful
 * when the VPC is provisioned separately; add the `vpcId` prop later to attach
 * it.
 *
 * **Example:** Internet Gateway with Tags
 * ```typescript
 * const internetGateway = yield* AWS.EC2.InternetGateway("InternetGateway", {
 *   vpcId: myVpc.vpcId,
 *   tags: { Name: "production-igw" },
 * });
 * ```
 * The `tags` map is merged with the alchemy auto-tags and can be changed in
 * place. A `Name` tag makes the gateway easy to identify in the AWS console.
 *
 * ### Enabling Public Internet Access
 * An internet gateway only carries traffic once a route table sends traffic to
 * it and a subnet is associated with that table. The full pattern below makes a
 * subnet public.
 *
 * **Example:** Internet Gateway with a Default Route
 * ```typescript
 * const internetGateway = yield* AWS.EC2.InternetGateway("InternetGateway", {
 *   vpcId: myVpc.vpcId,
 * });
 *
 * const publicRouteTable = yield* AWS.EC2.RouteTable("PublicRouteTable", {
 *   vpcId: myVpc.vpcId,
 * });
 *
 * const internetRoute = yield* AWS.EC2.Route("InternetRoute", {
 *   routeTableId: publicRouteTable.routeTableId,
 *   destinationCidrBlock: "0.0.0.0/0",
 *   gatewayId: internetGateway.internetGatewayId,
 * });
 * ```
 * With the default route in place, any subnet associated with
 * `publicRouteTable` can send and receive internet traffic. Add an analogous
 * route with `destinationIpv6CidrBlock: "::/0"` to enable IPv6.
 *
 * @resource
 */
export const InternetGateway = Resource<InternetGateway>("AWS.EC2.InternetGateway");

export const InternetGatewayProvider = () =>
  Provider.effect(
    InternetGateway,
    Effect.gen(function* () {
      const findInternetGatewayByTags = Effect.fn(function* (id: string) {
        const filters = yield* createAlchemyTagFilters(id);
        const pages = yield* ec2.describeInternetGateways
          .pages({ Filters: filters })
          .pipe(Stream.runCollect);
        return Array.from(pages)
          .flatMap((page) => page.InternetGateways ?? [])
          .find((candidate) => candidate.InternetGatewayId !== undefined);
      });

      /**
       * The attributes `read` and `reconcile` both report, so a converged
       * gateway reads unchanged. The VPC is the one the gateway is attached
       * (or attaching) to.
       */
      const toAttributes = (
        igw: ec2.InternetGateway,
        region: RegionID,
        accountId: AccountID,
      ): InternetGateway["Attributes"] => {
        const internetGatewayId = igw.InternetGatewayId as InternetGatewayId;
        return {
          internetGatewayId,
          internetGatewayArn: `arn:aws:ec2:${region}:${accountId}:internet-gateway/${internetGatewayId}`,
          vpcId: igw.Attachments?.find((a) => a.State === "available" || a.State === "attaching")
            ?.VpcId as VpcId | undefined,
          ownerId: igw.OwnerId,
          attachments: igw.Attachments?.map((a) => ({
            state: a.State! as "attaching" | "available" | "detaching" | "detached",
            vpcId: a.VpcId!,
          })),
          tags: tagListRecord(igw.Tags),
        };
      };

      return {
        stables: ["internetGatewayId", "internetGatewayArn", "ownerId"],
        read: Effect.fn(function* ({ id, output }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const igw = output?.internetGatewayId
            ? (yield* ec2
                .describeInternetGateways({ InternetGatewayIds: [output.internetGatewayId] })
                .pipe(
                  Effect.catchTag("InvalidInternetGatewayID.NotFound", () =>
                    Effect.succeed({ InternetGateways: [] }),
                  ),
                )).InternetGateways?.[0]
            : yield* findInternetGatewayByTags(id);
          if (!igw?.InternetGatewayId) return undefined;
          const attrs = toAttributes(igw, region, accountId);
          return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
        }),

        list: () =>
          Effect.gen(function* () {
            const { accountId, region } = yield* AWSEnvironment.current;
            // The default VPC's internet gateway is account furniture AWS
            // provisions; never census/nuke it.
            const defaultVpc = yield* getDefaultVpcScope;
            return yield* ec2.describeInternetGateways.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((page) =>
                  (page.InternetGateways ?? [])
                    .filter(
                      (
                        igw,
                      ): igw is ec2.InternetGateway & {
                        InternetGatewayId: string;
                      } => igw.InternetGatewayId != null,
                    )
                    .filter(
                      (igw) =>
                        defaultVpc.vpcId === undefined ||
                        !igw.Attachments?.some((a) => a.VpcId === defaultVpc.vpcId),
                    )
                    .map((igw) => {
                      const internetGatewayId = igw.InternetGatewayId as InternetGatewayId;
                      const attachedVpcId = igw.Attachments?.find(
                        (a) => a.State === "available" || a.State === "attaching",
                      )?.VpcId as VpcId | undefined;
                      return {
                        internetGatewayId,
                        internetGatewayArn:
                          `arn:aws:ec2:${region}:${accountId}:internet-gateway/${internetGatewayId}` as const,
                        vpcId: attachedVpcId,
                        ownerId: igw.OwnerId,
                        attachments: igw.Attachments?.map((a) => ({
                          state: a.State! as "attaching" | "available" | "detaching" | "detached",
                          vpcId: a.VpcId!,
                        })),
                      };
                    }),
                ),
              ),
            );
          }),

        reconcile: Effect.fn(function* ({ id, instanceId, news = {}, output, session }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const alchemyTags = yield* createInternalTags(id);
          const desiredTags = {
            ...news.tags,
            ...alchemyTags,
            "alchemy::instance": instanceId,
          };

          // Observe — find the IGW via cached id, else fall through to create.
          let igw: ec2.InternetGateway | undefined;
          if (output?.internetGatewayId) {
            const lookup = yield* ec2
              .describeInternetGateways({
                InternetGatewayIds: [output.internetGatewayId],
              })
              .pipe(
                Effect.catchTag("InvalidInternetGatewayID.NotFound", () =>
                  Effect.succeed({ InternetGateways: [] }),
                ),
              );
            igw = lookup.InternetGateways?.[0];
          }
          if (igw === undefined) {
            // CreateInternetGateway has no idempotency token and this provider
            // never replaces an IGW. Recover a create that succeeded before
            // state persistence by stable stack/stage/logical-id ownership.
            // Older interrupted creates predate the instance tag, so requiring
            // it here would strand exactly the resources recovery must adopt.
            igw = yield* findInternetGatewayByTags(id);
          }

          // Ensure — create the IGW if missing.
          if (igw === undefined) {
            const createResult = yield* ec2.createInternetGateway({
              TagSpecifications: [
                {
                  ResourceType: "internet-gateway",
                  Tags: createTagsList(desiredTags),
                },
              ],
              DryRun: false,
            });
            const newIgwId = createResult.InternetGateway!.InternetGatewayId! as InternetGatewayId;
            yield* session.note(`Internet gateway created: ${newIgwId}`);
            // EC2 can return the new ID before DescribeInternetGateways sees
            // it. Retain and poll that ID rather than failing the reconcile
            // after creation and losing the cleanup handle.
            igw = yield* describeInternetGateway(newIgwId);
          }

          const internetGatewayId = igw.InternetGatewayId! as InternetGatewayId;

          // Sync VPC attachment — observed attachment vs desired.
          const attachedVpcId = igw.Attachments?.find(
            (a) => a.State === "available" || a.State === "attaching",
          )?.VpcId;
          if (attachedVpcId !== news.vpcId) {
            if (attachedVpcId) {
              yield* ec2
                .detachInternetGateway({
                  InternetGatewayId: internetGatewayId,
                  VpcId: attachedVpcId,
                })
                .pipe(Effect.catchTag("Gateway.NotAttached", () => Effect.void));
              yield* session.note(`Detached from VPC: ${attachedVpcId}`);
            }
            if (news.vpcId) {
              yield* ec2
                .attachInternetGateway({
                  InternetGatewayId: internetGatewayId,
                  VpcId: news.vpcId,
                })
                .pipe(
                  Effect.retry({
                    while: (e) =>
                      e._tag === "InvalidVpcID.NotFound" ||
                      e._tag === "InvalidInternetGatewayID.NotFound",
                    schedule: Schedule.max([Schedule.fixed(500), Schedule.recurs(10)]),
                  }),
                );
              yield* session.note(`Attached to VPC: ${news.vpcId}`);
            }
          }
          if (news.vpcId) {
            // AttachInternetGateway is asynchronous. Also check this when the
            // observed attachment was already `attaching`, as can happen when
            // a reconcile resumes after interruption. Do not publish outputs
            // to a dependent Route until AWS reports it as available.
            igw = yield* waitForInternetGatewayAttached(internetGatewayId, news.vpcId, session);
          }

          // Sync tags — observed cloud tags vs desired.
          const currentTags = Object.fromEntries(
            (igw.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: [internetGatewayId],
              Tags: removed.map((key) => ({ Key: key })),
            });
          }
          if (upsert.length > 0) {
            yield* ec2.createTags({
              Resources: [internetGatewayId],
              Tags: upsert,
            });
          }

          // Re-read final state.
          const final = yield* describeInternetGateway(internetGatewayId);
          return { ...toAttributes(final, region, accountId), tags: desiredTags };
        }),

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

          yield* session.note(`Deleting internet gateway: ${internetGatewayId}`);

          // Re-describe to get current attachments from AWS (don't rely on stored state)
          // This handles cases where state is incomplete from a previous crashed run
          const igw = yield* findInternetGateway(internetGatewayId);
          if (igw === undefined) {
            yield* session.note(`Internet gateway ${internetGatewayId} is already absent`);
            return;
          }
          const attachments = igw.Attachments ?? [];

          // 1. Detach from all VPCs first. DetachInternetGateway fails with
          // DependencyViolation ("has some mapped public address(es)") while
          // any ENI in the VPC still holds a public IP — a just-deleted VPC
          // Lambda's Hyperplane ENIs or draining Fargate task ENIs can hold
          // theirs for 5-20 minutes after the owner is gone. Ride that
          // window out on the same budget the subnet delete uses, reaping
          // detached Lambda ENIs between attempts to accelerate the release.
          if (attachments.length > 0) {
            for (const attachment of attachments) {
              yield* retryWhileLingeringEnis(
                ec2
                  .detachInternetGateway({
                    InternetGatewayId: internetGatewayId,
                    VpcId: attachment.VpcId!,
                  })
                  .pipe(
                    Effect.tapError(Effect.logDebug),
                    Effect.catchTags({
                      "Gateway.NotAttached": () => Effect.void,
                      "InvalidInternetGatewayID.NotFound": () => Effect.void,
                    }),
                  ),
                {
                  scope: { name: "vpc-id", value: attachment.VpcId! },
                  isDependencyViolation: (e) => e._tag === "DependencyViolation",
                  session,
                },
              );
              yield* session.note(`Detached from VPC: ${attachment.VpcId}`);
            }
          }

          // 2. Delete the internet gateway
          yield* ec2
            .deleteInternetGateway({
              InternetGatewayId: internetGatewayId,
              DryRun: false,
            })
            .pipe(
              Effect.tapError(Effect.logDebug),
              Effect.catchTag("InvalidInternetGatewayID.NotFound", () => Effect.void),
              // Retry on dependency violations. Public addresses on a
              // draining EKS/HyperPod control plane's ENIs can take
              // several minutes to release — 5s x 60 = ~5 min.
              Effect.retry({
                while: (e) =>
                  e._tag === "DependencyViolation" ||
                  (e._tag === "ValidationError" && e.message?.includes("DependencyViolation")),
                schedule: Schedule.max([Schedule.fixed(5000), Schedule.recurs(60)]).pipe(
                  Schedule.tap(({ attempt }) =>
                    session.note(`Waiting for dependencies to clear... (attempt ${attempt})`),
                  ),
                ),
              }),
            );

          // 3. Wait for internet gateway to be fully deleted
          yield* waitForInternetGatewayDeleted(internetGatewayId, session);

          yield* session.note(`Internet gateway ${internetGatewayId} deleted successfully`);
        }),
      };
    }),
  );

/**
 * Describe an internet gateway by ID
 */
const findInternetGateway = (internetGatewayId: string) =>
  Effect.gen(function* () {
    const result = yield* ec2
      .describeInternetGateways({ InternetGatewayIds: [internetGatewayId] })
      .pipe(
        Effect.catchTag("InvalidInternetGatewayID.NotFound", () =>
          Effect.succeed({ InternetGateways: [] }),
        ),
      );

    return result.InternetGateways?.[0];
  });

const describeInternetGateway = (internetGatewayId: string) =>
  findInternetGateway(internetGatewayId).pipe(
    Effect.flatMap((igw) =>
      igw ? Effect.succeed(igw) : Effect.fail(new InternetGatewayNotVisible({ internetGatewayId })),
    ),
    Effect.retry({
      while: (error) => error instanceof InternetGatewayNotVisible,
      schedule: Schedule.max([Schedule.fixed(500), Schedule.recurs(10)]),
    }),
  );

class InternetGatewayStillListed extends Data.TaggedError("InternetGatewayStillListed")<{
  internetGatewayId: string;
}> {}

class InternetGatewayNotVisible extends Data.TaggedError("InternetGatewayNotVisible")<{
  internetGatewayId: string;
}> {}

class InternetGatewayAttachmentPending extends Data.TaggedError(
  "InternetGatewayAttachmentPending",
)<{
  internetGatewayId: string;
  vpcId: string;
  state: string;
}> {}

const waitForInternetGatewayAttached = (
  internetGatewayId: string,
  vpcId: string,
  session: ScopedPlanStatusSession,
) =>
  Effect.gen(function* () {
    const igw = yield* describeInternetGateway(internetGatewayId);
    const attachment = igw.Attachments?.find((candidate) => candidate.VpcId === vpcId);
    if (attachment?.State === "available") {
      return igw;
    }
    return yield* new InternetGatewayAttachmentPending({
      internetGatewayId,
      vpcId,
      state: attachment?.State ?? "missing",
    });
  }).pipe(
    Effect.retry({
      while: (error) => error instanceof InternetGatewayAttachmentPending,
      schedule: Schedule.max([Schedule.fixed(1000), Schedule.recurs(30)]).pipe(
        Schedule.tap(({ attempt }) =>
          session.note(
            `Waiting for internet gateway attachment to become available... (${attempt}s)`,
          ),
        ),
      ),
    }),
  );

/**
 * Wait for internet gateway to be deleted
 */
const waitForInternetGatewayDeleted = (
  internetGatewayId: string,
  session: ScopedPlanStatusSession,
) =>
  Effect.retry(
    Effect.gen(function* () {
      const result = yield* ec2
        .describeInternetGateways({ InternetGatewayIds: [internetGatewayId] })
        .pipe(
          Effect.tapError(Effect.logDebug),
          Effect.catchTag("InvalidInternetGatewayID.NotFound", () =>
            Effect.succeed({ InternetGateways: [] }),
          ),
        );

      if (!result.InternetGateways || result.InternetGateways.length === 0) {
        return; // Successfully deleted
      }

      // Still listed: EC2 is eventually consistent after a delete.
      return yield* new InternetGatewayStillListed({ internetGatewayId });
    }),
    {
      while: (error) => error._tag === "InternetGatewayStillListed",
      // EC2 can keep listing a deleted gateway for minutes, so bound the
      // wait like NatGateway: 5s x 60 = ~5 min.
      schedule: Schedule.max([Schedule.fixed(5000), Schedule.recurs(60)]).pipe(
        Schedule.tap(({ attempt }) =>
          session.note(`Waiting for internet gateway deletion... (${attempt * 5}s)`),
        ),
      ),
    },
  );