sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ DNS/ Firewall.ts

import * as dnsFirewall from "@distilled.cloud/cloudflare/dns-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 * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.DNS.Firewall" as const;
type TypeId = typeof TypeId;

/**
 * Attack mitigation settings for a DNS Firewall cluster.
 */
export type AttackMitigation = {
  /**
   * When enabled, automatically mitigate random-prefix attacks to protect
   * upstream DNS servers.
   * @default false
   */
  enabled?: boolean;
  /**
   * Only mitigate attacks when upstream servers seem unhealthy.
   * @default false
   */
  onlyWhenUpstreamUnhealthy?: boolean;
};

export type FirewallProps = {
  /**
   * DNS Firewall cluster name. Changing the name triggers a replacement —
   * the name is the identity used for cold-state recovery. If omitted, a
   * unique name is generated from the app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * Upstream DNS server IPs the cluster forwards queries to. At least one
   * is required.
   */
  upstreamIps: string[];
  /**
   * Attack mitigation settings.
   * @default disabled
   */
  attackMitigation?: AttackMitigation;
  /**
   * Whether to refuse to answer queries for the ANY type.
   * @default false
   */
  deprecateAnyRequests?: boolean;
  /**
   * Whether to forward the client IP (resolver) subnet if no EDNS Client
   * Subnet is sent.
   * @default false
   */
  ecsFallback?: boolean;
  /**
   * Upper bound (in seconds) on how long responses are cached, regardless
   * of the TTL received from the upstream nameservers.
   * @default 900
   */
  maximumCacheTtl?: number;
  /**
   * Lower bound (in seconds) on how long responses are cached, regardless
   * of the TTL received from the upstream nameservers.
   * @default 60
   */
  minimumCacheTtl?: number;
  /**
   * How long (in seconds) DNS Firewall caches negative responses (e.g.
   * NXDOMAIN) from the upstream servers. `null` uses Cloudflare's default
   * behavior.
   * @default null
   */
  negativeCacheTtl?: number | null;
  /**
   * Ratelimit in queries per second per datacenter, applied to queries
   * sent to the upstream nameservers. `null` disables the limit.
   * @default null
   */
  ratelimit?: number | null;
  /**
   * Number of retries for fetching DNS responses from upstream nameservers
   * (not counting the initial attempt).
   * @default 2
   */
  retries?: number;
  /**
   * Reverse DNS (PTR) mappings for the cluster's assigned IPs — a map of
   * cluster IP address to PTR record content. Only the entries listed here
   * are managed: entries are upserted, and removing an entry from this map
   * leaves the PTR in place (clear it explicitly with an empty string).
   */
  reverseDns?: Record<string, string>;
};

export type FirewallAttributes = {
  /**
   * DNS Firewall cluster identifier (UUID).
   */
  dnsFirewallId: string;
  /**
   * The Cloudflare account the cluster belongs to.
   */
  accountId: string;
  /**
   * DNS Firewall cluster name.
   */
  name: string;
  /**
   * The Cloudflare-assigned anycast IPs of the cluster. Point NS glue
   * records at these.
   */
  dnsFirewallIps: string[];
  /**
   * Upstream DNS server IPs the cluster forwards queries to.
   */
  upstreamIps: string[];
  /**
   * Attack mitigation settings.
   */
  attackMitigation: {
    enabled: boolean;
    onlyWhenUpstreamUnhealthy: boolean;
  };
  /**
   * Whether queries for the ANY type are refused.
   */
  deprecateAnyRequests: boolean;
  /**
   * Whether the client IP (resolver) subnet is forwarded when no EDNS
   * Client Subnet is sent.
   */
  ecsFallback: boolean;
  /**
   * Upper bound (in seconds) on response cache duration.
   */
  maximumCacheTtl: number;
  /**
   * Lower bound (in seconds) on response cache duration.
   */
  minimumCacheTtl: number;
  /**
   * Negative response cache duration (in seconds), or `null` for
   * Cloudflare's default behavior.
   */
  negativeCacheTtl: number | null;
  /**
   * Ratelimit in queries per second per datacenter, or `null` when
   * disabled.
   */
  ratelimit: number | null;
  /**
   * Number of retries for fetching DNS responses from upstream
   * nameservers.
   */
  retries: number;
  /**
   * Reverse DNS (PTR) mappings managed on the cluster, when the
   * `reverseDns` prop is set.
   */
  reverseDns: Record<string, string> | undefined;
  /**
   * Last modification time of the cluster.
   */
  modifiedOn: string;
};

