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

import * as web3 from "@distilled.cloud/cloudflare/web3";
import { Unowned } from "alchemy/AdoptPolicy";
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";
import { listAllZones } from "../Zone/lookup.ts";

const TypeId = "Cloudflare.Web3.Hostname" as const;
type TypeId = typeof TypeId;

/**
 * The gateway a Web3 hostname resolves through: an Ethereum gateway, an
 * IPFS gateway pinned to a single DNSLink, or an IPFS universal-path
 * gateway that can serve any CID under `/ipfs/...` / `/ipns/...`.
 */
export type HostnameTarget = "ethereum" | "ipfs" | "ipfs_universal_path";

/**
 * Activation status of a Web3 hostname. Hostnames start `pending` until the
 * CNAME is verified at the edge; deletion is asynchronous (`deleting`).
 */
export type HostnameStatus = "active" | "pending" | "deleting" | "error";

export interface HostnameProps {
  /**
   * The zone the hostname is created in. The hostname must be a subdomain
   * of (or equal to) the zone's name.
   *
   * Stable — moving a hostname to another zone triggers a replacement.
   */
  zoneId: string;
  /**
   * The hostname that points to the target gateway via CNAME, e.g.
   * `gateway.example.com`.
   *
   * Immutable — the hostname is the resource's identity and cannot be
   * renamed, so changing it triggers a replacement.
   */
  name: string;
  /**
   * The target gateway of the hostname.
   *
   * Immutable — the API cannot change a hostname's target after creation,
   * so changing it triggers a replacement.
   */
  target: HostnameTarget;
  /**
   * The DNSLink value used when `target` is `ipfs`, e.g.
   * `/ipns/onboarding.ipfs.cloudflare.com`. Mutable — patched in place.
   */
  dnslink?: string;
  /**
   * An optional description of the hostname. Mutable — patched in place.
   */
  description?: string;
}

export interface HostnameAttributes {
  /** Cloudflare-assigned identifier of the Web3 hostname. */
  hostnameId: string;
  /** The zone the hostname belongs to. */
  zoneId: string;
  /** The hostname that points to the target gateway via CNAME. */
  name: string;
  /** The target gateway of the hostname. */
  target: HostnameTarget;
  /** The DNSLink value, if the target is `ipfs`. */
  dnslink: string | undefined;
  /** The hostname's description, if set. */
  description: string | undefined;
  /** Activation status of the hostname. */
  status: HostnameStatus;
  /** ISO8601 creation timestamp. */
  createdOn: string | undefined;
  /** ISO8601 last-modified timestamp. */
  modifiedOn: string | undefined;
}

export type Hostname = Resource<TypeId, HostnameProps, HostnameAttributes, never, Providers>;

/**
 * A Cloudflare Web3 gateway hostname — serve Ethereum or IPFS content from
 * a hostname on your zone via Cloudflare's distributed web gateways.
 *
 * A hostname's identity is its `name` within the zone; only `dnslink` and
 * `description` are mutable, so changing `name`, `target`, or `zoneId`
 * triggers a replacement. Hostnames activate asynchronously: they start in
 * `pending` status and flip to `active` once the CNAME is verified.
 *
 * Note: Cloudflare has restricted Web3 gateways for new customers — on
 * accounts without the entitlement, creation fails with the typed
 * `Web3HostnameNotEntitled` error.
 *
 * Safety: Web3 hostnames carry no ownership markers. When there is no prior
 * state, `read` scans the zone for an existing hostname with the same name
 * and reports it as `Unowned`, so the engine refuses to take it over unless
 * `--adopt` (or `adopt(true)`) is set.
 * ### IPFS gateway
 * **Example:** IPFS hostname pinned to a DNSLink
 * ```typescript
 * const gateway = yield* Cloudflare.Web3.Hostname("IpfsGateway", {
 *   zoneId: zone.zoneId,
 *   name: "ipfs.example.com",
 *   target: "ipfs",
 *   dnslink: "/ipns/onboarding.ipfs.cloudflare.com",
 *   description: "IPFS gateway for example.com",
 * });
 * ```
 *
 * **Example:** IPFS universal-path gateway
 * ```typescript
 * // Serves any CID under /ipfs/... and /ipns/... paths.
 * const universal = yield* Cloudflare.Web3.Hostname("UniversalGateway", {
 *   zoneId: zone.zoneId,
 *   name: "gateway.example.com",
 *   target: "ipfs_universal_path",
 * });
 * ```
 *
 * ### Ethereum gateway
 * **Example:** Ethereum RPC hostname
 * ```typescript
 * yield* Cloudflare.Web3.Hostname("EthGateway", {
 *   zoneId: zone.zoneId,
 *   name: "eth.example.com",
 *   target: "ethereum",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/web3/
 *
 * @resource
 * @product Web3
 * @category Domains & DNS
 */
export const Hostname = Resource<Hostname>(TypeId, {
  aliases: ["Cloudflare.Web3Hostname"],
});

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

