cursedbelt-server 1.1.0 → 2.1.0

package/dist/server/bench/assert.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The gate assertion. *"Document the WHY; automate the WHETHER."*
+ *
+ * 🔴 A report that is printed and not asserted on is the paragraph this module exists to
+ * replace. {@link assertCpuBudgets} THROWS, so a route that grows past its budget reddens
+ * a build instead of adding a line to a log nobody opens.
+ */
+import type { CpuBudgetReport } from './recorder';
+export type CpuViolationKind = 
+/** p99 above the route's declared (or default) budget. */
+'over-budget'
+/** Too few samples for the percentile to mean anything. */
+ | 'insufficient-samples'
+/** `requireDeclared` and the route fell through to the default. */
+ | 'undeclared'
+/** An exempt route crossed its own `noticeAboveMs`. Never fails a build. */
+ | 'exempt-notice'
+/** The clock could not measure at all. */
+ | 'unmeasurable';
+export interface CpuViolation {
+    kind: CpuViolationKind;
+    /** `'GET /api/notes/:id'`. */
+    key: string;
+    method: string;
+    route: string;
+    p99: number;
+    budgetMs: number | null;
+    samples: number;
+    /** False for `exempt-notice`, which is informational by design. */
+    fails: boolean;
+    message: string;
+}
+export interface AssertCpuBudgetsOpts {
+    /**
+     * Minimum samples before a p99 is trusted. Below it the route is a violation rather
+     * than a pass: a budget nothing could measure is not a budget that was met.
+     * Default: 20.
+     */
+    minSamples?: number;
+    /**
+     * Fail any route that relied on the default budget instead of declaring one. Off by
+     * default; an app turns it on to prove EVERY route has been thought about.
+     */
+    requireDeclared?: boolean;
+    /**
+     * Treat an unavailable clock as a pass. Off by default — a gate that goes green
+     * because it measured nothing is worse than no gate.
+     */
+    allowUnmeasurable?: boolean;
+}
+/** Compute violations without throwing. {@link assertCpuBudgets} is this plus a throw. */
+export declare function checkCpuBudgets(report: CpuBudgetReport, opts?: AssertCpuBudgetsOpts): CpuViolation[];
+/** A human-readable table of every route measured, worst p99 first. */
+export declare function formatCpuBudgetReport(report: CpuBudgetReport): string;
+/**
+ * Throw if any route exceeds its budget.
+ *
+ * 🔴 The message names the ROUTE and its NUMBER, because a failure that says only
+ * "a route is over budget" sends the reader back to the report to find out which.
+ */
+export declare function assertCpuBudgets(report: CpuBudgetReport, opts?: AssertCpuBudgetsOpts): CpuViolation[];

package/dist/server/bench/assert.js