export type Firewall = Resource<TypeId, FirewallProps, FirewallAttributes, never, Providers>;

/**
 * A Cloudflare DNS Firewall cluster.
 *
 * DNS Firewall sits in front of your authoritative DNS infrastructure,
 * caching responses on Cloudflare's anycast network and shielding the
 * upstream nameservers from attack traffic. Creating a cluster assigns a
 * set of Cloudflare anycast IPs (`dnsFirewallIps`) that you point NS glue
 * records at; queries hitting those IPs are answered from cache or
 * forwarded to your `upstreamIps`.
 *
 * DNS Firewall is a paid add-on (typically Enterprise / contract). On
 * accounts without the entitlement, creation fails with the typed
 * `DnsFirewallNotEntitled` error (Cloudflare error code 10101).
 *
 * All settings are mutable in place; only `name` (the cold-state recovery
 * identity) triggers a replacement.
 * ### Creating a Cluster
 * **Example:** Basic cluster
 * ```typescript
 * const cluster = yield* Cloudflare.DNS.Firewall("dns-shield", {
 *   upstreamIps: ["192.0.2.1", "192.0.2.2"],
 * });
 * // Point NS glue records at the assigned anycast IPs:
 * const ips = cluster.dnsFirewallIps;
 * ```
 *
 * **Example:** Tuned caching and attack mitigation
 * ```typescript
 * const cluster = yield* Cloudflare.DNS.Firewall("dns-shield", {
 *   upstreamIps: ["192.0.2.1"],
 *   minimumCacheTtl: 120,
 *   maximumCacheTtl: 3600,
 *   negativeCacheTtl: 300,
 *   ratelimit: 600,
 *   retries: 2,
 *   attackMitigation: {
 *     enabled: true,
 *     onlyWhenUpstreamUnhealthy: true,
 *   },
 * });
 * ```
 *
 * ### Reverse DNS
 * **Example:** Managing PTR records for cluster IPs
 * ```typescript
 * const cluster = yield* Cloudflare.DNS.Firewall("dns-shield", {
 *   upstreamIps: ["192.0.2.1"],
 *   reverseDns: {
 *     "203.0.113.1": "ns1.example.com",
 *   },
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/dns/dns-firewall/
 *
 * @resource
 * @product DNS Firewall
 * @category Domains & DNS
 */
export const Firewall = Resource<Firewall>(TypeId, {
  aliases: ["Cloudflare.DnsFirewall"],
});

/**
 * Returns true if the given value is a DnsFirewall resource.
 */
export const isFirewall = (value: unknown): value is Firewall =>
  Predicate.hasProperty(value, "Type") && value.Type === TypeId;

