import * as rum from "@distilled.cloud/cloudflare/rum";
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 Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
const TypeId = "Cloudflare.Rum.Rule" as const;
type TypeId = typeof TypeId;
export type RuleProps = {
/**
* The identifier of the Web Analytics ruleset the rule belongs to.
* Each zone-based (orange-clouded) `Site` owns one implicit ruleset —
* pass its `rulesetId` attribute. Changing this property triggers a
* replacement.
*/
rulesetId: string;
/**
* The hostname the rule applies to (e.g. `example.com`).
*/
host?: string;
/**
* The paths the rule applies to (e.g. `["/blog/*"]`).
*/
paths?: string[];
/**
* Whether the rule includes (`true`) or excludes (`false`) matching
* traffic from being measured.
* @default true
*/
inclusive?: boolean;
/**
* Whether the rule is paused.
* @default false
*/
isPaused?: boolean;
};
export type RuleAttributes = {
/**
* The Web Analytics rule identifier. Stable for the lifetime of the rule.
*/
id: string;
/**
* The identifier of the ruleset the rule belongs to.
*/
rulesetId: string;
/**
* The Cloudflare account the rule belongs to.
*/
accountId: string;
/**
* The hostname the rule applies to.
*/
host: string | undefined;
/**
* The paths the rule applies to.
*/
paths: string[] | undefined;
/**
* Whether the rule includes or excludes matching traffic from being
* measured.
*/
inclusive: boolean;
/**
* Whether the rule is paused.
*/
isPaused: boolean;
/**
* The rule's evaluation priority within its ruleset (assigned by
* Cloudflare).
*/
priority: number | undefined;
/**
* When the rule was created.
*/
created: string | undefined;
};
export type Rule = Resource<TypeId, RuleProps, RuleAttributes, never, Providers>;
/**
* A Cloudflare Web Analytics (RUM) rule.
*
* Rules include or exclude traffic from Web Analytics measurement by
* hostname and path patterns. They live under the implicit ruleset of a
* zone-based (orange-clouded) `Site` — pass the site's `rulesetId`
* attribute. Host, paths, `inclusive`, and `isPaused` are all mutable in
* place; changing `rulesetId` triggers a replacement.
*
* Web Analytics is available on free accounts.
* ### Excluding traffic
* **Example:** Exclude a path from measurement
* ```typescript
* const zone = yield* Cloudflare.Zone.Zone("Zone", { name: "example.com" });
*
* const site = yield* Cloudflare.Rum.Site("Analytics", {
* zoneTag: zone.zoneId,
* autoInstall: true,
* });
*
* yield* Cloudflare.Rum.Rule("ExcludeAdmin", {
* rulesetId: site.rulesetId.as<string>(),
* host: "example.com",
* paths: ["/admin/*"],
* inclusive: false,
* });
* ```
*
* ### Pausing a rule
* **Example:** Keep the rule but stop applying it
* ```typescript
* yield* Cloudflare.Rum.Rule("ExcludeAdmin", {
* rulesetId: site.rulesetId.as<string>(),
* host: "example.com",
* paths: ["/admin/*"],
* inclusive: false,
* isPaused: true,
* });
* ```
*
* @see https://developers.cloudflare.com/web-analytics/
*
* @resource
* @product RUM
* @category Observability & Analytics
*/
export const Rule = Resource<Rule>(TypeId);
/**
* Returns true if the given value is a Rule resource.
*/
export const isRule = (value: unknown): value is Rule =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
export const RuleProvider = () =>
Provider.succeed(Rule, {
stables: ["id", "rulesetId", "accountId", "created"],
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
// Rules live under a Site's implicit ruleset and there is no
// account-wide rule list. Enumerate every site (paginated), collect
// their ruleset ids, then fan out the per-ruleset rule list and
// flatten — the same listRules read path each rule's `read` uses.
const sites = yield* rum.listSiteInfos.pages({ accountId }).pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.result ?? [])),
);
const rulesetIds = Array.from(
new Set(
sites
.map((site) => site.ruleset?.id ?? undefined)
.filter((id): id is string => id !== undefined),
),
);
const rows = yield* Effect.forEach(
rulesetIds,
(rulesetId) =>
listRules(accountId, rulesetId).pipe(
Effect.map((rules) =>
(rules ?? []).map((rule) => toAttributes(rule, rulesetId, accountId)),
),
// A freshly minted scoped token can briefly 403 across the
// edge — skip rulesets we momentarily can't read.
Effect.catchTag("Forbidden", () => Effect.succeed([])),
),
{ concurrency: 10 },
);
return rows.flat();
}),
diff: Effect.fn(function* ({ news, output }) {
const { accountId } = yield* yield* CloudflareEnvironment;
if (!isResolved(news)) return undefined;
if ((output?.accountId ?? accountId) !== accountId) {
return { action: "replace" } as const;
}
// A rule cannot be moved between rulesets — moving it means a new
// rule under the new ruleset.
if (output !== undefined && news.rulesetId !== output.rulesetId) {
return { action: "replace" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ output, olds }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const acct = output?.accountId ?? accountId;
const rulesetId =
output?.rulesetId ?? (typeof olds?.rulesetId === "string" ? olds.rulesetId : undefined);
if (rulesetId === undefined) return undefined;
// There is no getRule — read through the ruleset's rule list. A
// deleted ruleset (the parent site is gone) means the rule is gone.
const rules = yield* listRules(acct, rulesetId);
if (rules === undefined) return undefined;
// Owned path: refresh by our persisted rule id.
if (output?.id) {
const observed = rules.find((rule) => rule.id === output.id);
return observed ? toAttributes(observed, rulesetId, acct) : undefined;
}
// Adoption path: rules carry no ownership markers, so a rule matching
// the same host+paths cannot be proven ours — brand it `Unowned` so
// the engine refuses to take over unless `adopt` is set.
if (olds !== undefined && isResolved(olds)) {
const match = rules
.filter(
(rule) =>
(rule.host ?? undefined) === olds.host &&
samePaths(rule.paths ?? undefined, olds.paths),
)
.sort((a, b) => (a.created ?? "").localeCompare(b.created ?? ""))
.at(0);
if (match) return Unowned(toAttributes(match, rulesetId, acct));
}
return undefined;
}),
reconcile: Effect.fn(function* ({ news, output }) {
const { accountId } = yield* yield* CloudflareEnvironment;
// Inputs have been resolved to concrete strings by Plan.
const rulesetId = news.rulesetId as string;
// 1. Observe — the rule id cached on `output` is a hint, not a
// guarantee: a missing rule (or ruleset) falls through to create.
const rules =
output?.id !== undefined && output.rulesetId === rulesetId
? yield* listRules(accountId, rulesetId)
: undefined;
let observed = rules?.find((rule) => rule.id === output?.id);
// 2. Ensure — create when missing. Rules have no uniqueness
// constraint, so there is no AlreadyExists race to tolerate. The
// API rejects bodies with absent `inclusive`/`is_paused`
// (`web_analytics.configuration.form.*.invalid`), so always send
// the full body with defaults. The create response omits
// `priority`, so re-read the rule from the list for the complete
// state.
if (!observed) {
const created = yield* rum
.createRule({
accountId,
rulesetId,
host: news.host,
paths: news.paths ?? [],
inclusive: news.inclusive ?? true,
isPaused: news.isPaused ?? false,
})
.pipe(
// The implicit ruleset of a freshly-created Site is eventually
// consistent: a createRule issued immediately after the site
// deploy can briefly 404 (`RulesetNotFound`, code
// `web_analytics.configuration.api.notFound`) before the ruleset is
// visible. Ride out the propagation window with a bounded retry.
Effect.retry({
while: (e) => e._tag === "RulesetNotFound",
schedule: Schedule.max([Schedule.exponential("500 millis"), Schedule.recurs(8)]),
}),
);
const fresh = yield* listRules(accountId, rulesetId);
observed = fresh?.find((rule) => rule.id === created.id) ?? toRule(created);
return toAttributes(observed, rulesetId, accountId);
}
// 3. Sync — diff observed cloud state against desired. The update
// API is a PUT; send the full desired body, but skip the call
// entirely on a no-op. Unspecified props keep their observed
// values.
const desired = {
host: news.host ?? observed.host ?? undefined,
paths: news.paths ?? [...(observed.paths ?? [])],
inclusive: news.inclusive ?? observed.inclusive ?? true,
isPaused: news.isPaused ?? observed.isPaused ?? false,
};
const dirty =
(observed.host ?? undefined) !== desired.host ||
!samePaths(observed.paths ?? undefined, desired.paths) ||
(observed.inclusive ?? true) !== desired.inclusive ||
(observed.isPaused ?? false) !== desired.isPaused;
if (!dirty) {
return toAttributes(observed, rulesetId, accountId);
}
const updated = yield* rum.updateRule({
accountId,
rulesetId,
ruleId: observed.id ?? "",
...desired,
});
return toAttributes(
{ ...toRule(updated), priority: updated.priority ?? observed.priority },
rulesetId,
accountId,
);
}),
delete: Effect.fn(function* ({ output }) {
yield* rum
.deleteRule({
accountId: output.accountId,
rulesetId: output.rulesetId,
ruleId: output.id,
})
.pipe(
// `RuleNotFound` (code 10003) — the rule is already gone;
// `RulesetNotFound` (404) — the parent site/ruleset is gone,
// taking the rule with it. Both make delete a success.
Effect.catchTag(["RuleNotFound", "RulesetNotFound"], () => Effect.void),
);
}),
});
type ObservedRule = NonNullable<NonNullable<rum.ListRulesResponse["rules"]>>[number];
/**
* List the rules of a ruleset, mapping "ruleset gone" (`RulesetNotFound`,
* HTTP 404 `web_analytics.configuration.api.notFound`) to `undefined`.
*/
const listRules = (accountId: string, rulesetId: string) =>
rum.listRules({ accountId, rulesetId }).pipe(
Effect.map((response): readonly ObservedRule[] | undefined => response.rules ?? []),
Effect.catchTag("RulesetNotFound", () => Effect.undefined),
);
const toRule = (rule: rum.CreateRuleResponse | rum.UpdateRuleResponse): ObservedRule => rule;
const samePaths = (
observed: readonly string[] | undefined,
desired: readonly string[] | undefined,
) =>
(observed ?? []).length === (desired ?? []).length &&
(observed ?? []).join(" ") === (desired ?? []).join(" ");
const toAttributes = (
rule: ObservedRule,
rulesetId: string,
accountId: string,
): RuleAttributes => ({
id: rule.id ?? "",
rulesetId,
accountId,
host: rule.host ?? undefined,
paths: rule.paths ? [...rule.paths] : undefined,
inclusive: rule.inclusive ?? true,
isPaused: rule.isPaused ?? false,
priority: rule.priority ?? undefined,
created: rule.created ?? undefined,
});