@@ -0,0 +1,117 @@
+/**
+ * The gate assertion. *"Document the WHY; automate the WHETHER."*
+ *
+ * 🔴 A report that is printed and not asserted on is the paragraph this module exists to
+ * replace. {@link assertCpuBudgets} THROWS, so a route that grows past its budget reddens
+ * a build instead of adding a line to a log nobody opens.
+ */
+import { DEFAULT_ROUTE_CPU_BUDGET_MS } from './budget';
+const fmt = (n) => (Number.isFinite(n) ? n.toFixed(2) : 'n/a');
+/** Compute violations without throwing. {@link assertCpuBudgets} is this plus a throw. */
+export function checkCpuBudgets(report, opts = {}) {
+    const minSamples = opts.minSamples ?? 20;
+    const violations = [];
+    if (!report.available && !opts.allowUnmeasurable) {
+        return [
+            {
+                kind: 'unmeasurable',
+                key: '*',
+                method: '*',
+                route: '*',
+                p99: Number.NaN,
+                budgetMs: null,
+                samples: 0,
+                fails: true,
+                message: `CPU budget: nothing could be measured — clock source '${report.source}' is ` +
+                    'unavailable. Pass a runtime CPU reader, or set allowUnmeasurable to accept it.',
+            },
+        ];
+    }
+    for (const r of report.routes) {
+        const base = {
+            key: r.key,
+            method: r.method,
+            route: r.route,
+            p99: r.p99,
+            budgetMs: r.budgetMs,
+            samples: r.samples,
+        };
+        if (r.budgetMs === null) {
+            if (r.noticeAboveMs !== undefined && r.p99 > r.noticeAboveMs) {
+                violations.push({
+                    ...base,
+                    kind: 'exempt-notice',
+                    fails: false,
+                    message: `${r.key} is exempt (${r.exemptReason}) and its p99 is ${fmt(r.p99)} CPU-ms, ` +
+                        `above its own notice threshold of ${fmt(r.noticeAboveMs)}.`,
+                });
+            }
+            continue;
+        }
+        if (opts.requireDeclared && !r.declared) {
+            violations.push({
+                ...base,
+                kind: 'undeclared',
+                fails: true,
+                message: `${r.key} declares no CPU budget and fell through to the default of ` +
+                    `${fmt(r.budgetMs)} CPU-ms. requireDeclared is on: give it a number, or an ` +
+                    'exemption naming the reason.',
+            });
+            continue;
+        }
+        if (r.samples < minSamples) {
+            violations.push({
+                ...base,
+                kind: 'insufficient-samples',
+                fails: true,
+                message: `${r.key} has ${r.samples} sample(s); a p99 needs at least ${minSamples}. ` +
+                    'Drive the route more times, or lower minSamples deliberately.',
+            });
+            continue;
+        }
+        if (r.p99 > r.budgetMs) {
+            violations.push({
+                ...base,
+                kind: 'over-budget',
+                fails: true,
+                message: `${r.key} spent ${fmt(r.p99)} CPU-ms at p99, over its budget of ` +
+                    `${fmt(r.budgetMs)} CPU-ms (${(r.p99 / r.budgetMs).toFixed(1)}×). ` +
+                    `mean ${fmt(r.mean)} · p50 ${fmt(r.p50)} · p95 ${fmt(r.p95)} · max ${fmt(r.max)} ` +
+                    `over ${r.samples} samples.`,
+            });
+        }
+    }
+    return violations;
+}
+/** A human-readable table of every route measured, worst p99 first. */
+export function formatCpuBudgetReport(report) {
+    const head = `CPU per route — source '${report.source}'` +
+        (report.proxy
+            ? ' 🔴 PROXY: these are local process CPU deltas, NOT Worker CPU-ms.'
+            : ' (runtime-reported Worker CPU-ms).');
+    const rows = report.routes.map((r) => {
+        const budget = r.budgetMs === null ? `exempt: ${r.exemptReason}` : `${fmt(r.budgetMs)}ms budget`;
+        const flag = r.budgetMs !== null && r.p99 > r.budgetMs ? ' ← OVER' : '';
+        return (`  ${r.key.padEnd(44)} p50 ${fmt(r.p50).padStart(8)}  p95 ${fmt(r.p95).padStart(8)}  ` +
+            `p99 ${fmt(r.p99).padStart(8)}  max ${fmt(r.max).padStart(8)}  ` +
+            `n=${String(r.samples).padStart(5)}  ${budget}${flag}`);
+    });
+    return [head, ...rows].join('\n');
+}
+/**
+ * Throw if any route exceeds its budget.
+ *
+ * 🔴 The message names the ROUTE and its NUMBER, because a failure that says only
+ * "a route is over budget" sends the reader back to the report to find out which.
+ */
+export function assertCpuBudgets(report, opts = {}) {
+    const violations = checkCpuBudgets(report, opts);
+    const failing = violations.filter((v) => v.fails);
+    if (failing.length > 0) {
+        const lines = failing.map((v) => `  · [${v.kind}] ${v.message}`);
+        throw new Error(`${failing.length} route(s) over CPU budget ` +
+            `(default ${DEFAULT_ROUTE_CPU_BUDGET_MS} CPU-ms):\n${lines.join('\n')}\n\n` +
+            formatCpuBudgetReport(report));
+    }
+    return violations;
+}