export const FirewallProvider = () =>
  Provider.succeed(Firewall, {
    stables: ["dnsFirewallId", "accountId", "dnsFirewallIps"],
    diff: Effect.fn(function* ({ id, olds, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (!isResolved(news)) return undefined;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // The name is the cold-state recovery identity — renames replace.
      const oldName = output?.name ?? (yield* createClusterName(id, olds.name));
      // Auto-generated names are engine-owned: the deployed name stays
      // authoritative even if the generator would name this id differently
      // today. Only an explicit user-provided name can force a replace.
      const name = news.name ?? oldName;
      if (name !== oldName) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ id, output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;

      if (output?.dnsFirewallId) {
        const observed = yield* getCluster(acct, output.dnsFirewallId);
        if (!observed) return undefined;
        const reverseDns =
          olds?.reverseDns !== undefined ? yield* getReverseDns(acct, observed.id) : undefined;
        return toAttributes(observed, acct, reverseDns);
      }

      // Cold read — recover from lost state by matching the deterministic
      // physical name. Cluster names are not guaranteed unique and carry
      // no ownership markers, so report the match as `Unowned`: the
      // engine refuses to take it over unless `adopt` is set.
      const name = yield* createClusterName(id, olds?.name);
      const match = yield* findByName(acct, name);
      if (!match) return undefined;
      const reverseDns =
        olds?.reverseDns !== undefined ? yield* getReverseDns(acct, match.id) : undefined;
      return Unowned(toAttributes(match, acct, reverseDns));
    }),
    list: Effect.fn(function* () {
      // Account-scoped collection: exhaustively paginate the DNS Firewall
      // list for the ambient account. Each list item already carries the
      // full cluster shape (identical to `getDnsFirewall`), so it maps
      // directly into the `read` Attributes shape — no per-item hydration
      // needed. `reverseDns` is left `undefined` (the same shape `read`
      // produces when no managed PTR map is tracked).
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* dnsFirewall.listDnsFirewalls.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            page.result.map((cluster) =>
              toAttributes({ ...cluster, accountId }, accountId, undefined),
            ),
          ),
        ),
      );
    }),
    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Prefer the deployed name: regenerating would rename the deployed
      // cluster if the generator's output for this id ever drifts.
      const name = output?.name ?? (yield* createClusterName(id, news.name));

      // Observe — the id cached on `output` is a hint, not a guarantee: a
      // missing cluster falls through to "missing" and we recreate.
      const observed = output?.dnsFirewallId
        ? yield* getCluster(output.accountId ?? accountId, output.dnsFirewallId)
        : undefined;

      let synced: ObservedCluster;
      if (!observed) {
        // Ensure — greenfield (or out-of-band delete): create with the
        // full desired body. Names are not unique on Cloudflare's side,
        // so there is no AlreadyExists race to tolerate.
        const created = yield* dnsFirewall.createDnsFirewall({
          accountId,
          name,
          upstreamIps: news.upstreamIps,
          attackMitigation: news.attackMitigation,
          deprecateAnyRequests: news.deprecateAnyRequests,
          ecsFallback: news.ecsFallback,
          maximumCacheTtl: news.maximumCacheTtl,
          minimumCacheTtl: news.minimumCacheTtl,
          negativeCacheTtl: news.negativeCacheTtl,
          ratelimit: news.ratelimit,
          retries: news.retries,
        });
        synced = { ...created, accountId };
      } else {
        // Sync — diff observed cloud state against the desired settings
        // (props with their documented defaults applied) and PATCH only
        // when something actually differs.
        const desired = {
          name,
          upstreamIps: news.upstreamIps,
          attackMitigation: {
            enabled: news.attackMitigation?.enabled ?? false,
            onlyWhenUpstreamUnhealthy: news.attackMitigation?.onlyWhenUpstreamUnhealthy ?? false,
          },
          deprecateAnyRequests: news.deprecateAnyRequests ?? false,
          ecsFallback: news.ecsFallback ?? false,
          maximumCacheTtl: news.maximumCacheTtl ?? 900,
          minimumCacheTtl: news.minimumCacheTtl ?? 60,
          negativeCacheTtl: news.negativeCacheTtl ?? null,
          ratelimit: news.ratelimit ?? null,
          retries: news.retries ?? 2,
        };
        const observedMitigation = normalizeMitigation(observed.attackMitigation);
        const dirty =
          observed.name !== desired.name ||
          !sameIps(observed.upstreamIps, desired.upstreamIps) ||
          observedMitigation.enabled !== desired.attackMitigation.enabled ||
          observedMitigation.onlyWhenUpstreamUnhealthy !==
            desired.attackMitigation.onlyWhenUpstreamUnhealthy ||
          observed.deprecateAnyRequests !== desired.deprecateAnyRequests ||
          observed.ecsFallback !== desired.ecsFallback ||
          observed.maximumCacheTtl !== desired.maximumCacheTtl ||
          observed.minimumCacheTtl !== desired.minimumCacheTtl ||
          observed.negativeCacheTtl !== desired.negativeCacheTtl ||
          observed.ratelimit !== desired.ratelimit ||
          observed.retries !== desired.retries;

        synced = dirty
          ? {
              ...(yield* dnsFirewall.patchDnsFirewall({
                accountId: observed.accountId,
                dnsFirewallId: observed.id,
                ...desired,
              })),
              accountId: observed.accountId,
            }
          : observed;
      }

      // Sync reverse DNS (PTR) entries when managed. Only the entries in
      // the desired map are reconciled — observed entries outside the map
      // are left untouched.
      let reverseDns: Record<string, string> | undefined;
      if (news.reverseDns !== undefined) {
        const observedPtr = yield* getReverseDns(synced.accountId, synced.id);
        const dirtyPtr = Object.entries(news.reverseDns).some(
          ([ip, ptr]) => observedPtr[ip] !== ptr,
        );
        if (dirtyPtr) {
          yield* dnsFirewall.patchReverseDn({
            accountId: synced.accountId,
            dnsFirewallId: synced.id,
            ptr: news.reverseDns,
          });
        }
        reverseDns = { ...observedPtr, ...news.reverseDns };
      }

      return toAttributes(synced, synced.accountId, reverseDns);
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* dnsFirewall
        .deleteDnsFirewall({
          accountId: output.accountId,
          dnsFirewallId: output.dnsFirewallId,
        })
        .pipe(Effect.catchTag("DnsFirewallNotFound", () => Effect.void));
    }),
  });

