sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ EC2/ NetworkAcl.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 NetworkAclUnexpectedResponse extends Data.TaggedError("NetworkAclUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

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

export type NetworkAclArn<ID extends NetworkAclId = NetworkAclId> =
  `arn:aws:ec2:${RegionID}:${AccountID}:network-acl/${ID}`;

export interface NetworkAclProps {
  /**
   * The VPC to create the network ACL in.
   */
  vpcId: VpcId;

  /**
   * Tags to assign to the network ACL.
   */
  tags?: Record<string, string>;
}

export interface NetworkAcl extends Resource<
  "AWS.EC2.NetworkAcl",
  NetworkAclProps,
  {
    /**
     * The ID of the network ACL.
     */
    networkAclId: NetworkAclId;
    /**
     * The Amazon Resource Name (ARN) of the network ACL.
     */
    networkAclArn: NetworkAclArn;
    /**
     * The ID of the VPC the network ACL belongs to.
     */
    vpcId: VpcId;
    /**
     * Whether this is the default network ACL for the VPC.
     */
    isDefault: boolean;
    /**
     * The ID of the AWS account that owns the network ACL.
     */
    ownerId: string;
    /**
     * The rule entries (inbound and outbound) currently defined on the ACL.
     */
    entries?: Array<{
      /** The rule number; rules are evaluated lowest to highest. */
      ruleNumber: number;
      /** The protocol number ("-1" means all protocols). */
      protocol: string;
      /** Whether the rule allows or denies matching traffic. */
      ruleAction: ec2.RuleAction;
      /** Whether this is an egress (outbound) rule. */
      egress: boolean;
      /** The IPv4 CIDR block the rule applies to. */
      cidrBlock?: string;
      /** The IPv6 CIDR block the rule applies to. */
      ipv6CidrBlock?: string;
      /** The ICMP type and code, for ICMP rules. */
      icmpTypeCode?: {
        code?: number;
        type?: number;
      };
      /** The port range, for TCP/UDP rules. */
      portRange?: {
        from?: number;
        to?: number;
      };
    }>;
    /**
     * The subnet associations currently attached to the network ACL.
     */
    associations?: Array<{
      /** The ID of the association between the ACL and the subnet. */
      networkAclAssociationId: string;
      /** The ID of the associated network ACL. */
      networkAclId: string;
      /** The ID of the associated subnet. */
      subnetId: string;
    }>;
  },
  never,
  Providers
> {}
/**
 * A network ACL — a stateless firewall that controls inbound and outbound
 * traffic at the *subnet* level, evaluated as an ordered list of numbered
 * allow/deny rules.
 *
 * Unlike security groups (which are stateful and attach to interfaces), a
 * network ACL is associated with subnets and evaluates return traffic
 * independently, so you typically pair each inbound rule with a matching
 * ephemeral-port outbound rule. The ACL itself only takes `vpcId` and `tags`;
 * the actual rules live in `NetworkAclEntry` resources and subnet attachments
 * in `NetworkAclAssociation` resources. Changing `vpcId` replaces the ACL.
 *
 * ### Creating Network ACLs
 * **Example:** Basic Network ACL
 * ```typescript
 * const acl = yield* AWS.EC2.NetworkAcl("PrivateNetworkAcl", {
 *   vpcId: vpc.vpcId,
 *   tags: { Name: "private-nacl" },
 * });
 * ```
 * This creates an empty custom ACL in the VPC — it starts with only the implicit
 * default-deny rules, so until you add entries it blocks all traffic on any
 * subnet you associate with it.
 *
 * ### Composing Rules and Associations
 * A network ACL is only useful once you attach rules and point subnets at it.
 * The typical pattern is one `NetworkAcl`, several `NetworkAclEntry` rules, and
 * one `NetworkAclAssociation` per subnet.
 * **Example:** Network ACL with an Inbound Rule and Subnet Association
 * ```typescript
 * const acl = yield* AWS.EC2.NetworkAcl("PrivateNetworkAcl", {
 *   vpcId: vpc.vpcId,
 * });
 *
 * const allowVpc = yield* AWS.EC2.NetworkAclEntry("AllowVpc", {
 *   networkAclId: acl.networkAclId,
 *   ruleNumber: 100,
 *   protocol: "-1",
 *   ruleAction: "allow",
 *   egress: false,
 *   cidrBlock: "10.0.0.0/16",
 * });
 *
 * const association = yield* AWS.EC2.NetworkAclAssociation("SubnetAssoc", {
 *   networkAclId: acl.networkAclId,
 *   subnetId: privateSubnet.subnetId,
 * });
 * ```
 * The entry allows all traffic from within the VPC CIDR and the association
 * makes the subnet use this ACL instead of the VPC default. Build up the full
 * rule set by adding more `NetworkAclEntry` resources with increasing
 * `ruleNumber`s.
 *
 * @resource
 */
export const NetworkAcl = Resource<NetworkAcl>("AWS.EC2.NetworkAcl");

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

      const describeNetworkAcl = (networkAclId: string) =>
        ec2.describeNetworkAcls({ NetworkAclIds: [networkAclId] }).pipe(
          Effect.map((r) => r.NetworkAcls?.[0]),
          Effect.flatMap((acl) =>
            acl
              ? Effect.succeed(acl)
              : Effect.fail(
                  new NetworkAclUnexpectedResponse({
                    message: `Network ACL ${networkAclId} not found`,
                  }),
                ),
          ),
        );

      const toAttrs = Effect.fn(function* (acl: ec2.NetworkAcl) {
        const { accountId, region } = yield* AWSEnvironment.current;
        return {
          networkAclId: acl.NetworkAclId as NetworkAclId,
          networkAclArn:
            `arn:aws:ec2:${region}:${accountId}:network-acl/${acl.NetworkAclId}` as NetworkAclArn,
          vpcId: acl.VpcId as VpcId,
          isDefault: acl.IsDefault ?? false,
          ownerId: acl.OwnerId!,
          entries: acl.Entries?.map((e) => ({
            ruleNumber: e.RuleNumber!,
            protocol: e.Protocol!,
            ruleAction: e.RuleAction!,
            egress: e.Egress!,
            cidrBlock: e.CidrBlock,
            ipv6CidrBlock: e.Ipv6CidrBlock,
            icmpTypeCode: e.IcmpTypeCode
              ? {
                  code: e.IcmpTypeCode.Code,
                  type: e.IcmpTypeCode.Type,
                }
              : undefined,
            portRange: e.PortRange
              ? {
                  from: e.PortRange.From,
                  to: e.PortRange.To,
                }
              : undefined,
          })),
          associations: acl.Associations?.map((a) => ({
            networkAclAssociationId: a.NetworkAclAssociationId!,
            networkAclId: a.NetworkAclId!,
            subnetId: a.SubnetId!,
          })),
        } satisfies NetworkAcl["Attributes"];
      });

      return {
        stables: ["networkAclId", "networkAclArn", "ownerId", "isDefault"],

        read: Effect.fn(function* ({ output }) {
          if (!output) return undefined;
          const acl = yield* describeNetworkAcl(output.networkAclId);
          return yield* toAttrs(acl);
        }),

        list: () =>
          Effect.gen(function* () {
            // Filter default NACLs at the API: every VPC has one, they
            // cannot be deleted, and paging through them under a concurrent
            // suite stalls the list test past the per-test timeout — which
            // then skips destroy and leaks the custom ACL + VPC.
            const acls = yield* ec2.describeNetworkAcls
              .pages({
                Filters: [{ Name: "default", Values: ["false"] }],
              })
              .pipe(
                Stream.runCollect,
                Effect.map((chunk) =>
                  Array.from(chunk).flatMap((page) =>
                    (page.NetworkAcls ?? []).filter(
                      (acl): acl is ec2.NetworkAcl & { NetworkAclId: string } =>
                        acl.NetworkAclId != null && acl.IsDefault !== true,
                    ),
                  ),
                ),
              );
            return yield* Effect.forEach(acls, (acl) => toAttrs(acl));
          }),

        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 NACL via cached id, else fall through to create.
          let acl: ec2.NetworkAcl | undefined;
          if (output?.networkAclId) {
            const lookup = yield* ec2
              .describeNetworkAcls({ NetworkAclIds: [output.networkAclId] })
              .pipe(
                Effect.catchTag("InvalidNetworkAclID.NotFound", () =>
                  Effect.succeed({ NetworkAcls: [] }),
                ),
              );
            acl = lookup.NetworkAcls?.[0];
          }

          // Ensure — create the NACL when missing.
          if (acl === undefined) {
            yield* session.note("Creating Network ACL...");
            const result = yield* ec2.createNetworkAcl({
              VpcId: news.vpcId as string,
              TagSpecifications: [
                {
                  ResourceType: "network-acl",
                  Tags: createTagsList(desiredTags),
                },
              ],
              DryRun: false,
            });
            const newAclId = result.NetworkAcl!.NetworkAclId!;
            yield* session.note(`Network ACL created: ${newAclId}`);
            acl = yield* describeNetworkAcl(newAclId);
          }

          const networkAclId = acl.NetworkAclId!;

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

          // Re-read final state.
          const final = yield* describeNetworkAcl(networkAclId);
          return yield* toAttrs(final);
        }),

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

          yield* session.note(`Deleting Network ACL: ${networkAclId}`);

          yield* ec2
            .deleteNetworkAcl({
              NetworkAclId: networkAclId,
              DryRun: false,
            })
            .pipe(
              Effect.catchTag("InvalidNetworkAclID.NotFound", () => Effect.void),
              // Retry on dependency violations (e.g., associations still being removed)
              Effect.retry({
                while: (e) => e._tag === "DependencyViolation",
                schedule: Schedule.max([Schedule.exponential(1000, 1.5), Schedule.recurs(15)]).pipe(
                  Schedule.tap(({ attempt }) =>
                    session.note(`Waiting for dependencies to clear... (attempt ${attempt})`),
                  ),
                ),
              }),
            );

          yield* session.note(`Network ACL ${networkAclId} deleted`);
        }),
      };
    }),
  );