sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ NetworkFirewall/ Firewall.ts

import type * as NFW from "@distilled.cloud/aws/network-firewall";
import * as nfw from "@distilled.cloud/aws/network-firewall";
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, 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 type { Providers } from "../Providers.ts";
import { nfwTagsToRecord, recordToNfwTags } from "./internal.ts";

export interface FirewallProps {
  /**
   * Name of the firewall. Must be 1-128 alphanumeric characters or hyphens.
   * If omitted, a deterministic physical name is generated. Changing the
   * name replaces the firewall.
   */
  firewallName?: string;
  /**
   * ARN of the {@link FirewallPolicy} that defines the firewall's traffic
   * inspection behavior. Updated in place via `AssociateFirewallPolicy`.
   */
  firewallPolicyArn: string;
  /**
   * ID of the VPC the firewall protects. Changing the VPC replaces the
   * firewall.
   */
  vpcId: string;
  /**
   * The public subnets (one per Availability Zone) that Network Firewall
   * provisions firewall endpoints into. Uses raw Network Firewall API
   * structures (`{ SubnetId, IPAddressType? }`). Updated in place via
   * `AssociateSubnets` / `DisassociateSubnets`.
   */
  subnetMappings: NFW.SubnetMapping[];
  /**
   * Whether the firewall is protected against deletion. The provider
   * automatically clears this flag before deleting the firewall.
   * @default false
   */
  deleteProtection?: boolean;
  /**
   * Whether the firewall is protected against changes to its subnet
   * associations.
   * @default false
   */
  subnetChangeProtection?: boolean;
  /**
   * Whether the firewall is protected against a change of firewall policy.
   * @default false
   */
  firewallPolicyChangeProtection?: boolean;
  /**
   * Human-readable description of the firewall.
   */
  description?: string;
  /**
   * Tags to apply to the firewall. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface Firewall extends Resource<
  "AWS.NetworkFirewall.Firewall",
  FirewallProps,
  {
    /** Name of the firewall. */
    firewallName: string;
    /** ARN of the firewall. */
    firewallArn: string;
    /** Server-assigned unique id of the firewall. */
    firewallId: string;
    /** ID of the VPC the firewall is provisioned into. */
    vpcId: string;
    /**
     * The VPC endpoint IDs of the provisioned firewall endpoints, one per
     * subnet mapping, sorted for determinism. Use these as route targets.
     */
    endpointIds: string[];
  },
  never,
  Providers
> {}

/**
 * An AWS Network Firewall firewall — provisions managed firewall endpoints
 * into your VPC subnets and inspects traffic according to an associated
 * {@link FirewallPolicy}.
 *
 * Endpoint provisioning takes several minutes (typically 5-10), and deleting
 * a firewall waits for the endpoints to deprovision.
 * ### Creating Firewalls
 * **Example:** Firewall in a VPC
 * ```typescript
 * import * as EC2 from "@alchemy.run/aws/EC2";
 * import * as NetworkFirewall from "@alchemy.run/aws/NetworkFirewall";
 *
 * const vpc = yield* EC2.Vpc("Vpc", { cidrBlock: "10.0.0.0/16" });
 * const subnet = yield* EC2.Subnet("FirewallSubnet", {
 *   vpcId: vpc.vpcId,
 *   cidrBlock: "10.0.1.0/24",
 * });
 *
 * const policy = yield* NetworkFirewall.FirewallPolicy("Policy", {
 *   firewallPolicy: {
 *     StatelessDefaultActions: ["aws:pass"],
 *     StatelessFragmentDefaultActions: ["aws:pass"],
 *   },
 * });
 *
 * const firewall = yield* NetworkFirewall.Firewall("Firewall", {
 *   firewallPolicyArn: policy.firewallPolicyArn,
 *   vpcId: vpc.vpcId,
 *   subnetMappings: [{ SubnetId: subnet.subnetId }],
 * });
 * ```
 *
 * @resource
 */
export const Firewall = Resource<Firewall>("AWS.NetworkFirewall.Firewall");

/** Raised (internally, for bounded retry) while a firewall is provisioning. */
export class FirewallNotReady extends Data.TaggedError("FirewallNotReady")<{
  message: string;
}> {}

/** Raised (internally, for bounded retry) while a firewall is deleting. */
export class FirewallNotDeleted extends Data.TaggedError("FirewallNotDeleted")<{
  message: string;
}> {}

// Explicitly-typed pipeable retry helpers (see internal.ts for why these are
// not inlined).
const retryWhileNotReady = <A, E extends { readonly _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "FirewallNotReady",
    schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(60)]),
  });