package/dist/server/bench/budget.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The CPU budget, DERIVED rather than asserted.
+ *
+ * ## Why CPU and not requests
+ *
+ * The Workers Paid plan (`developers.cloudflare.com/workers/platform/pricing/`) meters
+ * requests and CPU time as two SEPARATE included allowances:
+ *
+ *   · $5/month base
+ *   · 10 million requests included, then +$0.30 per additional million
+ *   · 30 million CPU-milliseconds included, then +$0.02 per additional million
+ *   · 30 s CPU limit per invocation (raisable to 5 min)
+ *   · duration: "No charge or limit for duration" — wall clock is NEVER billed
+ *
+ * 🔴 There is no 125 ms per-request ceiling and no wall-clock fallback. That was the
+ * retired Bundled/Unbound model. Nothing here should be reasoned about in wall time:
+ * an `await` on a subrequest costs duration, and duration is free.
+ *
+ * At the owner's projection of 100k requests/day the two allowances are not equally
+ * tight — requests run to 30 % of the included 10 M while CPU is the binding one, which
+ * is the whole reason this module exists.
+ *
+ * ## 🔴 The default is a PROJECTION until an app is live
+ *
+ * {@link DEFAULT_ROUTE_CPU_BUDGET_MS} falls out of {@link OWNER_PROJECTED_REQUESTS_PER_DAY},
+ * which is the owner's estimate and not a measurement. {@link deriveCpuBudgetMs} is the
+ * function to re-run against real traffic — the re-derivation is a call, not a paragraph
+ * somebody has to remember to do.
+ */
+/** CPU-milliseconds included in the Workers Paid plan each month. */
+export declare const WORKERS_PAID_INCLUDED_CPU_MS = 30000000;
+/** Requests included in the Workers Paid plan each month. */
+export declare const WORKERS_PAID_INCLUDED_REQUESTS = 10000000;
+/** USD per additional million CPU-ms, once the included allowance is spent. */
+export declare const WORKERS_PAID_USD_PER_MILLION_CPU_MS = 0.02;
+/** USD per additional million requests, once the included allowance is spent. */
+export declare const WORKERS_PAID_USD_PER_MILLION_REQUESTS = 0.3;
+/**
+ * The owner's own projection, 2026-09-15. 🔴 A PROJECTION, not a measurement — the
+ * whole point of {@link deriveCpuBudgetMs} is to replace it once an app is serving.
+ */
+export declare const OWNER_PROJECTED_REQUESTS_PER_DAY = 100000;
+/** 365.25 / 12 — the average calendar month, since billing is monthly. */
+export declare const DAYS_PER_MONTH = 30.4375;
+/**
+ * Derive the average CPU-ms a single request may spend before the fleet exceeds its
+ * included CPU allowance.
+ *
+ * 🔴 This is an AVERAGE-per-request allowance, not a per-invocation limit. A route may
+ * exceed it and cost nothing, provided cheap routes carry the mean. What it is for is
+ * ranking: a route whose p99 sits above the average budget is a route that cannot be
+ * allowed to become the common case.
+ */
+export declare function deriveCpuBudgetMs(opts?: {
+    /** Included CPU-ms per month. Default: the Workers Paid allowance. */
+    includedCpuMs?: number;
+    /** Measured (or projected) requests per month. */
+    requestsPerMonth?: number;
+    /** Measured (or projected) requests per day — converted with {@link DAYS_PER_MONTH}. */
+    requestsPerDay?: number;
+}): number;
+/**
+ * What a month costs in overage once the included allowances are spent. Used by the
+ * report so a violation carries a PRICE and not only a number — the honest framing is
+ * that going 3× over the CPU budget at this traffic is about $1.20/month, which is a
+ * reason to care about the outlier route and not a reason to panic.
+ */
+export declare function monthlyOverageUsd(opts: {
+    requestsPerMonth: number;
+    meanCpuMsPerRequest: number;
+}): {
+    cpuUsd: number;
+    requestsUsd: number;
+    totalUsd: number;
+};
+/**
+ * 9.9 CPU-ms — `30,000,000 ÷ (100,000 × 30.4375)` = 9.856, to one decimal.
+ *
+ * Generous for a JSON route, tight for anything that renders, parses or derives a key.
+ * 🔴 Re-derive with {@link deriveCpuBudgetMs} once an app has real traffic.
+ */
+export declare const DEFAULT_ROUTE_CPU_BUDGET_MS: number;
+/** A route that is measured against a number. */
+export interface CpuBudgetLimit {
+    cpuMs: number;
+}
+/**
+ * A route that is deliberately NOT measured against the default.
+ *
+ * 🔴 `reason` is required by the type AND checked at runtime. An exemption whose
+ * justification is blank is the paragraph this module exists to replace — a silent
+ * opt-out is indistinguishable from a route nobody looked at.
+ */
+export interface CpuBudgetExemption {
+    exempt: true;
+    reason: string;
+    /**
+     * The exemption still records, and a p99 above this is reported as a NOTICE rather
+     * than a violation. Optional — an exemption with no ceiling is never surprising.
+     */
+    noticeAboveMs?: number;
+}
+export type RouteBudget = CpuBudgetLimit | CpuBudgetExemption | number;
+export interface CpuBudgetConfig {
+    /** Applied to any route without its own entry. Default: {@link DEFAULT_ROUTE_CPU_BUDGET_MS}. */
+    defaultCpuMs?: number;
+    /**
+     * Per-route budgets, keyed either `'GET /api/notes/:id'` (method-specific, wins) or
+     * `'/api/notes/:id'` (any method). Keys are matched against the same normalized route
+     * label the metrics tier uses, so `:params` are already collapsed.
+     */
+    routes?: Record<string, RouteBudget>;
+}
+export declare function isExemption(b: RouteBudget): b is CpuBudgetExemption;
+/** The resolved budget for one route label. */
+export interface ResolvedBudget {
+    /** The ceiling in CPU-ms, or `null` when the route is exempt. */
+    cpuMs: number | null;
+    exemptReason?: string;
+    noticeAboveMs?: number;
+    /** True when no explicit entry matched and the default was applied. */
+    declared: boolean;
+}
+/**
+ * 🔴 Validate the whole config up front rather than at the moment a route is hit. A
+ * blank exemption reason on a route nobody exercised in the bench would otherwise ship.
+ */
+export declare function validateCpuBudgetConfig(config: CpuBudgetConfig): void;
+/** Resolve `method` + `route` against the config. Method-specific keys win. */
+export declare function resolveBudget(config: CpuBudgetConfig, method: string, route: string): ResolvedBudget;

