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

import * as dns from "@distilled.cloud/cloudflare/dns";
import { Unowned } from "alchemy/AdoptPolicy";
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.ZoneTransferAcl" as const;
type TypeId = typeof TypeId;

export interface ZoneTransferAclProps {
  /**
   * Human-readable name of the ACL. If omitted, a unique name is
   * generated from the app, stage, and logical ID.
   *
   * Mutable — updated in place (PUT).
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * Allowed IPv4/IPv6 address range of primary or secondary
   * nameservers, applied account-wide. Used to allow additional NOTIFY
   * IPs for secondary zones and IPs Cloudflare allows AXFR/IXFR
   * requests from for outgoing transfers. CIDRs are limited to a
   * maximum of /24 for IPv4 and /64 for IPv6. Note that Cloudflare
   * normalizes the range to its network address (e.g. `192.0.2.53/28`
   * becomes `192.0.2.48/28`).
   *
   * Mutable — updated in place (PUT).
   */
  ipRange: string;
}

export interface ZoneTransferAclAttributes {
  /** Identifier of the ACL. */
  aclId: string;
  /** The Cloudflare account the ACL belongs to. */
  accountId: string;
  /** Human-readable name of the ACL. */
  name: string;
  /** Allowed IP range, as normalized by Cloudflare. */
  ipRange: string;
}

export type ZoneTransferAcl = Resource<
  TypeId,
  ZoneTransferAclProps,
  ZoneTransferAclAttributes,
  never,
  Providers
>;

/**
 * A Secondary DNS zone-transfer ACL
 * (`/accounts/{account_id}/secondary_dns/acls`) — an account-wide
 * IPv4/IPv6 range that may receive NOTIFYs for secondary zones and from
 * which Cloudflare accepts AXFR/IXFR requests for outgoing transfers.
 *
 * Requires the Secondary DNS (zone transfer) entitlement on the
 * account. Both `name` and `ipRange` are mutable in place.
 * ### Creating an ACL
 * **Example:** Allow a primary nameserver range
 * ```typescript
 * const acl = yield* Cloudflare.DNS.ZoneTransferAcl("PrimaryNs", {
 *   ipRange: "192.0.2.48/28",
 * });
 * ```
 *
 * **Example:** ACL with an explicit name
 * ```typescript
 * const acl = yield* Cloudflare.DNS.ZoneTransferAcl("PrimaryNs", {
 *   name: "primary-nameservers",
 *   ipRange: "2001:db8::/64",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/dns/zone-setups/zone-transfers/
 *
 * @resource
 * @product DNS
 * @category Domains & DNS
 */
export const ZoneTransferAcl = Resource<ZoneTransferAcl>(TypeId, {
  aliases: ["Cloudflare.Dns.ZoneTransferAcl"],
});

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

export const ZoneTransferAclProvider = () =>
  Provider.succeed(ZoneTransferAcl, {
    stables: ["aclId", "accountId"],

    // Account-scoped collection: enumerate every ACL in the ambient
    // account, paginating exhaustively, and hydrate into the exact `read`
    // Attributes shape.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* dns.listZoneTransferAcls.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((acl): ZoneTransferAclAttributes => ({
              aclId: acl.id,
              accountId,
              name: acl.name,
              ipRange: acl.ipRange,
            })),
          ),
        ),
      );
    }),

    diff: Effect.fn(function* ({ output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (output !== undefined && output.accountId !== accountId) {
        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?.aclId) {
        const observed = yield* getAcl(acct, output.aclId);
        return observed ? toAttributes(observed, acct) : undefined;
      }
      // Cold read — recover from lost state by matching the
      // deterministic physical name. ACLs carry no ownership markers,
      // so gate takeover behind adoption.
      const name = yield* createAclName(id, olds?.name);
      const match = yield* findByName(acct, name);
      return match ? Unowned(toAttributes(match, acct)) : undefined;
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const name = yield* createAclName(id, news.name);
      // Inputs are resolved to concrete values by Plan.
      const ipRange = news.ipRange as string;

      // Observe — the id cached on `output` is a hint, not a guarantee.
      const observed = output?.aclId
        ? yield* getAcl(output.accountId ?? accountId, output.aclId)
        : undefined;

      if (!observed) {
        // Ensure — greenfield (or out-of-band delete). Names are not
        // unique on Cloudflare's side, so there is no AlreadyExists
        // race to tolerate.
        const created = yield* dns.createZoneTransferAcl({
          accountId,
          name,
          ipRange,
        });
        return toAttributes(created, accountId);
      }

      // Sync — the update API is a PUT with the full body; skip the
      // call entirely when nothing differs. Cloudflare normalizes
      // `ipRange` to the network address, so compare against the
      // observed (normalized) value.
      if (observed.name === name && observed.ipRange === ipRange) {
        return toAttributes(observed, output?.accountId ?? accountId);
      }
      const updated = yield* dns.updateZoneTransferAcl({
        accountId: output?.accountId ?? accountId,
        aclId: observed.id,
        name,
        ipRange,
      });
      return toAttributes(updated, output?.accountId ?? accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* dns
        .deleteZoneTransferAcl({
          accountId: output.accountId,
          aclId: output.aclId,
        })
        .pipe(Effect.catchTag("AclNotFound", () => Effect.void));
    }),
  });

type ObservedAcl =
  | dns.GetZoneTransferAclResponse
  | dns.CreateZoneTransferAclResponse
  | dns.UpdateZoneTransferAclResponse;

/** Read an ACL by id, mapping "gone" (404) to `undefined`. */
const getAcl = (accountId: string, aclId: string) =>
  dns
    .getZoneTransferAcl({ accountId, aclId })
    .pipe(Effect.catchTag("AclNotFound", () => Effect.undefined));

/**
 * Find an ACL by exact name. Names are not unique on Cloudflare's side;
 * pick the lexicographically-first id for determinism.
 */
const findByName = (accountId: string, name: string) =>
  dns.listZoneTransferAcls.items({ accountId }).pipe(
    Stream.filter((a) => a.name === name),
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .sort((a, b) => a.id.localeCompare(b.id))
        .at(0),
    ),
  );

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

const toAttributes = (acl: ObservedAcl, accountId: string): ZoneTransferAclAttributes => ({
  aclId: acl.id,
  accountId,
  name: acl.name,
  ipRange: acl.ipRange,
});