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

import * as customNameservers from "@distilled.cloud/cloudflare/custom-nameservers";
import { Unowned } from "alchemy/AdoptPolicy";
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 * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.CustomNameserver.CustomNameserver" as const;
type TypeId = typeof TypeId;

/**
 * Verification status of an account custom nameserver. Deprecated by
 * Cloudflare but still returned by the API.
 */
export type Status = "moved" | "pending" | "verified";

/**
 * A glue record (A/AAAA) that must be registered at the domain registrar
 * for the custom nameserver to resolve.
 */
export interface Record {
  /**
   * The record type of the glue record.
   */
  type: "A" | "AAAA" | undefined;
  /**
   * The IP address of the glue record.
   */
  value: string | undefined;
}

export interface Props {
  /**
   * The FQDN of the nameserver (e.g. `ns1.yourbrand.com`). Must be a
   * subdomain of a zone active on the same account.
   *
   * Immutable — this is the nameserver's identity; changing it triggers a
   * replacement.
   */
  nsName: string;
  /**
   * The number of the nameserver set this nameserver belongs to (1–5).
   *
   * Immutable — there is no update API; changing it triggers a replacement.
   * @default 1
   */
  nsSet?: number;
}

export interface Attributes {
  /**
   * The FQDN of the nameserver. Also the identifier used to delete it.
   */
  nsName: string;
  /**
   * The Cloudflare account the nameserver belongs to.
   */
  accountId: string;
  /**
   * The number of the nameserver set this nameserver belongs to.
   */
  nsSet: number | undefined;
  /**
   * Verification status of the nameserver (deprecated by Cloudflare but
   * still returned).
   */
  status: Status;
  /**
   * A/AAAA glue records to register at the domain registrar so the
   * nameserver resolves.
   */
  dnsRecords: Record[];
  /**
   * The zone (on this account) that `nsName` belongs to.
   */
  zoneTag: string;
}

export type CustomNameserver = Resource<TypeId, Props, Attributes, never, Providers>;

/**
 * An account-level custom (vanity) nameserver — e.g. `ns1.yourbrand.com` —
 * that zones on the account can use instead of their assigned
 * `*.ns.cloudflare.com` names.
 *
 * The nameserver's identity is its `nsName` (FQDN) within the account.
 * There is no update API: both `nsName` and `nsSet` are immutable, so
 * changing either triggers a replacement. After creation, Cloudflare
 * returns the A/AAAA glue records (`dnsRecords`) that must be registered
 * at the domain registrar.
 *
 * Requires the account custom nameservers entitlement (Business/Enterprise
 * or a paid add-on); on unentitled accounts every API call fails with the
 * typed `CustomNameserversNotEnabled` error.
 *
 * Safety: custom nameservers carry no ownership markers. When there is no
 * prior state, `read` scans the account for an existing nameserver with
 * the same `nsName` and reports it as `Unowned`, so the engine refuses to
 * take it over unless `--adopt` (or `adopt(true)`) is set.
 * ### Creating a custom nameserver
 * **Example:** Vanity nameserver on the default set
 * ```typescript
 * const ns1 = yield* Cloudflare.CustomNameserver.CustomNameserver("Ns1", {
 *   nsName: "ns1.yourbrand.com",
 * });
 *
 * // Glue records to register at your registrar:
 * const glue = ns1.dnsRecords; // [{ type: "A", value: "..." }, ...]
 * ```
 *
 * **Example:** Nameserver on a specific set
 * ```typescript
 * yield* Cloudflare.CustomNameserver.CustomNameserver("Ns2", {
 *   nsName: "ns2.yourbrand.com",
 *   nsSet: 2,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/dns/nameservers/custom-nameservers/account-custom-nameservers/
 *
 * @resource
 * @product Custom Nameservers
 * @category Domains & DNS
 */
export const CustomNameserver = Resource<CustomNameserver>(TypeId, {
  aliases: ["Cloudflare.CustomNameserver"],
});

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

