/**
* Site analytics in the renderer (RFC-0006 §5, rollout step 5), shared by the Cloudflare Site
* Worker entry and the Node middleware. Worker-safe: no Node module, no bundler.
*
* - **Settings** apply per request: the deployment switch and defaults (`CLOUDHAL_ANALYTICS`,
* `CLOUDHAL_ANALYTICS_DEFAULTS` on Cloudflare; integration options on Node), overridden by the
* site's `analytics_settings` row, memoised for 60 s per isolate. A missing table, a read error,
* a missing store or the deployment switch off all count as **off** (fail closed).
* - **The tag** (``;
}
/** Inserts the tag before `` of an HTML string (Node; the Worker uses `HTMLRewriter`). */
export function insertTag(html: string, tag: string): string {
const at = html.search(/<\/head\s*>/i);
return at < 0 ? html : `${html.slice(0, at)}${tag}${html.slice(at)}`;
}
/**
* The node a normalised route shows in a published source: a page, an entry, or a term archive
* (any of its pages counts toward the term). Feeds, redirects, 404s and 410s are not page views.
*/
export async function publishedNode(
source: GraphSource,
path: string,
): Promise {
const route = await resolveRoute(source, path);
switch (route.kind) {
case "page":
return { nodeId: route.page.id, nodeKind: "page", locale: route.page.locale };
case "entry":
return { nodeId: route.entry.id, nodeKind: "entry", locale: route.entry.locale };
case "archive":
return {
nodeId: route.archive.term.id,
nodeKind: "archive",
locale: route.archive.locale,
};
default:
return undefined;
}
}
/**
* The deployment switch and defaults as the site Worker reads them: `CLOUDHAL_ANALYTICS` must be
* `"on"` (anything else, or absent, is off); `CLOUDHAL_ANALYTICS_DEFAULTS` is compact JSON
* (`cloudhal.json`'s `analytics` block) in which `enabled` defaults to `true`.
*/
export function deploymentDefaults(
flag: string | undefined,
defaults: string | undefined,
): AnalyticsDefaults | undefined {
if (flag?.trim().toLowerCase() !== "on") return undefined;
let parsed: unknown;
try {
parsed = defaults ? JSON.parse(defaults) : {};
} catch {
parsed = {};
}
const o = parsed && typeof parsed === "object" ? (parsed as Record) : {};
return parseAnalyticsDefaults({ enabled: true, ...o });
}
/** Comma- or space-separated hostnames (e.g. `CLOUDHAL_SITE_HOSTS`), lower case. */
export function parseHosts(value: string | undefined): string[] {
return (value ?? "")
.split(/[\s,]+/)
.map((h) => h.trim().toLowerCase())
.filter(Boolean);
}
export interface SiteAnalyticsOptions {
readonly siteId: string;
/** Deployment defaults; `undefined` = analytics are off for the deployment. */
readonly defaults: AnalyticsDefaults | undefined;
/** Where events go; `undefined` = no store (nothing is collected, no tag). */
readonly writer: AnalyticsWriter | undefined;
/** Settings, salt (D1 on Cloudflare, SQLite on Node). */
readonly sql: () => SqlDriver;
/** The site row as stored now (for its published pointer and domains). */
readonly site: () => Promise;
/** The source of a snapshot (cached by the caller; snapshots are immutable). */
readonly snapshot: (id: string) => Promise;
/** Hashed URL of the page-view script; without it no tag is injected. */
readonly script?: string | undefined;
/** Hosts the site answers on besides `Site.domains` (e.g. the workers.dev host). */
readonly hosts?: readonly string[];
/** Also accept the request's own host (`*.workers.dev` on Cloudflare; every host in dev). */
readonly acceptRequestHost?: (host: string) => boolean;
/**
* The optional Workers Rate Limiting binding (`analytics.rateLimit`, RFC-0006 §5.5), checked
* after the per-isolate limit and keyed by an HMAC under `secret` (a deployment secret every
* isolate has). Absent: the per-isolate limits alone apply.
*/
readonly rateLimit?: { readonly binding: RateLimitBinding; readonly secret: string } | undefined;
readonly now?: () => number;
readonly onError?: (message: string, error?: unknown) => void;
}
interface Memo {
readonly at: number;
readonly value: Promise;
}
/** What a request's analytics need from the published site. */
interface Published {
readonly site: Site;
readonly source: GraphSource;
}
/**
* Per-isolate analytics state of one site: memoised settings and pointer, the beacon rate limiter
* and the render-event sampler. Create one per isolate (module scope) and `reset()` it on a purge.
*/
export class SiteAnalytics {
readonly #o: SiteAnalyticsOptions;
readonly #now: () => number;
readonly #limiter: BeaconRateLimiter;
readonly #shared: SharedBeaconRateLimiter | undefined;
readonly #sampler: RenderEventSampler;
readonly #salt: (day: string) => Promise;
#saltProvider: SaltProvider | undefined;
#settings: Memo | undefined;
#site: Memo | undefined;
constructor(options: SiteAnalyticsOptions) {
this.#o = options;
this.#now = options.now ?? Date.now;
this.#limiter = new BeaconRateLimiter({ now: this.#now });
this.#shared = options.rateLimit
? new SharedBeaconRateLimiter(options.rateLimit.binding, {
secret: options.rateLimit.secret,
...(options.onError ? { onError: options.onError } : {}),
})
: undefined;
this.#sampler = new RenderEventSampler({ now: this.#now });
this.#salt = (day) => {
this.#saltProvider ??= createSaltProvider(this.#o.sql(), { now: this.#now });
return this.#saltProvider(day);
};
}
/**
* Forget memoised settings, the pointer and the day's salt (a purge follows every settings
* change, §9.2, including "unique visitors" on or off, which deletes the salt in D1).
*/
reset(): void {
this.#settings = undefined;
this.#site = undefined;
this.#saltProvider?.reset();
}
/** True when the deployment collects at all (switch on and a store bound). */
get available(): boolean {
return this.#o.defaults !== undefined && this.#o.writer !== undefined;
}
#memo(current: Memo | undefined, load: () => Promise): Memo {
const now = this.#now();
if (current && now - current.at < ANALYTICS_MEMO_MS) return current;
const value = load();
value.catch(() => {});
return { at: now, value };
}
/** The site's effective settings, or `undefined` when analytics are off or unreadable. */
async settings(): Promise {
const defaults = this.#o.defaults;
if (!defaults || !this.#o.writer) return undefined;
const before = this.#settings;
this.#settings = this.#memo(this.#settings, async () =>
effectiveSettings(
this.#o.siteId,
await getAnalyticsSettings(this.#o.sql(), this.#o.siteId),
defaults,
),
);
// The salt is never older than the settings it is used with: whenever they are read again
// (every 60 s, or after a reset), the salt's row is read again too, so a salt deleted by
// switching unique visitors off is not used once this isolate sees the change.
if (this.#settings !== before) this.#saltProvider?.reset();
try {
const s = await this.#settings.value;
return s?.enabled ? s : undefined;
} catch {
return undefined; // a missing table (before migration 0014) or a read error: off
}
}
/** The tag for a published HTML page, or `undefined` (off, or no built script). */
async tag(): Promise {
if (!this.#o.script) return undefined;
const s = await this.settings();
return s ? analyticsTag(this.#o.script, s.vitalsOneIn) : undefined;
}
async #published(): Promise {
this.#site = this.#memo(this.#site, () => this.#o.site());
let site: Site | undefined;
try {
site = await this.#site.value;
} catch (error) {
this.#o.onError?.("analytics: reading the site failed", error);
return undefined;
}
if (!site?.publishedSnapshotId) return undefined;
return { site, source: await this.#o.snapshot(site.publishedSnapshotId) };
}
#hosts(site: Site, requestHost: string): string[] {
const hosts = [...site.domains.map((d) => d.hostname), ...(this.#o.hosts ?? [])];
const bare = requestHost.toLowerCase().replace(/:\d+$/, "");
if (this.#o.acceptRequestHost?.(bare)) hosts.push(requestHost.toLowerCase());
return hosts;
}
/**
* `POST /__cloudhal/e`: `204` for every outcome (`405` for another method), `no-store`.
* `clientIp` is the client's address as the caller knows it (the Site Worker: Cloudflare's
* `CF-Connecting-IP`; Node: the socket address); request headers are never trusted for it.
* `country` stands in for `request.cf.country` off Cloudflare.
*/
async beacon(
request: Request,
extra: { clientIp?: string; country?: string } = {},
): Promise {
const writer = this.#o.writer;
const off = { settings: () => undefined, hosts: [], resolvePath: () => undefined };
const noop: AnalyticsWriter = { write: () => {} };
if (request.method !== "POST" || !writer)
return handleBeacon(request, { siteId: this.#o.siteId, writer: noop, ...off });
const settings = await this.settings();
const published = settings ? await this.#published() : undefined;
if (!settings || !published)
return handleBeacon(request, { siteId: this.#o.siteId, writer: noop, ...off });
const { source, site } = published;
return handleBeacon(request, {
siteId: this.#o.siteId,
settings: () => settings,
hosts: this.#hosts(site, new URL(request.url).host),
resolvePath: (path) => publishedNode(source, path),
writer,
salt: this.#salt,
rateLimit: async (ip, kind) =>
(await this.#limiter.allow(ip, kind)) && (await (this.#shared?.allow(ip) ?? true)),
now: () => new Date(this.#now()),
...(extra.clientIp ? { clientIp: extra.clientIp } : {}),
...(extra.country ? { country: extra.country } : {}),
...(this.#o.onError ? { onError: this.#o.onError } : {}),
});
}
/**
* Records the render event for a response the site rendered (§5.4), if it is one. Run it off
* the response path (`ctx.waitUntil`); it never throws.
*/
async render(
request: Request,
response: Response,
renderMs: number,
extra: { country?: string } = {},
): Promise {
try {
const writer = this.#o.writer;
if (!writer || !isRenderEvent(request, response)) return;
if (!(await this.settings())) return;
const published = await this.#published();
if (!published) return;
const decision = this.#sampler.next();
if (!decision.record) return;
const url = new URL(request.url);
const status = response.status;
const location = response.headers.get("location");
// the node shown (200) or redirected to (3xx, same-site targets only)
let nodePath: string | undefined;
if (status === 200) nodePath = normaliseBeaconPath(url.pathname);
else if (status >= 300 && status < 400 && location) {
const target = new URL(location, url);
if (target.host === url.host) nodePath = normaliseBeaconPath(target.pathname);
}
const node = nodePath ? await publishedNode(published.source, nodePath) : undefined;
const cf = (request as Request & { cf?: { country?: unknown } }).cf;
const country = typeof cf?.country === "string" ? cf.country : extra.country;
const h = request.headers;
const event = buildRenderEvent({
siteId: this.#o.siteId,
now: new Date(this.#now()),
url,
status,
hosts: this.#hosts(published.site, url.host),
userAgent: h.get("user-agent"),
hints: { mobile: h.get("sec-ch-ua-mobile"), platform: h.get("sec-ch-ua-platform") },
referer: h.get("referer"),
...(node ? { node: { nodeId: node.nodeId, nodeKind: node.nodeKind } } : {}),
location,
renderMs,
sampleOneIn: decision.sampleOneIn,
...(country ? { country } : {}),
});
if (event) writer.write(event);
} catch (error) {
this.#o.onError?.("analytics: render event failed", error);
}
}
}
const RENDER_STATUSES = new Set([301, 302, 303, 307, 308, 404, 410, 451]);
/**
* Whether a response is one the site Worker records as a `render` event (§5.4): a `GET` for a
* site path (not `/__cloudhal/*`, `/_cloudhal/*`, not a preview), answered with a published HTML
* `200`, a redirect, `404`, `410`, `451` or a `5xx`. Media `200`/`206`/`304` and feeds are not
* HTML, so they never count.
*/
export function isRenderEvent(request: Request, response: Response): boolean {
if (request.method !== "GET") return false;
const url = new URL(request.url);
if (url.pathname.startsWith("/__cloudhal/") || url.pathname.startsWith(ANALYTICS_SCRIPT_DIR))
return false;
if (url.searchParams.has(PREVIEW_PARAM)) return false;
const mode = response.headers.get("x-cloudhal-mode");
if (mode === "preview" || mode === "unpublished") return false;
const status = response.status;
if (status === 200)
return (
mode === "published" && (response.headers.get("content-type") ?? "").includes("text/html")
);
return RENDER_STATUSES.has(status) || (status >= 500 && status <= 599);
}