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

import * as rules from "@distilled.cloud/cloudflare/rules";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.Rules.List" as const;
type TypeId = typeof TypeId;

/**
 * The type of a list. Each kind supports specific list items: IP addresses,
 * ASNs, hostnames, or URL redirects. Cannot be changed after creation.
 */
export type ListKind = "ip" | "asn" | "hostname" | "redirect";

/**
 * An item in an `ip` list — an IPv4/IPv6 address or CIDR range
 * (IPv4 prefixes /8–/32, IPv6 prefixes /4–/64).
 */
export type ListIpItem = {
  /**
   * An IPv4 address, IPv4 CIDR, IPv6 address, or IPv6 CIDR.
   */
  ip: string;
  /**
   * An informative summary of the item.
   */
  comment?: string;
};

/**
 * An item in an `asn` list — an autonomous system number.
 */
export type ListAsnItem = {
  /**
   * A non-negative 32 bit integer.
   */
  asn: number;
  /**
   * An informative summary of the item.
   */
  comment?: string;
};

/**
 * An item in a `hostname` list.
 */
export type ListHostnameItem = {
  /**
   * Valid characters for hostnames are ASCII(7) letters from a to z, the
   * digits from 0 to 9, wildcards (*), and the hyphen (-).
   */
  hostname: {
    /**
     * The hostname to match, e.g. `example.com` or `*.example.com`.
     */
    urlHostname: string;
    /**
     * Only applies to wildcard hostnames (e.g., *.example.com). When `true`,
     * only subdomains are blocked. When `false`, both the root domain and
     * subdomains are blocked.
     * @default false
     */
    excludeExactHostname?: boolean;
  };
  /**
   * An informative summary of the item.
   */
  comment?: string;
};

/**
 * An item in a `redirect` list — a source/target URL pair used by Bulk
 * Redirect rules.
 */
export type ListRedirectItem = {
  /**
   * The definition of the redirect.
   */
  redirect: {
    /**
     * The source URL to match, e.g. `example.com/old-path`.
     */
    sourceUrl: string;
    /**
     * The URL to redirect to.
     */
    targetUrl: string;
    /**
     * Whether the redirect also matches subdomains of the source URL.
     * @default false
     */
    includeSubdomains?: boolean;
    /**
     * Whether the redirect target URL keeps the path suffix of the request.
     * @default false
     */
    preservePathSuffix?: boolean;
    /**
     * Whether the redirect target URL keeps the query string of the request.
     * @default false
     */
    preserveQueryString?: boolean;
    /**
     * The HTTP status code used for the redirect.
     * @default 301
     */
    statusCode?: 301 | 302 | 307 | 308;
    /**
     * Whether the redirect also matches subpaths of the source URL.
     * @default false
     */
    subpathMatching?: boolean;
  };
  /**
   * An informative summary of the item.
   */
  comment?: string;
};

/**
 * An item in an account list. The shape must match the list `kind`:
 * `{ ip }` for `ip` lists, `{ asn }` for `asn` lists, `{ hostname }` for
 * `hostname` lists, and `{ redirect }` for `redirect` lists.
 */
export type ListItem = ListIpItem | ListAsnItem | ListHostnameItem | ListRedirectItem;

export type ListProps = {
  /**
   * An informative name for the list, used in filter and rule expressions
   * (e.g. `ip.src in $my_list`). Must contain only letters, numbers, and
   * underscores (max 50 characters). If omitted, a unique name is generated
   * from the app, stage, and logical ID. Cannot be changed after creation —
   * updating this property triggers a replacement.
   * @default ${app}_${stage}_${id}
   */
  name?: string;
  /**
   * The type of the list. Each kind supports specific list items
   * (IP addresses, ASNs, hostnames, or redirects). Cannot be changed after
   * creation — updating this property triggers a replacement.
   */
  kind: ListKind;
  /**
   * An informative summary of the list.
   */
  description?: string;
  /**
   * The full contents of the list. Items are replaced idempotently via the
   * bulk items operation: the provider diffs the observed items against this
   * desired set and, on any delta, replaces the entire list contents and
   * polls the asynchronous bulk operation to completion.
   * @default []
   */
  items?: ListItem[];
};