export const HostnameProvider = () =>
  Provider.succeed(Hostname, {
    stables: ["hostnameId", "zoneId", "name", "target", "createdOn"],

    // Web3 hostnames live inside a zone (`/zones/{id}/web3/hostnames`) with no
    // account-wide enumeration API, so fan out over every zone via
    // `listAllZones` and exhaustively paginate the per-zone list. Zones without
    // the Web3 entitlement (or where the scoped token lacks access) answer
    // `Forbidden` — skip them rather than failing the whole enumeration.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const zones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        zones,
        (zone) =>
          web3.listHostnames.pages({ zoneId: zone.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? [])
                  .filter((raw) => raw.status !== "deleting")
                  .map((raw): HostnameAttributes => toAttributes(raw, zone.id)),
              ),
            ),
            Effect.catchTag("Forbidden", () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),

    diff: Effect.fn(function* ({ olds = {}, news, output }) {
      const o = olds as Partial<HostnameProps>;
      const n = news as HostnameProps;
      const oldName = output?.name ?? o.name;
      const oldTarget = output?.target ?? o.target;
      if (oldName === undefined && oldTarget === undefined) return undefined;
      // The hostname is the resource's identity — no rename API exists.
      if (oldName !== undefined && oldName !== n.name) {
        return { action: "replace" } as const;
      }
      // The target gateway is immutable after creation.
      if (oldTarget !== undefined && oldTarget !== n.target) {
        return { action: "replace" } as const;
      }
      // zoneId is Input<string>; compare only once both are concrete.
      const oldZone = output?.zoneId ?? o.zoneId;
      if (typeof oldZone === "string" && typeof n.zoneId === "string" && oldZone !== n.zoneId) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (typeof olds?.zoneId === "string" ? olds.zoneId : undefined);
      if (zoneId === undefined) return undefined;

      // Owned path: refresh by our persisted hostname id.
      if (output?.hostnameId) {
        const observed = yield* getHostname(zoneId, output.hostnameId);
        if (observed) return toAttributes(observed, zoneId);
      }

      // Cold lookup: a hostname with this name may already exist in the
      // zone. Web3 hostnames carry no ownership markers, so we cannot
      // prove we created it — brand it `Unowned` so the engine refuses
      // to take over unless `adopt` is set.
      const name = output?.name ?? olds?.name;
      if (name !== undefined) {
        const observed = yield* findByName(zoneId, name);
        if (observed) return Unowned(toAttributes(observed, zoneId));
      }
      return undefined;
    }),

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

      // 1. Observe — the hostname id cached on `output` is a hint, not a
      //    guarantee: a missing hostname falls through to the name scan
      //    and then to create.
      let observed = output?.hostnameId ? yield* getHostname(zoneId, output.hostnameId) : undefined;

      // 2. Fall back to scanning the zone for a name match. Ownership has
      //    already been verified upstream — `read` reports existing
      //    hostnames as `Unowned` and the engine gates takeover behind
      //    the adopt policy before reconcile ever runs.
      if (!observed) {
        observed = yield* findByName(zoneId, news.name);
      }

      // 3. Ensure — create when missing. Hostnames activate
      //    asynchronously; return the `pending` state as-is rather than
      //    polling for `active` (activation depends on CNAME/edge
      //    propagation outside our control).
      if (!observed) {
        const created = yield* web3.createHostname({
          zoneId,
          name: news.name,
          target: news.target,
          dnslink: news.dnslink,
          description: news.description,
        });
        return toAttributes(created, zoneId);
      }

      // 4. Sync — diff observed dnslink/description against desired;
      //    skip the patch call entirely on a no-op.
      const dirty =
        (news.dnslink !== undefined && (observed.dnslink ?? undefined) !== news.dnslink) ||
        (news.description !== undefined &&
          (observed.description ?? undefined) !== news.description);
      if (dirty) {
        observed = yield* web3.patchHostname({
          zoneId,
          identifier: observed.id ?? "",
          dnslink: news.dnslink,
          description: news.description,
        });
      }

      return toAttributes(observed, zoneId);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Deletion is asynchronous (the hostname lingers in `deleting`
      // status); a hostname that is already gone answers 404 with the
      // typed Web3HostnameNotFound tag — treat it as done.
      yield* web3
        .deleteHostname({
          zoneId: output.zoneId,
          identifier: output.hostnameId,
        })
        .pipe(Effect.catchTag("Web3HostnameNotFound", () => Effect.void));
    }),
  });

type ObservedHostname = web3.GetHostnameResponse;

/**
 * Read a hostname by id, mapping "gone" (`Web3HostnameNotFound`, Cloudflare
 * error code 1002 "Hostname does not exist.") to `undefined`. A hostname in
 * `deleting` status is treated as already gone — it cannot be converged.
 */
const getHostname = (zoneId: string, hostnameId: string) =>
  web3.getHostname({ zoneId, identifier: hostnameId }).pipe(
    Effect.map((hostname): ObservedHostname | undefined =>
      hostname.status === "deleting" ? undefined : hostname,
    ),
    Effect.catchTag("Web3HostnameNotFound", () => Effect.undefined),
  );

/**
 * Find a hostname by exact name within the zone. The name is a hostname's
 * identity — Cloudflare rejects duplicates — so at most one (non-deleting)
 * hostname can match.
 */
const findByName = (zoneId: string, name: string) =>
  web3.listHostnames.items({ zoneId }).pipe(
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk).find(
        (hostname): hostname is ObservedHostname =>
          hostname.name === name && hostname.status !== "deleting",
      ),
    ),
  );

const toAttributes = (hostname: ObservedHostname, zoneId: string): HostnameAttributes => ({
  // Cloudflare always echoes id/name/target/status for a persisted
  // hostname — distilled just types every response field as optional.
  hostnameId: hostname.id ?? "",
  zoneId,
  name: hostname.name ?? "",
  target: (hostname.target ?? "ipfs") as HostnameTarget,
  dnslink: hostname.dnslink ?? undefined,
  description: hostname.description ?? undefined,
  status: (hostname.status ?? "pending") as HostnameStatus,
  createdOn: hostname.createdOn ?? undefined,
  modifiedOn: hostname.modifiedOn ?? undefined,
});