sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ EC2/ EgressOnlyInternetGateway.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 * as Stream from "effect/Stream";
import type { AccountID } from "../Environment.ts";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
import type { VpcId } from "./Vpc.ts";

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

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

export type EgressOnlyInternetGatewayArn<
  ID extends EgressOnlyInternetGatewayId = EgressOnlyInternetGatewayId,
> = `arn:aws:ec2:${RegionID}:${AccountID}:egress-only-internet-gateway/${ID}`;

export interface EgressOnlyInternetGatewayProps {
  /**
   * The VPC for which to create the egress-only internet gateway.
   */
  vpcId: VpcId;

  /**
   * Tags to assign to the egress-only internet gateway.
   */
  tags?: Record<string, string>;
}

export interface EgressOnlyInternetGateway extends Resource<
  "AWS.EC2.EgressOnlyInternetGateway",
  EgressOnlyInternetGatewayProps,
  {
    /**
     * The ID of the egress-only internet gateway.
     */
    egressOnlyInternetGatewayId: EgressOnlyInternetGatewayId;

    /**
     * The Amazon Resource Name (ARN) of the egress-only internet gateway.
     */
    egressOnlyInternetGatewayArn: EgressOnlyInternetGatewayArn;

    /**
     * Information about the attachment of the egress-only internet gateway.
     */
    attachments?: Array<{
      /**
       * The current state of the attachment.
       */
      state: "attaching" | "attached" | "detaching" | "detached";
      /**
       * The ID of the VPC.
       */
      vpcId: VpcId;
    }>;
  },
  never,
  Providers
> {}
/**
 * An egress-only internet gateway is the IPv6 counterpart to a NAT gateway: it
 * lets instances in a VPC initiate outbound IPv6 traffic to the internet while
 * preventing the internet from initiating inbound connections to them. Use it
 * to give private, IPv6-addressed resources outbound-only internet access.
 *
 * Unlike a NAT gateway it is free, has no bandwidth charges, and does not
 * require an Elastic IP — but it works for IPv6 only. It always belongs to a
 * VPC (`vpcId` is required); the gateway must be paired with an IPv6
 * {@link Route} to actually carry traffic.
 *
 * ### Creating an Egress-Only Internet Gateway
 * The gateway is created and attached to `vpcId` in a single step. Because the
 * attachment is intrinsic, changing `vpcId` replaces the gateway rather than
 * moving it.
 *
 * **Example:** Basic Egress-Only Internet Gateway
 * ```typescript
 * const egressOnlyIgw = yield* AWS.EC2.EgressOnlyInternetGateway("EgressOnlyIgw", {
 *   vpcId: myVpc.vpcId,
 * });
 * ```
 * Creates the gateway in the VPC. The resulting
 * `egressOnlyInternetGatewayId` (prefixed `eigw-`) is referenced from a
 * route's `egressOnlyInternetGatewayId` target.
 *
 * **Example:** Egress-Only Internet Gateway with Tags
 * ```typescript
 * const egressOnlyIgw = yield* AWS.EC2.EgressOnlyInternetGateway("EgressOnlyIgw", {
 *   vpcId: myVpc.vpcId,
 *   tags: { Name: "production-eigw" },
 * });
 * ```
 * The `tags` map is merged with the alchemy auto-tags and can be updated in
 * place without replacing the gateway.
 *
 * ### Routing IPv6 Egress Traffic
 * A gateway alone does nothing until a private route table sends IPv6 traffic
 * to it. Pair it with a `::/0` {@link Route} so private, IPv6-addressed
 * instances can reach the internet outbound-only.
 *
 * **Example:** IPv6 Default Route to the Egress-Only Gateway
 * ```typescript
 * const egressOnlyIgw = yield* AWS.EC2.EgressOnlyInternetGateway("EgressOnlyIgw", {
 *   vpcId: myVpc.vpcId,
 * });
 *
 * const ipv6EgressRoute = yield* AWS.EC2.Route("Ipv6EgressRoute", {
 *   routeTableId: privateRouteTable.routeTableId,
 *   destinationIpv6CidrBlock: "::/0",
 *   egressOnlyInternetGatewayId: egressOnlyIgw.egressOnlyInternetGatewayId,
 * });
 * ```
 * Instances in subnets associated with `privateRouteTable` can now make
 * outbound IPv6 connections (updates, API calls) while remaining unreachable
 * from the public internet.
 *
 * @resource
 */