type ObservedCluster = dnsFirewall.GetDnsFirewallResponse & {
  accountId: string;
};

/**
 * Read a cluster by id, mapping "gone" (`DnsFirewallNotFound`, Cloudflare
 * error code 11001) to `undefined`.
 */
const getCluster = (accountId: string, dnsFirewallId: string) =>
  dnsFirewall.getDnsFirewall({ accountId, dnsFirewallId }).pipe(
    Effect.map((c): ObservedCluster => ({ ...c, accountId })),
    Effect.catchTag("DnsFirewallNotFound", () => Effect.undefined),
  );

/**
 * Read the reverse DNS (PTR) map of a cluster, narrowing the distilled
 * `Record<string, unknown>` values to strings.
 */
const getReverseDns = (accountId: string, dnsFirewallId: string) =>
  dnsFirewall
    .getReverseDn({ accountId, dnsFirewallId })
    .pipe(
      Effect.map((r) =>
        Object.fromEntries(
          Object.entries(r.ptr).flatMap(([ip, ptr]) =>
            typeof ptr === "string" && ptr !== "" ? [[ip, ptr]] : [],
          ),
        ),
      ),
    );

/**
 * Find a cluster by exact name. The list API has no name filter, so scan
 * the (paginated) account list client-side. If several clusters carry the
 * same name, pick the lexicographically smallest id for determinism.
 */
const findByName = (accountId: string, name: string) =>
  dnsFirewall.listDnsFirewalls.items({ accountId }).pipe(
    Stream.filter((c) => c.name === name),
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .sort((a, b) => a.id.localeCompare(b.id))
        .at(0),
    ),
    Effect.map((match) =>
      match ? ({ ...match, accountId } satisfies ObservedCluster) : undefined,
    ),
  );

const createClusterName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    return name ?? (yield* createPhysicalName({ id, lowercase: true }));
  });

const normalizeMitigation = (
  mitigation: dnsFirewall.GetDnsFirewallResponse["attackMitigation"],
) => ({
  enabled: mitigation?.enabled ?? false,
  onlyWhenUpstreamUnhealthy: mitigation?.onlyWhenUpstreamUnhealthy ?? false,
});

const sameIps = (observed: readonly string[], desired: readonly string[]) =>
  observed.length === desired.length &&
  [...observed].sort().join(",") === [...desired].sort().join(",");

const toAttributes = (
  cluster: ObservedCluster,
  accountId: string,
  reverseDns: Record<string, string> | undefined,
): FirewallAttributes => ({
  dnsFirewallId: cluster.id,
  accountId,
  name: cluster.name,
  dnsFirewallIps: [...cluster.dnsFirewallIps],
  upstreamIps: [...cluster.upstreamIps],
  attackMitigation: normalizeMitigation(cluster.attackMitigation),
  deprecateAnyRequests: cluster.deprecateAnyRequests,
  ecsFallback: cluster.ecsFallback,
  maximumCacheTtl: cluster.maximumCacheTtl,
  minimumCacheTtl: cluster.minimumCacheTtl,
  negativeCacheTtl: cluster.negativeCacheTtl,
  ratelimit: cluster.ratelimit,
  retries: cluster.retries,
  reverseDns,
  modifiedOn: cluster.modifiedOn,
});