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

import * as web3 from "@distilled.cloud/cloudflare/web3";
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.HostnameContentList" as const;
type TypeId = typeof TypeId;

/**
 * The kind of content a content-list entry blocks: a CID (`cid`) or a
 * content path (`content_path`).
 */
export type ContentListEntryType = "cid" | "content_path";

/**
 * A single entry of an IPFS universal-path content list.
 */
export interface ContentListEntry {
  /**
   * The CID or content path of content to block, e.g.
   * `QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco` (`cid`) or
   * `/ipfs/QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco/wiki` (`content_path`).
   */
  content: string;
  /**
   * The type of content list entry to block.
   */
  type: ContentListEntryType;
  /**
   * An optional description of the content list entry.
   */
  description?: string;
}

export interface HostnameContentListProps {
  /**
   * The zone the hostname belongs to.
   *
   * Stable — moving to another zone triggers a replacement.
   */
  zoneId: string;
  /**
   * The Web3 hostname the content list belongs to. Must be an
   * `ipfs_universal_path` hostname — other targets reject content-list
   * operations.
   *
   * Stable — pointing at another hostname triggers a replacement.
   */
  hostnameId: string;
  /**
   * Behavior of the content list. Cloudflare currently only supports
   * `block`.
   * @default "block"
   */
  action?: "block";
  /**
   * The full desired set of content list entries. The list is replaced
   * declaratively on every change (bulk PUT) — entries not present here
   * are removed.
   * @default []
   */
  entries?: ContentListEntry[];
}

export interface HostnameContentListAttributes {
  /** The zone the hostname belongs to. */
  zoneId: string;
  /** The Web3 hostname the content list belongs to. */
  hostnameId: string;
  /** Behavior of the content list. */
  action: "block";
  /** The current content list entries. */
  entries: ContentListEntry[];
}

export type HostnameContentList = Resource<
  TypeId,
  HostnameContentListProps,
  HostnameContentListAttributes,
  never,
  Providers
>;

/**
 * The IPFS content-blocking list of a Web3 universal-path gateway hostname —
 * blocks specific CIDs or content paths from being served.
 *
 * The content list is a per-hostname singleton: it always exists for an
 * `ipfs_universal_path` hostname (empty by default), so this resource never
 * creates or deletes a physical object. Reconciliation replaces the whole
 * list declaratively via the bulk PUT, and destroy resets the list to empty.
 * ### Blocking content
 * **Example:** Block a CID and a content path
 * ```typescript
 * const gateway = yield* Cloudflare.Web3.Hostname("UniversalGateway", {
 *   zoneId: zone.zoneId,
 *   name: "gateway.example.com",
 *   target: "ipfs_universal_path",
 * });
 *
 * yield* Cloudflare.Web3.HostnameContentList("Blocklist", {
 *   zoneId: zone.zoneId,
 *   hostnameId: gateway.hostnameId,
 *   entries: [
 *     {
 *       type: "cid",
 *       content: "QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco",
 *       description: "blocked CID",
 *     },
 *     {
 *       type: "content_path",
 *       content: "/ipfs/QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco/wiki",
 *     },
 *   ],
 * });
 * ```
 *
 * **Example:** Clear the blocklist
 * ```typescript
 * // An empty entries array removes every block (also what destroy does).
 * yield* Cloudflare.Web3.HostnameContentList("Blocklist", {
 *   zoneId: zone.zoneId,
 *   hostnameId: gateway.hostnameId,
 *   entries: [],
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/web3/
 *
 * @resource
 * @product Web3
 * @category Domains & DNS
 */
export const HostnameContentList = Resource<HostnameContentList>(TypeId, {
  aliases: ["Cloudflare.Web3HostnameContentList"],
});

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