export const CustomNameserverProvider = () =>
  Provider.succeed(CustomNameserver, {
    stables: ["nsName", "accountId", "nsSet", "zoneTag"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Account collection: `getCustomNameserver` is a paginated list
      // endpoint despite its name. Enumerate every page and hydrate each
      // nameserver into the exact `read` Attributes shape.
      return yield* customNameservers.getCustomNameserver.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) => page.result.map((ns) => toAttributes(ns, accountId))),
        ),
        // Unentitled accounts have no custom nameservers at all — the
        // collection endpoint rejects with a typed entitlement error.
        // Treat that as an empty collection rather than failing `list`.
        Effect.catchTag("CustomNameserversNotEnabled", () => Effect.succeed([] as Attributes[])),
      );
    }),

    diff: Effect.fn(function* ({ olds, news }) {
      if (!isResolved(news)) return undefined;
      // No prior props to compare against — let the engine decide.
      if (olds?.nsName === undefined) return undefined;
      // There is no update API: both the FQDN and the set number are
      // immutable, so any change is a replacement.
      if (olds.nsName !== news.nsName) {
        return { action: "replace" } as const;
      }
      if ((olds.nsSet ?? 1) !== (news.nsSet ?? 1)) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      const nsName = output?.nsName ?? olds?.nsName;
      if (nsName === undefined) return undefined;

      const observed = yield* findByName(acct, nsName);
      if (!observed) return undefined;

      // Owned path: we created this nameserver — refresh its attributes.
      if (output?.nsName) return toAttributes(observed, acct);

      // Adoption path: a nameserver with this FQDN already exists on the
      // account. Custom nameservers carry no ownership markers, so brand
      // it `Unowned` — the engine refuses to take over unless `adopt` is
      // set.
      return Unowned(toAttributes(observed, acct));
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;

      // 1. Observe — `nsName` is the nameserver's identity within the
      //    account; the cached `output` is at most a hint. The list is
      //    authoritative: a missing nameserver falls through to create.
      const observed = yield* findByName(output?.accountId ?? accountId, news.nsName);
      if (observed) {
        // 2. Sync — nothing is mutable (no update API); `diff` already
        //    replaces on nsName/nsSet changes, so observed state is final.
        return toAttributes(observed, output?.accountId ?? accountId);
      }

      // 3. Ensure — create when missing. A concurrent create surfaces as
      //    `CustomNameserverAlreadyExists`: converge by re-listing for
      //    the nameserver that won the race.
      const created = yield* customNameservers
        .createCustomNameserver({
          accountId,
          nsName: news.nsName,
          nsSet: news.nsSet,
        })
        .pipe(
          Effect.catchTag("CustomNameserverAlreadyExists", (error) =>
            findByName(accountId, news.nsName).pipe(
              Effect.flatMap((existing) =>
                existing ? Effect.succeed(existing) : Effect.fail(error),
              ),
            ),
          ),
        );
      return toAttributes(created, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Observe first — DELETE for an already-gone nameserver may not
      // return a decodable envelope, and a second destroy must be a
      // no-op either way.
      const observed = yield* findByName(output.accountId, output.nsName);
      if (!observed) return;
      yield* customNameservers
        .deleteCustomNameserver({
          accountId: output.accountId,
          customNsId: output.nsName,
        })
        .pipe(Effect.catchTag("CustomNameserverNotFound", () => Effect.void));
    }),
  });

type ObservedNameserver = customNameservers.GetCustomNameserverResponse["result"][number];

/**
 * Find a custom nameserver by exact FQDN on the account. The FQDN is the
 * nameserver's identity — Cloudflare rejects duplicates — so at most one
 * can match. `getCustomNameserver` is a list endpoint despite its name.
 */
const findByName = (accountId: string, nsName: string) =>
  customNameservers
    .getCustomNameserver({ accountId })
    .pipe(
      Effect.map((page) =>
        page.result.find((ns): ns is ObservedNameserver => ns.nsName === nsName),
      ),
    );

const toAttributes = (
  ns: ObservedNameserver | customNameservers.CreateCustomNameserverResponse,
  accountId: string,
): Attributes => ({
  nsName: ns.nsName,
  accountId,
  nsSet: ns.nsSet ?? undefined,
  // Distilled widens generated string enums to open unions (`string & {}`).
  status: ns.status as Status,
  dnsRecords: ns.dnsRecords.map((record) => ({
    type: (record.type ?? undefined) as "A" | "AAAA" | undefined,
    value: record.value ?? undefined,
  })),
  zoneTag: ns.zoneTag,
});