sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Zone/ CustomNameservers.ts

import * as zones from "@distilled.cloud/cloudflare/zones";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";

const TypeId = "Cloudflare.Zone.CustomNameservers" as const;
type TypeId = typeof TypeId;

export type CustomNameserversProps = {
  /**
   * Zone whose account-level custom nameserver usage is managed. Stable —
   * changing the zone triggers a replacement (the old zone's configuration
   * is restored to the value it had before Alchemy managed it).
   */
  zoneId: string;
  /**
   * Whether the zone uses account-level custom nameservers (ACNS) instead
   * of the Cloudflare-assigned nameservers.
   *
   * Enabling requires an account-level custom nameserver set to already be
   * configured (Business/Enterprise) — otherwise Cloudflare rejects the
   * update with the typed `CustomNameserverSetNotFound` error.
   *
   * Mutable — applied in place.
   */
  enabled: boolean;
  /**
   * The number of the account custom nameserver set to assign to the zone.
   * Only meaningful when `enabled` is `true`.
   *
   * Mutable — applied in place.
   *
   * @default 1 (Cloudflare's default nameserver set)
   */
  nsSet?: number;
};

export type CustomNameserversAttributes = {
  /** Zone whose custom nameserver usage is managed. */
  zoneId: string;
  /** Whether the zone currently uses account-level custom nameservers. */
  enabled: boolean;
  /** The nameserver set currently assigned to the zone, if reported. */
  nsSet: number | undefined;
  /**
   * Whether ACNS was enabled before Alchemy first touched the zone.
   * Restored on destroy, so deleting the resource puts the zone back the
   * way it was found.
   */
  initialEnabled: boolean;
  /** The nameserver set assigned before Alchemy first touched the zone. */
  initialNsSet: number | undefined;
};

export type CustomNameservers = Resource<
  TypeId,
  CustomNameserversProps,
  CustomNameserversAttributes,
  never,
  Providers
>;

/**
 * Controls whether a Cloudflare zone uses **account-level custom
 * nameservers** (ACNS, `/zones/{zone_id}/custom_ns`).
 *
 * This configuration is a zone singleton — it always exists on every zone
 * (disabled by default), so the resource never creates or deletes anything
 * physical. Reconcile applies the desired `enabled`/`nsSet` when the
 * observed configuration differs; destroy restores the configuration the
 * zone had before Alchemy first managed it.
 *
 * Enabling requires an account custom nameserver set to be configured first
 * (Business/Enterprise feature). Without one, Cloudflare rejects the update
 * with the typed `CustomNameserverSetNotFound` error.
 * ### Enabling account custom nameservers
 * **Example:** Use the account's default nameserver set
 * ```typescript
 * yield* Cloudflare.Zone.CustomNameservers("CustomNs", {
 *   zoneId: zone.zoneId,
 *   enabled: true,
 * });
 * ```
 *
 * **Example:** Pin a specific nameserver set
 * ```typescript
 * yield* Cloudflare.Zone.CustomNameservers("CustomNs", {
 *   zoneId: zone.zoneId,
 *   enabled: true,
 *   nsSet: 2,
 * });
 * ```
 *
 * ### Disabling
 * **Example:** Explicitly pin the zone to Cloudflare-assigned nameservers
 * ```typescript
 * yield* Cloudflare.Zone.CustomNameservers("CustomNs", {
 *   zoneId: zone.zoneId,
 *   enabled: false,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/api/resources/zones/subresources/custom_nameservers/
 *
 * @resource
 * @product Zones
 * @category Domains & DNS
 */
export const CustomNameservers = Resource<CustomNameservers>(TypeId);

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