package/dist/server/bench/budget.js

@@ -0,0 +1,131 @@
+/**
+ * The CPU budget, DERIVED rather than asserted.
+ *
+ * ## Why CPU and not requests
+ *
+ * The Workers Paid plan (`developers.cloudflare.com/workers/platform/pricing/`) meters
+ * requests and CPU time as two SEPARATE included allowances:
+ *
+ *   · $5/month base
+ *   · 10 million requests included, then +$0.30 per additional million
+ *   · 30 million CPU-milliseconds included, then +$0.02 per additional million
+ *   · 30 s CPU limit per invocation (raisable to 5 min)
+ *   · duration: "No charge or limit for duration" — wall clock is NEVER billed
+ *
+ * 🔴 There is no 125 ms per-request ceiling and no wall-clock fallback. That was the
+ * retired Bundled/Unbound model. Nothing here should be reasoned about in wall time:
+ * an `await` on a subrequest costs duration, and duration is free.
+ *
+ * At the owner's projection of 100k requests/day the two allowances are not equally
+ * tight — requests run to 30 % of the included 10 M while CPU is the binding one, which
+ * is the whole reason this module exists.
+ *
+ * ## 🔴 The default is a PROJECTION until an app is live
+ *
+ * {@link DEFAULT_ROUTE_CPU_BUDGET_MS} falls out of {@link OWNER_PROJECTED_REQUESTS_PER_DAY},
+ * which is the owner's estimate and not a measurement. {@link deriveCpuBudgetMs} is the
+ * function to re-run against real traffic — the re-derivation is a call, not a paragraph
+ * somebody has to remember to do.
+ */
+/** CPU-milliseconds included in the Workers Paid plan each month. */
+export const WORKERS_PAID_INCLUDED_CPU_MS = 30_000_000;
+/** Requests included in the Workers Paid plan each month. */
+export const WORKERS_PAID_INCLUDED_REQUESTS = 10_000_000;
+/** USD per additional million CPU-ms, once the included allowance is spent. */
+export const WORKERS_PAID_USD_PER_MILLION_CPU_MS = 0.02;
+/** USD per additional million requests, once the included allowance is spent. */
+export const WORKERS_PAID_USD_PER_MILLION_REQUESTS = 0.3;
+/**
+ * The owner's own projection, 2026-09-15. 🔴 A PROJECTION, not a measurement — the
+ * whole point of {@link deriveCpuBudgetMs} is to replace it once an app is serving.
+ */
+export const OWNER_PROJECTED_REQUESTS_PER_DAY = 100_000;
+/** 365.25 / 12 — the average calendar month, since billing is monthly. */
+export const DAYS_PER_MONTH = 30.4375;
+/**
+ * Derive the average CPU-ms a single request may spend before the fleet exceeds its
+ * included CPU allowance.
+ *
+ * 🔴 This is an AVERAGE-per-request allowance, not a per-invocation limit. A route may
+ * exceed it and cost nothing, provided cheap routes carry the mean. What it is for is
+ * ranking: a route whose p99 sits above the average budget is a route that cannot be
+ * allowed to become the common case.
+ */
+export function deriveCpuBudgetMs(opts = {}) {
+    const includedCpuMs = opts.includedCpuMs ?? WORKERS_PAID_INCLUDED_CPU_MS;
+    const requestsPerMonth = opts.requestsPerMonth ??
+        (opts.requestsPerDay ?? OWNER_PROJECTED_REQUESTS_PER_DAY) * DAYS_PER_MONTH;
+    if (!(requestsPerMonth > 0)) {
+        throw new Error('deriveCpuBudgetMs: requestsPerMonth must be > 0');
+    }
+    return includedCpuMs / requestsPerMonth;
+}
+/**
+ * What a month costs in overage once the included allowances are spent. Used by the
+ * report so a violation carries a PRICE and not only a number — the honest framing is
+ * that going 3× over the CPU budget at this traffic is about $1.20/month, which is a
+ * reason to care about the outlier route and not a reason to panic.
+ */
+export function monthlyOverageUsd(opts) {
+    const cpuMs = opts.requestsPerMonth * opts.meanCpuMsPerRequest;
+    const cpuOver = Math.max(0, cpuMs - WORKERS_PAID_INCLUDED_CPU_MS);
+    const reqOver = Math.max(0, opts.requestsPerMonth - WORKERS_PAID_INCLUDED_REQUESTS);
+    const cpuUsd = (cpuOver / 1_000_000) * WORKERS_PAID_USD_PER_MILLION_CPU_MS;
+    const requestsUsd = (reqOver / 1_000_000) * WORKERS_PAID_USD_PER_MILLION_REQUESTS;
+    return { cpuUsd, requestsUsd, totalUsd: cpuUsd + requestsUsd };
+}
+/**
+ * 9.9 CPU-ms — `30,000,000 ÷ (100,000 × 30.4375)` = 9.856, to one decimal.
+ *
+ * Generous for a JSON route, tight for anything that renders, parses or derives a key.
+ * 🔴 Re-derive with {@link deriveCpuBudgetMs} once an app has real traffic.
+ */
+export const DEFAULT_ROUTE_CPU_BUDGET_MS = Math.round(deriveCpuBudgetMs() * 10) / 10;
+export function isExemption(b) {
+    return typeof b === 'object' && 'exempt' in b && b.exempt === true;
+}
+/**
+ * 🔴 Validate the whole config up front rather than at the moment a route is hit. A
+ * blank exemption reason on a route nobody exercised in the bench would otherwise ship.
+ */
+export function validateCpuBudgetConfig(config) {
+    if (config.defaultCpuMs !== undefined && !(config.defaultCpuMs > 0)) {
+        throw new Error(`cpuBudget: defaultCpuMs must be > 0, got ${config.defaultCpuMs}`);
+    }
+    for (const [key, budget] of Object.entries(config.routes ?? {})) {
+        if (isExemption(budget)) {
+            if (typeof budget.reason !== 'string' || budget.reason.trim() === '') {
+                throw new Error(`cpuBudget: route '${key}' is exempt with no reason. An opt-out must name why — ` +
+                    'that is the difference between a decision and an oversight.');
+            }
+            if (budget.noticeAboveMs !== undefined && !(budget.noticeAboveMs > 0)) {
+                throw new Error(`cpuBudget: route '${key}' has noticeAboveMs ≤ 0`);
+            }
+            continue;
+        }
+        const cpuMs = typeof budget === 'number' ? budget : budget.cpuMs;
+        if (!(cpuMs > 0)) {
+            throw new Error(`cpuBudget: route '${key}' has a budget of ${cpuMs}; it must be > 0`);
+        }
+    }
+}
+/** Resolve `method` + `route` against the config. Method-specific keys win. */
+export function resolveBudget(config, method, route) {
+    const routes = config.routes ?? {};
+    const explicit = routes[`${method} ${route}`] ?? routes[route];
+    if (explicit === undefined) {
+        return { cpuMs: config.defaultCpuMs ?? DEFAULT_ROUTE_CPU_BUDGET_MS, declared: false };
+    }
+    if (isExemption(explicit)) {
+        return {
+            cpuMs: null,
+            exemptReason: explicit.reason,
+            noticeAboveMs: explicit.noticeAboveMs,
+            declared: true,
+        };
+    }
+    return {
+        cpuMs: typeof explicit === 'number' ? explicit : explicit.cpuMs,
+        declared: true,
+    };
+}

