sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Gateway/ List.ts
import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { arrayEqualsUnordered } from "alchemy/Util/equal";
import * as Data from "effect/Data";
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";
export class ListUnexpectedResponse extends Data.TaggedError("ListUnexpectedResponse")<{
readonly message: string;
readonly cause?: unknown;
}> {}
const TypeId = "Cloudflare.Gateway.List" as const;
type TypeId = typeof TypeId;
/**
* The kind of values a Gateway list holds. Immutable — changing the type
* triggers a replacement.
*/
export type ListType =
| "SERIAL"
| "URL"
| "DOMAIN"
| "EMAIL"
| "IP"
| "CATEGORY"
| "LOCATION"
| "DEVICE"
| "AAGUID";
/**
* A single entry in a Gateway list.
*/
export interface ListItem {
/**
* The item's value — a domain, URL, IP, email, serial number, etc.
* depending on the list's `type`.
*/
value: string;
/**
* Optional free-form description of the item.
*/
description?: string;
}
export interface ListProps {
/**
* Display name for the list. Used as a stable identifier so the provider
* can locate the list by name during adoption / state recovery. If
* omitted, a unique name is generated from the app, stage, and logical ID.
*
* @default ${app}-${stage}-${id}
*/
name?: string;
/**
* The kind of values the list holds (DOMAIN, IP, URL, EMAIL, SERIAL,
* CATEGORY, LOCATION, DEVICE, AAGUID). Immutable — changing the type
* triggers a replacement.
*/
type: ListType;
/**
* Free-form description of the list. Mutable.
*
* @default ""
*/
description?: string;
/**
* Entries in the list. Reconciled as a full set via PUT — items present
* here and missing in the cloud are added; extra cloud items are removed.
*
* @default []
*/
items?: ListItem[];
}
export interface ListAttributes {
/** UUID of the list, assigned by Cloudflare. */
listId: string;
/** Cloudflare account that owns the list. */
accountId: string;
/** Display name of the list. */
name: string;
/** The kind of values the list holds. */
type: ListType;
/** Description of the list. */
description: string;
/** Current entries in the list. */
items: ListItem[];
/** Number of entries in the list. */
count: number;
/** ISO8601 creation timestamp. */
createdAt: string | undefined;
/** ISO8601 last-update timestamp. */
updatedAt: string | undefined;
}
export type List = Resource<TypeId, ListProps, ListAttributes, never, Providers>;
/**
* A Cloudflare Zero Trust Gateway list — a named set of domains, IPs,
* URLs, emails, serial numbers, or device IDs referenced from Gateway
* rule wirefilter expressions by UUID (`Loading Sailfork
lt;listId>`).
*
* The list's `type` is immutable (changing it replaces the list); name,
* description, and items all converge in place. Items are managed as a
* full set — the provider PUTs the complete desired item set and removes
* anything not declared.
* ### Creating a List
* **Example:** Domain list
* ```typescript
* const blocked = yield* Cloudflare.Gateway.List("BlockedDomains", {
* type: "DOMAIN",
* description: "domains blocked org-wide",
* items: [
* { value: "badsite.example.com" },
* { value: "malware.example.net", description: "known C2" },
* ],
* });
* ```
*
* **Example:** IP list
* ```typescript
* const egress = yield* Cloudflare.Gateway.List("OfficeEgress", {
* type: "IP",
* items: [{ value: "203.0.113.0/24" }],
* });
* ```
*
* ### Referencing from a Gateway Rule
* **Example:** Block DNS lookups for every domain in the list
* ```typescript
* yield* Cloudflare.Gateway.Rule("BlockListedDomains", {
* action: "block",
* filters: ["dns"],
* traffic: `any(dns.domains[*] in ${blocked.listId})`,
* });
* ```
*
* @see https://developers.cloudflare.com/cloudflare-one/policies/gateway/lists/
*
* @resource
* @product Gateway
* @category Cloudflare One (Zero Trust)
*/
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;
export const ListProvider = () =>
Provider.succeed(List, {
stables: ["listId", "accountId", "type", "createdAt"],
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
const lists = yield* zeroTrust.listGatewayLists.items({ accountId }).pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk)),
);
return lists.map((list) => toAttributes(list, accountId));
}),
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;
}
// The list type is immutable on Cloudflare's side.
const oldType = output?.type ?? (olds as ListProps).type;
if (oldType !== undefined && oldType !== news.type) {
return { action: "replace" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ id, output, olds }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const acct = output?.accountId ?? accountId;
// Owned path — refresh by the cached list id.
if (output?.listId) {
const observed = yield* getList(acct, output.listId);
if (observed) return toAttributes(observed, acct);
}
// Cold read — locate by deterministic name. Gateway lists carry no
// ownership markers, so report the match as Unowned to gate adoption.
const name = yield* resolveName(id, olds?.name ?? output?.name);
const match = yield* findByName(acct, name);
if (match?.id) {
const observed = yield* getList(acct, match.id);
if (observed) return Unowned(toAttributes(observed, acct));
}
return undefined;
}),
reconcile: Effect.fn(function* ({ id, news, output }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const name = yield* resolveName(id, news.name);
const desiredItems = news.items ?? [];
// 1. Observe — the cached id is a hint, not a guarantee; fall back
// to a name scan so out-of-band deletes / lost state converge.
let observed = output?.listId ? yield* getList(accountId, output.listId) : undefined;
if (!observed) {
const match = yield* findByName(accountId, name);
if (match?.id) observed = yield* getList(accountId, match.id);
}
// 2. Ensure — create with the full desired body when missing. Names
// are not unique on Cloudflare's side, so there is no
// AlreadyExists race to tolerate.
if (!observed) {
const created = yield* zeroTrust.createGatewayList({
accountId,
name,
type: news.type,
description: news.description,
items: desiredItems,
});
if (!created.id) {
return yield* new ListUnexpectedResponse({
message: "Cloudflare did not return an id for the Gateway list",
});
}
// Create echoes items without count — re-read for a full shape.
const fresh = yield* getList(accountId, created.id);
return toAttributes(fresh ?? { ...created, count: desiredItems.length }, accountId);
}
// 3. Sync — diff observed name/description/items against desired;
// the update API is a PUT of the full mutable state, so skip the
// call entirely on a no-op. Items compare as an unordered set of
// values (the API may reorder).
const observedItems = (observed.items ?? []).map((i) => ({
value: i.value ?? "",
...(i.description != null ? { description: i.description } : {}),
}));
const dirty =
observed.name !== name ||
(news.description !== undefined && (observed.description ?? "") !== news.description) ||
!sameItems(observedItems, desiredItems);
if (dirty) {
yield* zeroTrust.updateGatewayList({
accountId,
listId: observed.id!,
name,
description: news.description ?? observed.description ?? undefined,
items: desiredItems,
});
// PUT echoes count but not items — re-read for the full shape.
const fresh = yield* getList(accountId, observed.id!);
if (fresh) return toAttributes(fresh, accountId);
}
return toAttributes(observed, accountId);
}),
delete: Effect.fn(function* ({ output }) {
// Lists still referenced by Gateway rules can fail deletion — rules
// that reference the list id as an Input get correct destroy
// ordering. A missing list (GatewayListNotFound, code 2218) means
// we're done.
yield* zeroTrust
.deleteGatewayList({
accountId: output.accountId,
listId: output.listId,
})
.pipe(Effect.catchTag("GatewayListNotFound", () => Effect.void));
}),
});
type ObservedList = zeroTrust.GetGatewayListResponse;
/**
* Read a list by id, mapping "gone" (`GatewayListNotFound`, Cloudflare
* error code 2218) to `undefined`.
*/
const getList = (accountId: string, listId: string) =>
zeroTrust.getGatewayList({ accountId, listId }).pipe(
Effect.map((l): ObservedList | undefined => l),
Effect.catchTag("GatewayListNotFound", () => Effect.undefined),
);
/**
* Find a list by exact name. Names are not unique on Cloudflare's side;
* pick the oldest match for determinism.
*/
const findByName = (accountId: string, name: string) =>
zeroTrust.listGatewayLists.items({ accountId }).pipe(
Stream.filter((l) => l.name === name),
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk)
.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""))
.at(0),
),
);
const resolveName = (id: string, name: string | undefined) =>
Effect.gen(function* () {
if (name) return name;
return yield* createPhysicalName({ id, lowercase: true });
});
const sameItems = (observed: ReadonlyArray<ListItem>, desired: ReadonlyArray<ListItem>): boolean =>
arrayEqualsUnordered(
observed.map((i) => `${i.value} ${i.description ?? ""}`),
desired.map((i) => `${i.value} ${i.description ?? ""}`),
);
const toAttributes = (
list: ObservedList & { count?: number | null },
accountId: string,
): ListAttributes => ({
listId: list.id ?? "",
accountId,
name: list.name ?? "",
type: (list.type ?? "DOMAIN") as ListType,
description: list.description ?? "",
items: (list.items ?? []).map((i) => ({
value: i.value ?? "",
...(i.description != null ? { description: i.description } : {}),
})),
count: list.count ?? (list.items ?? []).length,
createdAt: list.createdAt ?? undefined,
updatedAt: list.updatedAt ?? undefined,
});