export const HostnameContentListProvider = () =>
  Provider.succeed(HostnameContentList, {
    stables: ["zoneId", "hostnameId"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // The content list is a per-hostname singleton keyed by
      // {zoneId, hostnameId}. Enumerate every zone, list its Web3
      // hostnames, keep only universal-path gateways (other targets
      // reject content-list ops), and read each one's list.
      const zones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        zones,
        (zone) =>
          web3.listHostnames.items({ zoneId: zone.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).filter(
                (h): h is typeof h & { id: string } =>
                  h.id != null && h.target === "ipfs_universal_path",
              ),
            ),
            Effect.flatMap((hostnames) =>
              Effect.forEach(
                hostnames,
                (h) =>
                  observeContentList(zone.id, h.id).pipe(
                    Effect.catchTag("Forbidden", () => Effect.undefined),
                  ),
                { concurrency: 10 },
              ),
            ),
            // Web3 is entitlement-gated and freshly minted tokens can
            // briefly 403 — skip zones we can't enumerate.
            Effect.catchTag("Forbidden", () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      return rows.flat().filter((row): row is HostnameContentListAttributes => row !== undefined);
    }),

    diff: Effect.fn(function* ({ olds = {}, news, output }) {
      const o = olds as Partial<HostnameContentListProps>;
      const n = news as HostnameContentListProps;
      // zoneId/hostnameId are Input<string>; compare only once both
      // sides are concrete. The content list is a sub-singleton of the
      // hostname — pointing elsewhere replaces it.
      const oldZone = output?.zoneId ?? o.zoneId;
      if (typeof oldZone === "string" && typeof n.zoneId === "string" && oldZone !== n.zoneId) {
        return { action: "replace" } as const;
      }
      const oldHostname = output?.hostnameId ?? o.hostnameId;
      if (
        typeof oldHostname === "string" &&
        typeof n.hostnameId === "string" &&
        oldHostname !== n.hostnameId
      ) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (typeof olds?.zoneId === "string" ? olds.zoneId : undefined);
      const hostnameId =
        output?.hostnameId ?? (typeof olds?.hostnameId === "string" ? olds.hostnameId : undefined);
      if (zoneId === undefined || hostnameId === undefined) return undefined;
      // Settings-singleton semantics: the list always exists for a
      // universal-path hostname (empty by default), so it is never
      // `Unowned`. A deleted hostname reads as gone.
      return yield* observeContentList(zoneId, hostnameId);
    }),

    reconcile: Effect.fn(function* ({ news }) {
      // Inputs have been resolved to concrete strings by Plan.
      const zoneId = news.zoneId as string;
      const hostnameId = news.hostnameId as string;
      const desired: HostnameContentListAttributes = {
        zoneId,
        hostnameId,
        action: news.action ?? "block",
        entries: news.entries ?? [],
      };

      // Observe — read the live list; the singleton always exists for a
      // universal-path hostname, so "missing" only means the hostname
      // itself is gone (which is a real failure for reconcile).
      const observed = yield* observeContentList(zoneId, hostnameId);

      // Sync — the bulk PUT replaces action + entries declaratively;
      // skip the API call entirely on a no-op.
      if (observed && sameContentList(observed, desired)) {
        return observed;
      }
      yield* web3.putHostnameIpfsUniversalPathContentList({
        zoneId,
        identifier: hostnameId,
        action: desired.action,
        entries: desired.entries,
      });
      return desired;
    }),

    delete: Effect.fn(function* ({ output }) {
      // There is no DELETE endpoint — destroying the resource resets the
      // singleton to its empty default. If the hostname itself is already
      // gone (or no longer a universal-path gateway), there is nothing
      // left to reset.
      yield* web3
        .putHostnameIpfsUniversalPathContentList({
          zoneId: output.zoneId,
          identifier: output.hostnameId,
          action: "block",
          entries: [],
        })
        .pipe(
          Effect.catchTag(["Web3HostnameNotFound", "InvalidWeb3HostnameTarget"], () => Effect.void),
        );
    }),
  });

/**
 * Read the content list (action) plus its entries, mapping a gone hostname
 * (`Web3HostnameNotFound`, code 1002) or a hostname that is not a
 * universal-path gateway (`InvalidWeb3HostnameTarget`, code 1006) to
 * `undefined`.
 */
const observeContentList = (zoneId: string, hostnameId: string) =>
  Effect.gen(function* () {
    const list = yield* web3.getHostnameIpfsUniversalPathContentList({
      zoneId,
      identifier: hostnameId,
    });
    const entries = yield* web3.listHostnameIpfsUniversalPathContentListEntries({
      zoneId,
      identifier: hostnameId,
    });
    return {
      zoneId,
      hostnameId,
      action: (list.action ?? "block") as "block",
      entries: (entries.entries ?? []).map((entry): ContentListEntry => ({
        content: entry.content ?? "",
        type: (entry.type ?? "cid") as ContentListEntryType,
        ...(entry.description != null ? { description: entry.description } : {}),
      })),
    } satisfies HostnameContentListAttributes;
  }).pipe(
    Effect.catchTag(["Web3HostnameNotFound", "InvalidWeb3HostnameTarget"], () => Effect.undefined),
  );

/**
 * Order-insensitive comparison of two content lists by (content, type,
 * description).
 */
const sameContentList = (
  observed: HostnameContentListAttributes,
  desired: HostnameContentListAttributes,
) =>
  observed.action === desired.action &&
  observed.entries.length === desired.entries.length &&
  serializeEntries(observed.entries) === serializeEntries(desired.entries);

const serializeEntries = (entries: ContentListEntry[]) =>
  entries
    .map((entry) => `${entry.type}${entry.content}${entry.description ?? ""}`)
    .sort()
    .join("");