cursedbelt-server 2.0.0 → 2.1.0

package/src/server/bench/assert.ts

@@ -0,0 +1,192 @@
+/**
+ * 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';
+import type { CpuBudgetReport, RouteCpuStats } 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;
+}
+
+const fmt = (n: number): string => (Number.isFinite(n) ? n.toFixed(2) : 'n/a');
+
+/** Compute violations without throwing. {@link assertCpuBudgets} is this plus a throw. */
+export function checkCpuBudgets(
+  report: CpuBudgetReport,
+  opts: AssertCpuBudgetsOpts = {},
+): CpuViolation[] {
+  const minSamples = opts.minSamples ?? 20;
+  const violations: CpuViolation[] = [];
+
+  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: Omit<CpuViolation, 'kind' | 'message' | 'fails'> = {
+      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: CpuBudgetReport): string {
+  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: RouteCpuStats) => {
+    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: CpuBudgetReport,
+  opts: AssertCpuBudgetsOpts = {},
+): CpuViolation[] {
+  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/src/server/bench/budget.spec.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  DAYS_PER_MONTH,
+  DEFAULT_ROUTE_CPU_BUDGET_MS,
+  deriveCpuBudgetMs,
+  monthlyOverageUsd,
+  OWNER_PROJECTED_REQUESTS_PER_DAY,
+  resolveBudget,
+  validateCpuBudgetConfig,
+  WORKERS_PAID_INCLUDED_CPU_MS,
+} from './budget';
+import { percentile } from './recorder';
+
+describe('the derivation', () => {
+  it('derives 9.9 CPU-ms from the Workers Paid allowance and the projected traffic', () => {
+    // 30,000,000 CPU-ms ÷ (100,000/day × 30.4375 days) = 9.856…
+    const raw = deriveCpuBudgetMs();
+    expect(raw).toBeCloseTo(9.856, 2);
+    expect(DEFAULT_ROUTE_CPU_BUDGET_MS).toBe(9.9);
+  });
+
+  it('is a FUNCTION of traffic, so the number moves when the measurement replaces the guess', () => {
+    // Twice the traffic halves what each request may spend. This is the call the outcome
+    // asks for once an app is live — not a constant somebody has to remember to edit.
+    expect(deriveCpuBudgetMs({ requestsPerDay: 200_000 })).toBeCloseTo(4.928, 2);
+    expect(deriveCpuBudgetMs({ requestsPerDay: 10_000 })).toBeCloseTo(98.56, 1);
+    expect(deriveCpuBudgetMs({ requestsPerMonth: 30_000_000 })).toBe(1);
+  });
+
+  it('holds the owner projection it was derived from, so a reader can check the arithmetic', () => {
+    expect(OWNER_PROJECTED_REQUESTS_PER_DAY * DAYS_PER_MONTH).toBeCloseTo(3_043_750, 0);
+    expect(WORKERS_PAID_INCLUDED_CPU_MS).toBe(30_000_000);
+  });
+
+  it('refuses a zero/negative request volume rather than returning Infinity', () => {
+    expect(() => deriveCpuBudgetMs({ requestsPerMonth: 0 })).toThrow(/must be > 0/);
+  });
+});
+
+describe('what going over actually costs', () => {
+  it('prices the overage — 3× the CPU budget at this traffic is about $1.20/month', () => {
+    const requestsPerMonth = OWNER_PROJECTED_REQUESTS_PER_DAY * DAYS_PER_MONTH;
+    const { cpuUsd, requestsUsd, totalUsd } = monthlyOverageUsd({
+      requestsPerMonth,
+      meanCpuMsPerRequest: DEFAULT_ROUTE_CPU_BUDGET_MS * 3,
+    });
+    // Requests are still well inside the included 10 M, so the whole bill is CPU.
+    expect(requestsUsd).toBe(0);
+    expect(cpuUsd).toBeCloseTo(1.2, 1);
+    expect(totalUsd).toBeCloseTo(1.2, 1);
+  });
+
+  it('charges nothing while both allowances are unspent', () => {
+    const { totalUsd } = monthlyOverageUsd({
+      requestsPerMonth: 1_000_000,
+      meanCpuMsPerRequest: 5,
+    });
+    expect(totalUsd).toBe(0);
+  });
+});
+
+describe('declaring a budget', () => {
+  it('prefers a method-specific key over a path-wide one', () => {
+    const config = { routes: { 'POST /api/x': 40, '/api/x': 2 } };
+    expect(resolveBudget(config, 'POST', '/api/x').cpuMs).toBe(40);
+    expect(resolveBudget(config, 'GET', '/api/x').cpuMs).toBe(2);
+  });
+
+  it('falls through to the default and says it was not declared', () => {
+    const r = resolveBudget({}, 'GET', '/whatever');
+    expect(r.cpuMs).toBe(DEFAULT_ROUTE_CPU_BUDGET_MS);
+    expect(r.declared).toBe(false);
+  });
+
+  it('carries an exemption through as a null ceiling plus its reason', () => {
+    const r = resolveBudget(
+      { routes: { 'POST /unlock': { exempt: true, reason: 'argon2id KDF' } } },
+      'POST',
+      '/unlock',
+    );
+    expect(r.cpuMs).toBeNull();
+    expect(r.exemptReason).toBe('argon2id KDF');
+    expect(r.declared).toBe(true);
+  });
+
+  // 🔴 The rule the task names: an opt-out must justify itself.
+  it('REFUSES an exemption with no reason', () => {
+    expect(() =>
+      validateCpuBudgetConfig({
+        routes: { '/unlock': { exempt: true, reason: '  ' } },
+      }),
+    ).toThrow(/exempt with no reason/);
+  });
+
+  it('refuses a nonsense budget up front, not when the route is first hit', () => {
+    expect(() => validateCpuBudgetConfig({ routes: { '/a': 0 } })).toThrow(/must be > 0/);
+    expect(() => validateCpuBudgetConfig({ routes: { '/a': -3 } })).toThrow(/must be > 0/);
+    expect(() => validateCpuBudgetConfig({ defaultCpuMs: 0 })).toThrow(/defaultCpuMs/);
+  });
+});
+
+describe('percentiles', () => {
+  // 🔴 The reason the report is a p99 and not a mean, stated as a test: this exact
+  // distribution PASSES a 9.9 ms budget on its mean and FAILS it on its p99.
+  it('reports the tail the mean hides', () => {
+    const samples = [...Array(98).fill(1), 400, 400].sort((a, b) => a - b);
+    const mean = samples.reduce((a, b) => a + b, 0) / samples.length;
+    expect(mean).toBeCloseTo(8.98, 2);
+    expect(mean).toBeLessThan(DEFAULT_ROUTE_CPU_BUDGET_MS); // a mean-based gate: green
+    expect(percentile(samples, 99)).toBe(400); // a p99-based gate: red, correctly
+    expect(percentile(samples, 50)).toBe(1);
+  });
+
+  it('uses nearest-rank, so it never reports a cost no request actually paid', () => {
+    const s = [1, 2, 3, 4];
+    expect(percentile(s, 50)).toBe(2);
+    expect(percentile(s, 75)).toBe(3);
+    expect(percentile(s, 99)).toBe(4);
+    // An interpolating p75 would answer 3.25 — a number no sample equals.
+    expect(s).toContain(percentile(s, 75));
+  });
+
+  it('answers NaN for no samples rather than 0', () => {
+    expect(percentile([], 99)).toBeNaN();
+  });
+});

package/src/server/bench/budget.ts

@@ -0,0 +1,207 @@
+/**
+ * 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: {
+    /** 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 {
+  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: {
+  requestsPerMonth: number;
+  meanCpuMsPerRequest: number;
+}): { cpuUsd: number; requestsUsd: number; totalUsd: number } {
+  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;
+
+/** 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 function isExemption(b: RouteBudget): b is CpuBudgetExemption {
+  return typeof b === 'object' && 'exempt' in b && b.exempt === true;
+}
+
+/** 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 function validateCpuBudgetConfig(config: CpuBudgetConfig): void {
+  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: CpuBudgetConfig,
+  method: string,
+  route: string,
+): ResolvedBudget {
+  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,
+  };
+}