export const CustomNameserversProvider = () =>
  Provider.succeed(CustomNameservers, {
    stables: ["zoneId", "initialEnabled", "initialNsSet"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // No account-wide API for this zone singleton — enumerate every
      // zone in the account and read its custom-nameserver config.
      const allZones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        allZones.map((zone) => zone.id),
        (zoneId) =>
          zones.getCustomNameserver({ zoneId }).pipe(
            Effect.map((observed) => {
              // Only zones actively using account custom nameservers are
              // worth enumerating — a disabled (default) toggle has
              // nothing to restore on destroy.
              if (!(observed.enabled ?? false)) return undefined;
              return toAttributes(
                zoneId,
                observed,
                observed.enabled ?? false,
                observed.nsSet ?? undefined,
              );
            }),
            // ACNS is a Business/Enterprise feature — plan-gated zones
            // reject with `Forbidden`; zones deleted out-of-band 404 with
            // `InvalidZoneIdentifier`. Skip both.
            Effect.catchTag(["InvalidZoneIdentifier", "Forbidden"], () => Effect.undefined),
          ),
        { concurrency: 10 },
      );
      return rows.filter((row): row is CustomNameserversAttributes => row !== undefined);
    }),

    diff: Effect.fn(function* ({ olds, news, output }) {
      // zoneId is the resource's identity; compare only once both sides
      // are concrete (resolved) values.
      if (!isResolved(news)) return undefined;
      const oldZoneId =
        output?.zoneId ?? (olds !== undefined && isResolved(olds) ? olds.zoneId : undefined);
      if (oldZoneId !== undefined && oldZoneId !== news.zoneId) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
      if (!zoneId) return undefined;
      const observed = yield* zones.getCustomNameserver({ zoneId }).pipe(
        // Zone deleted out-of-band — the configuration is gone with it.
        Effect.catchTag("InvalidZoneIdentifier", () => Effect.undefined),
      );
      if (observed === undefined) return undefined;
      // The custom-NS toggle is a singleton that always exists (disabled
      // by default) — there is nothing to "own", so a cold read adopts
      // freely (never `Unowned`). The observed state at adoption time
      // becomes the baseline restored on destroy.
      const initialEnabled =
        output !== undefined ? output.initialEnabled : (observed.enabled ?? false);
      const initialNsSet =
        output !== undefined ? output.initialNsSet : (observed.nsSet ?? undefined);
      return toAttributes(zoneId, observed, initialEnabled, initialNsSet);
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      // Inputs have been resolved to concrete strings by Plan.
      const zoneId = news.zoneId as string;

      // 1. Observe — the configuration always exists; read its live state.
      const observed = yield* zones.getCustomNameserver({ zoneId });

      // 2. Capture — the pre-management state, restored on destroy.
      //    `output` (including an adoption read) already carries it;
      //    otherwise this is our first touch and the observed state is
      //    the zone's original.
      const initialEnabled =
        output !== undefined ? output.initialEnabled : (observed.enabled ?? false);
      const initialNsSet =
        output !== undefined ? output.initialNsSet : (observed.nsSet ?? undefined);

      // 3. Sync — apply only when the observed state differs.
      const observedEnabled = observed.enabled ?? false;
      const observedNsSet = observed.nsSet ?? undefined;
      const inSync =
        observedEnabled === news.enabled &&
        (news.nsSet === undefined || observedNsSet === news.nsSet);
      if (inSync) {
        return toAttributes(zoneId, observed, initialEnabled, initialNsSet);
      }
      yield* zones.putCustomNameserver({
        zoneId,
        enabled: news.enabled,
        ...(news.nsSet !== undefined ? { nsSet: news.nsSet } : {}),
      });
      // The PUT response does not reliably echo the resulting state —
      // re-read so the attributes reflect the observed cloud state.
      const final = yield* zones.getCustomNameserver({ zoneId });
      return toAttributes(zoneId, final, initialEnabled, initialNsSet);
    }),

    delete: Effect.fn(function* ({ output }) {
      const { zoneId, initialEnabled, initialNsSet } = output;
      // Observe — if the zone itself is gone, so is the configuration.
      const observed = yield* zones
        .getCustomNameserver({ zoneId })
        .pipe(Effect.catchTag("InvalidZoneIdentifier", () => Effect.undefined));
      if (observed === undefined) return;
      // Restore the pre-management state; skip the call when it already
      // matches (idempotent re-delete after a crashed run).
      const observedEnabled = observed.enabled ?? false;
      const observedNsSet = observed.nsSet ?? undefined;
      if (
        observedEnabled === initialEnabled &&
        (initialNsSet === undefined || observedNsSet === initialNsSet)
      ) {
        return;
      }
      yield* zones
        .putCustomNameserver({
          zoneId,
          enabled: initialEnabled,
          ...(initialNsSet !== undefined ? { nsSet: initialNsSet } : {}),
        })
        .pipe(
          // Zone deleted out-of-band, or the account nameserver set the
          // zone originally referenced no longer exists — nothing left to
          // restore.
          Effect.catchTag(
            ["InvalidZoneIdentifier", "CustomNameserverSetNotFound"],
            () => Effect.void,
          ),
        );
    }),
  });

const toAttributes = (
  zoneId: string,
  observed: zones.GetCustomNameserverResponse,
  initialEnabled: boolean,
  initialNsSet: number | undefined,
): CustomNameserversAttributes => ({
  zoneId,
  enabled: observed.enabled ?? false,
  nsSet: observed.nsSet ?? undefined,
  initialEnabled,
  initialNsSet,
});