export const EgressOnlyInternetGateway = Resource<EgressOnlyInternetGateway>(
  "AWS.EC2.EgressOnlyInternetGateway",
);

/** `DeleteEgressOnlyInternetGateway` returned `ReturnCode: false` (no error). */
class EigwDeleteFailed extends Data.TaggedError("EigwDeleteFailed")<{
  readonly eigwId: string;
}> {}

/** The gateway is still observable after a successful delete call. */
class EigwStillExists extends Data.TaggedError("EigwStillExists")<{
  readonly eigwId: string;
}> {}

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

      const describeEgressOnlyInternetGateway = (eigwId: string) =>
        ec2
          .describeEgressOnlyInternetGateways({
            EgressOnlyInternetGatewayIds: [eigwId],
          })
          .pipe(
            Effect.map((r) => r.EgressOnlyInternetGateways?.[0]),
            Effect.flatMap((gw) =>
              gw
                ? Effect.succeed(gw)
                : Effect.fail(
                    new EgressOnlyInternetGatewayUnexpectedResponse({
                      message: `Egress-Only Internet Gateway ${eigwId} not found`,
                    }),
                  ),
            ),
          );

      const toAttrs = (gw: ec2.EgressOnlyInternetGateway) =>
        AWSEnvironment.current.pipe(
          Effect.map((env) => ({
            egressOnlyInternetGatewayId:
              gw.EgressOnlyInternetGatewayId as EgressOnlyInternetGatewayId,
            egressOnlyInternetGatewayArn:
              `arn:aws:ec2:${env.region}:${env.accountId}:egress-only-internet-gateway/${gw.EgressOnlyInternetGatewayId}` as EgressOnlyInternetGatewayArn,
            attachments: gw.Attachments?.map((a) => ({
              state: a.State as "attaching" | "attached" | "detaching" | "detached",
              vpcId: a.VpcId as VpcId,
            })),
          })),
        );

      return {
        stables: ["egressOnlyInternetGatewayId", "egressOnlyInternetGatewayArn"],

        list: () =>
          Effect.gen(function* () {
            const env = yield* AWSEnvironment.current;
            const items = yield* ec2.describeEgressOnlyInternetGateways.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((page) =>
                  (page.EgressOnlyInternetGateways ?? [])
                    .filter(
                      (
                        gw,
                      ): gw is ec2.EgressOnlyInternetGateway & {
                        EgressOnlyInternetGatewayId: string;
                      } => gw.EgressOnlyInternetGatewayId != null,
                    )
                    .map((gw) => ({
                      egressOnlyInternetGatewayId:
                        gw.EgressOnlyInternetGatewayId as EgressOnlyInternetGatewayId,
                      egressOnlyInternetGatewayArn:
                        `arn:aws:ec2:${env.region}:${env.accountId}:egress-only-internet-gateway/${gw.EgressOnlyInternetGatewayId}` as EgressOnlyInternetGatewayArn,
                      attachments: gw.Attachments?.map((a) => ({
                        state: a.State as "attaching" | "attached" | "detaching" | "detached",
                        vpcId: a.VpcId as VpcId,
                      })),
                    })),
                ),
              ),
            );
            return items satisfies EgressOnlyInternetGateway["Attributes"][];
          }),

        read: Effect.fn(function* ({ output }) {
          if (!output) return undefined;
          const gw = yield* describeEgressOnlyInternetGateway(output.egressOnlyInternetGatewayId);
          return yield* toAttrs(gw);
        }),

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return;
          // VPC change requires replacement
          if (news.vpcId !== olds.vpcId) {
            return { action: "replace" };
          }
          // Tags can be updated in-place
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const desiredTags = yield* createTags(id, news.tags);

          // Observe — find the EIGW via cached id, else fall through to create.
          let gw: ec2.EgressOnlyInternetGateway | undefined;
          if (output?.egressOnlyInternetGatewayId) {
            const lookup = yield* ec2
              .describeEgressOnlyInternetGateways({
                EgressOnlyInternetGatewayIds: [output.egressOnlyInternetGatewayId],
              })
              .pipe(
                Effect.catchTag("InvalidEgressOnlyInternetGatewayId.NotFound", () =>
                  Effect.succeed({ EgressOnlyInternetGateways: [] }),
                ),
              );
            gw = lookup.EgressOnlyInternetGateways?.[0];
          }

          // Ensure — create the EIGW if it isn't there yet.
          if (gw === undefined) {
            yield* session.note("Creating Egress-Only Internet Gateway...");
            const result = yield* ec2.createEgressOnlyInternetGateway({
              VpcId: news.vpcId as string,
              TagSpecifications: [
                {
                  ResourceType: "egress-only-internet-gateway",
                  Tags: createTagsList(desiredTags),
                },
              ],
              DryRun: false,
            });
            const newGwId = result.EgressOnlyInternetGateway!.EgressOnlyInternetGatewayId!;
            yield* session.note(`Egress-Only Internet Gateway created: ${newGwId}`);
            gw = yield* describeEgressOnlyInternetGateway(newGwId);
          }

          const eigwId = gw.EgressOnlyInternetGatewayId!;

          // Sync tags — observed cloud tags vs desired.
          const currentTags =
            (yield* ec2
              .describeTags({
                Filters: [
                  { Name: "resource-id", Values: [eigwId] },
                  {
                    Name: "resource-type",
                    Values: ["egress-only-internet-gateway"],
                  },
                ],
              })
              .pipe(
                Effect.map(
                  (r) =>
                    Object.fromEntries(r.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: [eigwId],
              Tags: removed.map((key) => ({ Key: key })),
              DryRun: false,
            });
          }
          if (upsert.length > 0) {
            yield* ec2.createTags({
              Resources: [eigwId],
              Tags: upsert,
              DryRun: false,
            });
          }

          // Re-read to reflect current cloud state in the returned attributes.
          const final = yield* describeEgressOnlyInternetGateway(eigwId);
          return yield* toAttrs(final);
        }),

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

          yield* session.note(`Deleting Egress-Only Internet Gateway: ${eigwId}`);

          yield* ec2
            .deleteEgressOnlyInternetGateway({
              EgressOnlyInternetGatewayId: eigwId,
              DryRun: false,
            })
            .pipe(
              Effect.tapError(Effect.logDebug),
              // `DeleteEgressOnlyInternetGateway` reports failure as
              // `ReturnCode: false` with NO error. Treating that as success
              // orphans the gateway: the engine drops the state row while the
              // gateway stays attached, wedging the parent VPC's delete on
              // DependencyViolation forever. Surface it so the retry below
              // re-drives the call (and the delete fails loudly if it never
              // takes).
              Effect.flatMap((result) =>
                result.ReturnCode === false
                  ? Effect.fail(new EigwDeleteFailed({ eigwId }))
                  : Effect.void,
              ),
              Effect.catchTags({
                "InvalidGatewayID.NotFound": () => Effect.void,
                "InvalidEgressOnlyInternetGatewayId.NotFound": () => Effect.void,
              }),
              // Retry on dependency violations (e.g., routes still using the EIGW)
              Effect.retry({
                while: (e) => e._tag === "DependencyViolation" || e._tag === "EigwDeleteFailed",
                schedule: Schedule.max([Schedule.fixed(5000), Schedule.recurs(30)]).pipe(
                  Schedule.tap(({ attempt }) =>
                    session.note(`Waiting for dependencies to clear... (attempt ${attempt})`),
                  ),
                ),
              }),
            );

          // Deletion is asynchronous: wait until the gateway is actually gone
          // before reporting success, so the parent VPC's delete (which the
          // engine runs next) never races a still-attached gateway.
          yield* ec2
            .describeEgressOnlyInternetGateways({
              EgressOnlyInternetGatewayIds: [eigwId],
            })
            .pipe(
              Effect.flatMap((r) =>
                (r.EgressOnlyInternetGateways ?? []).length === 0
                  ? Effect.void
                  : Effect.fail(new EigwStillExists({ eigwId })),
              ),
              Effect.retry({
                while: (e) => e._tag === "EigwStillExists",
                schedule: Schedule.max([Schedule.fixed(2000), Schedule.recurs(15)]),
              }),
              Effect.catchTag("InvalidEgressOnlyInternetGatewayId.NotFound", () => Effect.void),
            );

          yield* session.note(`Egress-Only Internet Gateway ${eigwId} deleted`);
        }),
      };
    }),
  );