const retryWhileNotDeleted = <A, E extends { readonly _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "FirewallNotDeleted",
    schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(80)]),
  });

const retryWhileFirewallBusy = <A, E extends { readonly _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "InvalidOperationException",
    schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(20)]),
  });

export const FirewallProvider = () =>
  Provider.effect(
    Firewall,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: { firewallName?: string }) {
        return props.firewallName ?? (yield* createPhysicalName({ id, maxLength: 128 }));
      });

      const endpointIds = (status: NFW.FirewallStatus | undefined): string[] =>
        Object.values(status?.SyncStates ?? {})
          .map((state) => state?.Attachment?.EndpointId)
          .filter((id): id is string => id !== undefined)
          .sort();

      const toAttrs = (
        firewall: NFW.Firewall,
        status: NFW.FirewallStatus | undefined,
      ): Firewall["Attributes"] => ({
        firewallName: firewall.FirewallName ?? "",
        firewallArn: firewall.FirewallArn ?? "",
        firewallId: firewall.FirewallId,
        vpcId: firewall.VpcId,
        endpointIds: endpointIds(status),
      });

      const describe = Effect.fn(function* (name: string) {
        return yield* nfw
          .describeFirewall({ FirewallName: name })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      });

      // Bounded readiness wait. Endpoint provisioning typically completes in
      // 5-10 minutes; budget ~15 min (60 * 15s).
      const waitForReady = Effect.fn(function* (name: string) {
        return yield* Effect.gen(function* () {
          const response = yield* describe(name);
          if (response?.Firewall === undefined) {
            return yield* new FirewallNotReady({ message: `firewall '${name}' not found` });
          }
          if (response.FirewallStatus?.Status !== "READY") {
            return yield* new FirewallNotReady({
              message: `firewall '${name}' not ready (status: ${response.FirewallStatus?.Status})`,
            });
          }
          return response;
        }).pipe(retryWhileNotReady);
      });

      return Firewall.Provider.of({
        stables: ["firewallName", "firewallArn", "firewallId", "vpcId"],

        list: () =>
          Effect.gen(function* () {
            const pages = yield* nfw.listFirewalls.pages({}).pipe(Stream.runCollect);
            const metas = Array.from(pages).flatMap((page) => page.Firewalls ?? []);
            const items = yield* Effect.forEach(
              metas,
              (meta) =>
                nfw.describeFirewall({ FirewallArn: meta.FirewallArn }).pipe(
                  Effect.map((r) =>
                    r.Firewall !== undefined ? toAttrs(r.Firewall, r.FirewallStatus) : undefined,
                  ),
                  Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
                ),
              { concurrency: 5 },
            );
            return items.filter((item): item is Firewall["Attributes"] => item !== undefined);
          }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.firewallName ?? (yield* createName(id, olds ?? {}));
          const found = yield* describe(name);
          if (found?.Firewall === undefined) return undefined;
          const attrs = toAttrs(found.Firewall, found.FirewallStatus);
          const tags = nfwTagsToRecord(found.Firewall.Tags);
          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);
          if (oldName !== newName || olds.vpcId !== news.vpcId) {
            return { action: "replace" } as const;
          }
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = output?.firewallName ?? (yield* createName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags: Record<string, string> = {
            ...news.tags,
            ...internalTags,
          };

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

          // 2. Ensure — create if missing, then wait for READY so mutation
          // calls below don't race endpoint provisioning.
          if (observed?.Firewall === undefined) {
            yield* session.note(`creating firewall ${name} (5-10 minutes)`);
            yield* nfw.createFirewall({
              FirewallName: name,
              FirewallPolicyArn: news.firewallPolicyArn,
              VpcId: news.vpcId,
              SubnetMappings: news.subnetMappings,
              DeleteProtection: news.deleteProtection ?? false,
              SubnetChangeProtection: news.subnetChangeProtection ?? false,
              FirewallPolicyChangeProtection: news.firewallPolicyChangeProtection ?? false,
              Description: news.description,
              Tags: recordToNfwTags(desiredTags),
            });
          }
          observed = yield* waitForReady(name);
          let firewall = observed.Firewall!;

          // 3. Sync — each mutable aspect re-reads for a fresh UpdateToken,
          // diffs OBSERVED against desired, and applies only the delta.
          const refresh = Effect.fn(function* () {
            observed = yield* waitForReady(name);
            firewall = observed.Firewall!;
          });

          // 3a. Firewall policy association.
          if (firewall.FirewallPolicyArn !== news.firewallPolicyArn) {
            yield* nfw.associateFirewallPolicy({
              UpdateToken: observed.UpdateToken,
              FirewallName: name,
              FirewallPolicyArn: news.firewallPolicyArn,
            });
            yield* refresh();
          }

          // 3b. Subnet associations.
          const observedSubnetIds = new Set(firewall.SubnetMappings.map((m) => m.SubnetId));
          const desiredSubnetIds = new Set(news.subnetMappings.map((m) => m.SubnetId));
          const toAssociate = news.subnetMappings.filter((m) => !observedSubnetIds.has(m.SubnetId));
          const toDisassociate = [...observedSubnetIds].filter(
            (subnetId) => !desiredSubnetIds.has(subnetId),
          );
          if (toAssociate.length > 0) {
            yield* nfw.associateSubnets({
              UpdateToken: observed.UpdateToken,
              FirewallName: name,
              SubnetMappings: toAssociate,
            });
            yield* refresh();
          }
          if (toDisassociate.length > 0) {
            yield* nfw.disassociateSubnets({
              UpdateToken: observed.UpdateToken,
              FirewallName: name,
              SubnetIds: toDisassociate,
            });
            yield* refresh();
          }

          // 3c. Description.
          if ((news.description ?? undefined) !== firewall.Description) {
            yield* nfw.updateFirewallDescription({
              UpdateToken: observed.UpdateToken,
              FirewallName: name,
              Description: news.description,
            });
            yield* refresh();
          }

          // 3d. Protection flags.
          const desiredDeleteProtection = news.deleteProtection ?? false;
          if ((firewall.DeleteProtection ?? false) !== desiredDeleteProtection) {
            yield* nfw.updateFirewallDeleteProtection({
              UpdateToken: observed.UpdateToken,
              FirewallName: name,
              DeleteProtection: desiredDeleteProtection,
            });
            yield* refresh();
          }
          const desiredSubnetChangeProtection = news.subnetChangeProtection ?? false;
          if ((firewall.SubnetChangeProtection ?? false) !== desiredSubnetChangeProtection) {
            yield* nfw.updateSubnetChangeProtection({
              UpdateToken: observed.UpdateToken,
              FirewallName: name,
              SubnetChangeProtection: desiredSubnetChangeProtection,
            });
            yield* refresh();
          }
          const desiredPolicyChangeProtection = news.firewallPolicyChangeProtection ?? false;
          if (
            (firewall.FirewallPolicyChangeProtection ?? false) !== desiredPolicyChangeProtection
          ) {
            yield* nfw.updateFirewallPolicyChangeProtection({
              UpdateToken: observed.UpdateToken,
              FirewallName: name,
              FirewallPolicyChangeProtection: desiredPolicyChangeProtection,
            });
            yield* refresh();
          }

          // 3e. Tags — diff against OBSERVED cloud tags.
          const observedTags = nfwTagsToRecord(firewall.Tags);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          const arn = firewall.FirewallArn!;
          if (upsert.length > 0) {
            yield* nfw.tagResource({ ResourceArn: arn, Tags: upsert });
          }
          if (removed.length > 0) {
            yield* nfw.untagResource({ ResourceArn: arn, TagKeys: removed });
          }

          yield* session.note(name);
          return toAttrs(firewall, observed.FirewallStatus);
        }),

        delete: Effect.fn(function* ({ output, session }) {
          const name = output.firewallName;
          const observed = yield* nfw
            .describeFirewall({ FirewallName: name })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
          if (observed === undefined) return;

          // Clear delete protection first — DeleteFirewall requires it off.
          if (observed.Firewall?.DeleteProtection) {
            yield* nfw
              .updateFirewallDeleteProtection({
                UpdateToken: observed.UpdateToken,
                FirewallName: name,
                DeleteProtection: false,
              })
              .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
          }

          yield* session.note(
            `deleting firewall ${name} (endpoints deprovision over several minutes)`,
          );
          yield* nfw.deleteFirewall({ FirewallName: name }).pipe(
            retryWhileFirewallBusy,
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
          );

          // Wait until the firewall (and its endpoints) are fully gone so
          // dependent deletions (subnets, VPC) don't hit DependencyViolations.
          yield* Effect.gen(function* () {
            const remaining = yield* nfw
              .describeFirewall({ FirewallName: name })
              .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
            if (remaining !== undefined) {
              return yield* new FirewallNotDeleted({
                message: `firewall '${name}' still deleting (status: ${remaining.FirewallStatus?.Status})`,
              });
            }
          }).pipe(retryWhileNotDeleted);
        }),
      });
    }),
  );