package/dist/server/bench/cpuBudget.d.ts

@@ -0,0 +1,45 @@
+import type { MiddlewareHandler } from 'hono';
+import type { CursedbeltEnv } from '../context';
+import type { CpuBudgetConfig } from './budget';
+import { type CpuClock } from './cpuClock';
+import { type CpuRecorder } from './recorder';
+/**
+ * Per-route CPU attribution, mounted like any other cursedbelt middleware.
+ *
+ * ```ts
+ * const cpu = createCpuRecorder({ clock: processCpuClock(), config: BUDGETS })
+ * app.use('*', cpuBudget({ recorder: cpu }))
+ * ```
+ *
+ * 🔴 **It records CPU, never wall clock.** `requestLogger` beside it records duration,
+ * and duration is the quantity Cloudflare explicitly does not bill. The two numbers
+ * diverge by exactly the amount a handler spends awaiting a subrequest, which on this
+ * fleet is most of it — so a route can be slow and free, or fast and expensive, and only
+ * this middleware can tell you which.
+ *
+ * Like `requestLogger`, it records even when a downstream handler THROWS: the CPU was
+ * spent either way, and an endpoint that is expensive only on its error path is exactly
+ * the sort of thing a budget is supposed to catch. The error is re-thrown unchanged.
+ */
+export interface CpuBudgetOpts {
+    /** The recorder to write through. Provide one so the gate can read its report. */
+    recorder?: CpuRecorder;
+    /** Built into a recorder when `recorder` is omitted. */
+    config?: CpuBudgetConfig;
+    /** Defaults to {@link processCpuClock} — the local PROXY. */
+    clock?: CpuClock;
+    /**
+     * Called after each request with the sample. For shipping the number somewhere (a
+     * telemetry sink, a log line) without coupling this module to a destination.
+     */
+    onSample?: (sample: {
+        method: string;
+        route: string;
+        cpuMs: number;
+        proxy: boolean;
+        status: number;
+    }) => void;
+}
+export declare function cpuBudget(opts?: CpuBudgetOpts): MiddlewareHandler<CursedbeltEnv> & {
+    recorder: CpuRecorder;
+};