export type ListAttributes = {
  /**
   * The unique ID of the list.
   */
  listId: string;
  /**
   * The Cloudflare account the list belongs to.
   */
  accountId: string;
  /**
   * The name of the list, usable in rule expressions as `$name`.
   */
  name: string;
  /**
   * The type of the list.
   */
  kind: ListKind;
  /**
   * An informative summary of the list.
   */
  description: string | undefined;
  /**
   * The number of items in the list.
   */
  numItems: number;
  /**
   * The number of filters referencing the list.
   */
  numReferencingFilters: number;
  /**
   * The RFC 3339 timestamp of when the list was created.
   */
  createdOn: string;
  /**
   * The RFC 3339 timestamp of when the list was last modified.
   */
  modifiedOn: string;
};

export type List = Resource<TypeId, ListProps, ListAttributes, never, Providers>;

/**
 * A Cloudflare account-level List (Lists API) — a named collection of IP
 * addresses, ASNs, hostnames, or URL redirects referenced from ruleset
 * expressions (`ip.src in $my_list`) and Bulk Redirect rules.
 *
 * `name` and `kind` are immutable and changing either triggers a
 * replacement. The list's items are managed as part of the resource: on any
 * change the full contents are replaced via the asynchronous bulk items
 * operation, which the provider polls to completion.
 * ### Creating a List
 * **Example:** IP list with items
 * ```typescript
 * const blocklist = yield* Cloudflare.Rules.List("blocklist", {
 *   kind: "ip",
 *   description: "Known bad actors",
 *   items: [
 *     { ip: "203.0.113.7", comment: "scanner" },
 *     { ip: "198.51.100.0/24" },
 *   ],
 * });
 * ```
 *
 * **Example:** ASN list with an explicit name
 * ```typescript
 * const asns = yield* Cloudflare.Rules.List("bad-asns", {
 *   name: "bad_asns",
 *   kind: "asn",
 *   items: [{ asn: 64496 }, { asn: 64511, comment: "spam network" }],
 * });
 * ```
 *
 * ### Bulk Redirects
 * A zone's `http_request_dynamic_redirect` phase caps the number of rules
 * (10 on most plans). Bulk Redirects scale past that: put every mapping in a
 * `redirect` list and reference it from a single rule in the account's
 * `http_request_redirect` phase.
 *
 * **Example:** Redirect retired paths with one rule
 * ```typescript
 * const retired = yield* Cloudflare.Rules.List("RetiredSlugs", {
 *   kind: "redirect",
 *   items: [
 *     {
 *       redirect: {
 *         sourceUrl: "example.com/services/old-slug",
 *         targetUrl: "https://example.com/services/new-slug",
 *         statusCode: 301,
 *         preserveQueryString: true,
 *       },
 *     },
 *   ],
 * });
 *
 * yield* Cloudflare.Ruleset.AccountEntrypoint("BulkRedirects", {
 *   phase: "http_request_redirect",
 *   rules: [
 *     {
 *       ref: "retired_slugs",
 *       expression: Output.interpolate`http.request.full_uri in ${retired.name}`,
 *       action: "redirect",
 *       actionParameters: {
 *         fromList: { name: retired.name, key: "http.request.full_uri" },
 *       },
 *     },
 *   ],
 * });
 * ```
 *
 * ### Referencing a List from rules
 * **Example:** Use the list name in a Ruleset expression
 * ```typescript
 * const list = yield* Cloudflare.Rules.List("blocklist", { kind: "ip" });
 *
 * // The stable `name` attribute interpolates into rule expressions:
 * // `ip.src in 

Loading Sailfork

lt;name>` * const expression = list.name.apply((name) => `ip.src in ${name}`); * ``` * * @see https://developers.cloudflare.com/waf/tools/lists/ * * @resource * @product Rules * @category Rules & Configuration */ export const List = Resource<List>(TypeId); /** * Returns true if the given value is a List resource. */ export const isList = (value: unknown): value is List => Predicate.hasProperty(value, "Type") && value.Type === TypeId; /** * The asynchronous bulk items operation finished in a non-`completed` * state (or never completed within the polling budget). */ export class ListBulkOperationError extends Data.TaggedError("ListBulkOperationError")<{ readonly operationId: string; readonly status: string; readonly message?: string; }> {} export const ListProvider = () => Provider.succeed(List, { stables: ["listId", "accountId", "name", "kind", "createdOn"], list: Effect.fn(function* () { const { accountId } = yield* yield* CloudflareEnvironment; return yield* rules.listLists.items({ accountId }).pipe( Stream.map((list) => toAttributes(list, accountId)), Stream.runCollect, Effect.map((chunk) => Array.from(chunk)), ); }), diff: Effect.fn(function* ({ olds, news, output }) { const { accountId } = yield* yield* CloudflareEnvironment; if (!isResolved(news)) return undefined; if ((output?.accountId ?? accountId) !== accountId) { return { action: "replace" } as const; } // Lists cannot be renamed and the kind is immutable. const oldName = output?.name ?? olds?.name; // Auto-generated names are engine-owned: the deployed name stays // authoritative even if the generator would name this id differently // today. Only an explicit user-provided name can force a replace. const desiredName = news.name ?? oldName; if (oldName !== undefined && desiredName !== oldName) { return { action: "replace" } as const; } const oldKind = output?.kind ?? olds?.kind; if (oldKind !== undefined && news.kind !== oldKind) { // List names are unique per account. When the name is unchanged the // replacement cannot be create-first (the create would collide with // the old list), so delete the old list before creating the new one. return { action: "replace", deleteFirst: true } as const; } return undefined; }), read: Effect.fn(function* ({ id, output, olds }) { const { accountId } = yield* yield* CloudflareEnvironment; const acct = output?.accountId ?? accountId; if (output?.listId) { const observed = yield* getListById(acct, output.listId); return observed ? toAttributes(observed, acct) : undefined; } // Cold read — recover from lost state by matching the deterministic // physical name. List names are unique per account, so an exact match // is authoritative. const name = yield* createListName(id, olds?.name); const match = yield* findByName(acct, name); return match ? toAttributes(match, acct) : undefined; }), reconcile: Effect.fn(function* ({ id, news, output }) { const { accountId } = yield* yield* CloudflareEnvironment; // Prefer the deployed name: regenerating would target a different // resource if the generator's output for this id ever drifts. const name = yield* createListName(id, news.name ?? output?.name); // Observe — the listId cached on `output` is a hint, not a guarantee: // a missing list falls through to "missing" and ensure recreates. let observed = output?.listId ? yield* getListById(output.accountId ?? accountId, output.listId) : undefined; const acct = observed ? (output?.accountId ?? accountId) : accountId; // Ensure — create when missing. A duplicate-name conflict is a race // (or an out-of-band create): adopt the existing list with that name // when its kind matches. When the kind differs the list cannot be // converged in place (kind is immutable and names are unique), so the // stale list is deleted and recreated — this is how a replacement of // an explicitly-named list lands, since a create-first replacement // would always collide on the name. if (!observed) { const create = rules.createList({ accountId: acct, name, kind: news.kind, description: news.description, }); observed = yield* create.pipe( Effect.catchTag("ListAlreadyExists", (error) => findByName(acct, name).pipe( Effect.flatMap((match) => { if (!match) return Effect.fail(error); if (match.kind === news.kind) return Effect.succeed(match); return rules.deleteList({ accountId: acct, listId: match.id }).pipe( Effect.catchTag("ListNotFound", () => Effect.void), Effect.andThen(create), ); }), ), ), ); } // Sync description — diff observed cloud state against desired and // skip the API call entirely on a no-op. if ((observed.description ?? undefined) !== news.description) { observed = yield* rules.updateList({ accountId: acct, listId: observed.id, description: news.description, }); } // Sync items — read the observed items fresh from the cloud, compare // against the desired set (keyed on value fields + comment, ignoring // server-assigned ids/timestamps), and on any delta replace the full // contents via the asynchronous bulk PUT, polling it to completion. const desiredItems = news.items ?? []; const observedItems = yield* listAllItems(acct, observed.id); if (!sameItems(observedItems, desiredItems)) { const { operationId } = yield* rules.updateListItem({ accountId: acct, listId: observed.id, body: desiredItems, }); yield* awaitBulkOperation(acct, operationId); } // Return — re-read so eventually-consistent counters (numItems) and // timestamps are as fresh as possible. const final = yield* getListById(acct, observed.id); return toAttributes(final ?? observed, acct); }), delete: Effect.fn(function* ({ output }) { // Cloudflare's delete is itself idempotent (deleting a missing list // succeeds), but tolerate a typed not-found anyway. yield* rules .deleteList({ accountId: output.accountId, listId: output.listId, }) .pipe(Effect.catchTag("ListNotFound", () => Effect.void)); }), }); type ObservedList = rules.GetListResponse; /** * List names only allow letters, numbers, and underscores (max 50 chars), so * the generated physical name swaps the default hyphen delimiter for an * underscore. */ const createListName = (id: string, name: string | undefined) => Effect.gen(function* () { if (name !== undefined) return name; const generated = yield* createPhysicalName({ id, lowercase: true, delimiter: "_", maxLength: 50, }); return generated.replaceAll("-", "_"); }); /** * Read a list by id, mapping "gone" (`ListNotFound`, Cloudflare error code * 10001) to `undefined`. */ const getListById = (accountId: string, listId: string) => rules .getList({ accountId, listId }) .pipe(Effect.catchTag("ListNotFound", () => Effect.undefined)); /** * Find a list by exact name. List names are unique per account. */ const findByName = (accountId: string, name: string) => rules.listLists.items({ accountId }).pipe( Stream.filter((list) => list.name === name), Stream.runHead, Effect.map(Option.getOrUndefined), ); /** * Read the full observed contents of a list (all pages). */ const listAllItems = (accountId: string, listId: string) => rules.listListItems.items({ accountId, listId }).pipe( Stream.runCollect, Effect.map((chunk) => Array.from(chunk)), ); type ComparableItem = ListItem | rules.GetListItemResponse; /** * Canonicalize an item (desired prop or observed response) into a stable * string key: server-assigned ids/timestamps are ignored and optional fields * are normalized to their API defaults so omitted props compare equal to the * defaults the API materializes. */ const canonicalItem = (item: ComparableItem): string => { const comment = "comment" in item && item.comment != null && item.comment !== "" ? item.comment : undefined; if ("ip" in item) { return JSON.stringify({ ip: item.ip, comment }); } if ("asn" in item) { return JSON.stringify({ asn: item.asn, comment }); } if ("hostname" in item) { return JSON.stringify({ hostname: { urlHostname: item.hostname.urlHostname, excludeExactHostname: item.hostname.excludeExactHostname ?? false, }, comment, }); } return JSON.stringify({ redirect: { sourceUrl: item.redirect.sourceUrl, targetUrl: item.redirect.targetUrl, includeSubdomains: item.redirect.includeSubdomains ?? false, preservePathSuffix: item.redirect.preservePathSuffix ?? false, preserveQueryString: item.redirect.preserveQueryString ?? false, statusCode: item.redirect.statusCode ?? 301, subpathMatching: item.redirect.subpathMatching ?? false, }, comment, }); }; /** * Compare observed and desired items as multisets of canonical keys. */ const sameItems = (observed: readonly ComparableItem[], desired: readonly ComparableItem[]) => { if (observed.length !== desired.length) return false; const a = observed.map(canonicalItem).sort(); const b = desired.map(canonicalItem).sort(); return a.every((key, i) => key === b[i]); }; /** * Poll an asynchronous bulk items operation until it reaches a terminal * state, failing with a typed error when it does not complete successfully. */ const awaitBulkOperation = (accountId: string, operationId: string) => Effect.gen(function* () { const operation = yield* rules.getListBulkOperation({ accountId, operationId }).pipe( Effect.repeat({ schedule: Schedule.spaced("2 seconds"), until: (op) => op.status === "completed" || op.status === "failed", times: 90, }), ); if (operation.status !== "completed") { return yield* new ListBulkOperationError({ operationId, status: operation.status, message: "error" in operation ? operation.error : undefined, }); } }); const toAttributes = (list: ObservedList, accountId: string): ListAttributes => ({ listId: list.id, accountId, name: list.name, // Distilled widens generated string enums to open unions (`string & {}`). kind: list.kind as ListKind, description: list.description ?? undefined, numItems: list.numItems, numReferencingFilters: list.numReferencingFilters, createdOn: list.createdOn, modifiedOn: list.modifiedOn, });