package/dist/server/bench/cpuBudget.js

@@ -0,0 +1,34 @@
+import { normalizeRoute } from '../metrics/normalizeRoute';
+import { processCpuClock } from './cpuClock';
+import { createCpuRecorder } from './recorder';
+export function cpuBudget(opts = {}) {
+    const recorder = opts.recorder ??
+        createCpuRecorder({ clock: opts.clock ?? processCpuClock(), config: opts.config });
+    const handler = async (c, next) => {
+        const end = recorder.clock.start();
+        let thrown;
+        let didThrow = false;
+        try {
+            await next();
+        }
+        catch (err) {
+            thrown = err;
+            didThrow = true;
+        }
+        const cpuMs = end();
+        // `normalizeRoute` must run AFTER `next()` — before it, Hono has not matched a route
+        // pattern yet and every request would aggregate under its raw path.
+        const { method, route } = normalizeRoute(c);
+        recorder.record(method, route, cpuMs);
+        opts.onSample?.({
+            method,
+            route,
+            cpuMs,
+            proxy: recorder.clock.proxy,
+            status: didThrow ? 500 : c.res.status,
+        });
+        if (didThrow)
+            throw thrown;
+    };
+    return Object.assign(handler, { recorder });
+}

package/dist/server/bench/cpuClock.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Where a CPU-millisecond comes from, and how honest it is.
+ *
+ * 🔴 **Every reading carries `proxy`, and it is not decoration.** The task that asked for
+ * this module asked for the label in the same breath as the measurement: *"a local number
+ * that is called a CPU-ms measurement will be quoted as one."* A number printed without
+ * its provenance becomes a fact about Cloudflare's billing the first time somebody pastes
+ * it into a summary.
+ *
+ * Two sources, and they are not interchangeable:
+ *
+ *   · {@link processCpuClock} — `process.cpuUsage()` deltas on Bun/Node. `proxy: true`.
+ *   · {@link workerCpuClock} — a reader the Worker runtime supplies. `proxy: false`.
+ *
+ * There is deliberately no built-in Cloudflare reader here. The isolate does not hand a
+ * handler its own CPU time; `cpuTime` arrives on the trace event a **tail worker** sees.
+ * Inventing an API that does not exist would produce a clock that reads zero for ever and
+ * a gate that can never go red — so the platform passes its reader in, or there is none.
+ */
+/** A started measurement. Call it to end the measurement and get CPU-ms. */
+export type CpuSpan = () => number;
+export interface CpuClock {
+    /** Human-readable provenance, e.g. `'process.cpuUsage'`. Printed in every report. */
+    readonly source: string;
+    /**
+     * 🔴 True when this number is a PROXY for Worker CPU-ms rather than a reading of it.
+     * The report prints it and {@link CpuBudgetReport} carries it downstream.
+     */
+    readonly proxy: boolean;
+    /** True when the clock can actually measure. A false one records nothing. */
+    readonly available: boolean;
+    start(): CpuSpan;
+}
+/**
+ * `process.cpuUsage()` deltas — user + system, converted from µs to ms.
+ *
+ * 🔴 **The delta is PROCESS-WIDE, not per-request.** If two requests are in flight the
+ * reading for each includes the other's CPU, and any background work (a metrics flush, a
+ * GC pause attributed to the interval) lands on whichever handler happened to be open.
+ * That is why {@link runCpuBench} drives its cases SERIALLY — a serial driver is what
+ * makes this proxy sound enough to gate on. Mounted in production it is advisory: useful
+ * for ranking routes, not for a billing claim.
+ */
+export declare function processCpuClock(): CpuClock;
+/**
+ * A clock over a CPU-ms reader the runtime supplies. `proxy: false` — this is the real
+ * quantity Cloudflare bills, so a report built on it may be quoted as one.
+ *
+ * @param readCpuMs Returns monotonically non-decreasing CPU-ms for the current invocation.
+ */
+export declare function workerCpuClock(readCpuMs: () => number, source?: string): CpuClock;
+/**
+ * A clock that cannot measure. Recording through it is a no-op, and the report says so
+ * rather than reporting a confident zero.
+ */
+export declare function unavailableCpuClock(source?: string): CpuClock;
+/**
+ * A deterministic clock for tests: each `start()` consumes the next value in `values`,
+ * repeating the last one once exhausted. Lets the assertion be proven in both directions
+ * without burning real CPU, which is the difference between a test that is fast and
+ * reliable and one that is neither.
+ */
+export declare function fixedCpuClock(values: number[], source?: string): CpuClock;
+/** `workerCpuClock` when the platform supplied a reader, else the local proxy. */
+export declare function resolveCpuClock(readCpuMs?: (() => number) | null): CpuClock;