cursedbelt-server 2.0.0 → 3.0.0

package/src/server/bench/cpuBudget.spec.ts

@@ -0,0 +1,302 @@
+import { describe, expect, it } from 'bun:test';
+import { Hono } from 'hono';
+import { assertCpuBudgets, checkCpuBudgets, formatCpuBudgetReport } from './assert';
+import { type CpuBudgetConfig, DEFAULT_ROUTE_CPU_BUDGET_MS } from './budget';
+import { cpuBudget } from './cpuBudget';
+import { fixedCpuClock, processCpuClock, unavailableCpuClock } from './cpuClock';
+import { createCpuRecorder } from './recorder';
+import { runCpuBench } from './runBench';
+
+/**
+ * 🔴 **The assertion must fire in BOTH directions or it is decoration.** A gate that can
+ * only pass is indistinguishable from no gate, and a gate that always fails gets deleted
+ * in a week. Everything below is one of those two directions.
+ *
+ * The end-to-end cases burn REAL CPU through a REAL Hono app, because the thing being
+ * proven is that the middleware attributes cost to the right route — which a mocked clock
+ * cannot show. The deterministic cases use `fixedCpuClock` for the edges, where a real
+ * timing would make the suite flaky for no extra truth.
+ */
+
+/** Burn approximately `ms` of CPU. Deliberately un-optimizable: the result escapes. */
+function burnCpu(ms: number): number {
+  const deadline = performance.now() + ms;
+  let acc = 0;
+  while (performance.now() < deadline) {
+    for (let i = 0; i < 2_000; i += 1) acc += Math.sqrt(i + acc % 7);
+  }
+  return acc;
+}
+
+const SLOW_MS = 30; // ~3× the 9.9 ms budget — far outside measurement noise.
+
+function buildApp(config: CpuBudgetConfig, clock = processCpuClock()) {
+  const recorder = createCpuRecorder({ clock, config });
+  const app = new Hono();
+  app.use('*', cpuBudget({ recorder }));
+  app.get('/api/cheap', (c) => c.json({ ok: true }));
+  app.get('/api/slow', (c) => c.json({ ok: true, acc: burnCpu(SLOW_MS) }));
+  app.post('/api/unlock', (c) => c.json({ ok: true, acc: burnCpu(SLOW_MS) }));
+  return { app, recorder };
+}
+
+describe('direction 1 — a route under budget PASSES', () => {
+  it('measures a cheap JSON route and asserts green', async () => {
+    const { app, recorder } = buildApp({ routes: { 'GET /api/cheap': 5 } });
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [{ path: '/api/cheap' }],
+      iterations: 25,
+    });
+
+    expect(report.routes).toHaveLength(1);
+    const row = report.routes[0];
+    expect(row.key).toBe('GET /api/cheap');
+    expect(row.samples).toBe(25);
+    expect(row.p99).toBeLessThan(5);
+    // Does not throw — that IS the assertion under test.
+    expect(assertCpuBudgets(report)).toEqual([]);
+  });
+});
+
+describe('direction 2 — a route over budget FAILS, and names itself', () => {
+  it('reddens on a deliberately slow route and puts the route and its number in the message', async () => {
+    const { app, recorder } = buildApp({}); // no declaration → the 9.9 ms default applies
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [{ path: '/api/slow' }],
+      iterations: 20,
+      warmup: 3,
+    });
+
+    const row = report.routes[0];
+    expect(row.key).toBe('GET /api/slow');
+    expect(row.p99).toBeGreaterThan(DEFAULT_ROUTE_CPU_BUDGET_MS);
+
+    let message = '';
+    expect(() => {
+      try {
+        assertCpuBudgets(report);
+      } catch (err) {
+        message = (err as Error).message;
+        throw err;
+      }
+    }).toThrow(/over CPU budget/);
+
+    // 🔴 The failure names the ROUTE…
+    expect(message).toContain('GET /api/slow');
+    // …and its NUMBER, and the budget it broke.
+    expect(message).toMatch(/spent \d+\.\d+ CPU-ms at p99/);
+    expect(message).toContain('9.90 CPU-ms');
+    expect(message).toMatch(/\d+\.\d+×/);
+    // …and the whole table, so the reader does not have to go looking.
+    expect(message).toContain('p50');
+  });
+
+  it('attributes cost to the RIGHT route when a cheap and an expensive one share an app', async () => {
+    const { app, recorder } = buildApp({ routes: { 'GET /api/cheap': 5, 'GET /api/slow': 5 } });
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [{ path: '/api/cheap' }, { path: '/api/slow' }],
+      iterations: 20,
+      warmup: 3,
+    });
+
+    const cheap = report.routes.find((r) => r.route === '/api/cheap');
+    const slow = report.routes.find((r) => r.route === '/api/slow');
+    expect(cheap?.p99).toBeLessThan(5);
+    expect(slow?.p99).toBeGreaterThan(SLOW_MS * 0.5);
+
+    const violations = checkCpuBudgets(report);
+    expect(violations.map((v) => v.key)).toEqual(['GET /api/slow']);
+    // Worst offender is sorted to the top of the report.
+    expect(report.routes[0].route).toBe('/api/slow');
+  });
+});
+
+describe('the exemption — the KDF is the type specimen', () => {
+  it('lets a named exemption through while the same cost fails undeclared', async () => {
+    const config: CpuBudgetConfig = {
+      routes: {
+        'POST /api/unlock': {
+          exempt: true,
+          reason: 'argon2id KDF: 332 CPU-ms and 64 MiB measured — expensive on purpose',
+        },
+      },
+    };
+    const { app, recorder } = buildApp(config);
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [{ method: 'POST', path: '/api/unlock' }],
+      iterations: 20,
+      warmup: 3,
+    });
+
+    const row = report.routes[0];
+    expect(row.budgetMs).toBeNull();
+    expect(row.exemptReason).toContain('argon2id');
+    expect(row.p99).toBeGreaterThan(DEFAULT_ROUTE_CPU_BUDGET_MS); // genuinely over
+    expect(assertCpuBudgets(report)).toEqual([]); // and deliberately allowed
+
+    expect(formatCpuBudgetReport(report)).toContain('exempt: argon2id KDF');
+  });
+
+  it('still NOTICES an exempt route that crosses its own threshold, without failing', () => {
+    const recorder = createCpuRecorder({
+      clock: fixedCpuClock([500]),
+      config: {
+        routes: {
+          '/unlock': { exempt: true, reason: 'KDF', noticeAboveMs: 400 },
+        },
+      },
+    });
+    for (let i = 0; i < 25; i += 1) recorder.record('POST', '/unlock', 500);
+    const violations = checkCpuBudgets(recorder.report());
+    expect(violations).toHaveLength(1);
+    expect(violations[0].kind).toBe('exempt-notice');
+    expect(violations[0].fails).toBe(false);
+    expect(() => assertCpuBudgets(recorder.report())).not.toThrow();
+  });
+});
+
+describe('the ways a green could be a lie', () => {
+  it('FAILS a route it could not sample enough times to have a p99', () => {
+    const recorder = createCpuRecorder({ clock: fixedCpuClock([1]) });
+    for (let i = 0; i < 3; i += 1) recorder.record('GET', '/api/x', 1);
+    expect(() => assertCpuBudgets(recorder.report())).toThrow(/needs at least 20/);
+  });
+
+  it('FAILS when the clock could not measure at all, rather than passing on zero', () => {
+    const recorder = createCpuRecorder({ clock: unavailableCpuClock() });
+    recorder.record('GET', '/api/x', Number.NaN);
+    const report = recorder.report();
+    expect(report.routes).toHaveLength(0); // an unmeasurable request is not a sample
+    expect(() => assertCpuBudgets(report)).toThrow(/nothing could be measured/);
+    expect(assertCpuBudgets(report, { allowUnmeasurable: true })).toEqual([]);
+  });
+
+  it('FAILS an undeclared route under requireDeclared, so an app must budget every route', () => {
+    const recorder = createCpuRecorder({ clock: fixedCpuClock([1]) });
+    for (let i = 0; i < 25; i += 1) recorder.record('GET', '/api/undeclared', 1);
+    expect(() => assertCpuBudgets(recorder.report(), { requireDeclared: true })).toThrow(
+      /declares no CPU budget/,
+    );
+    // The same route passes without the flag — the default still applies.
+    expect(assertCpuBudgets(recorder.report())).toEqual([]);
+  });
+
+  // 🔴 A 404 costs no CPU. Without this guard the bench reports a beautiful number for a
+  // handler that never ran.
+  it('REFUSES to bench a route that errors, instead of reporting its cheap 404', async () => {
+    const { app, recorder } = buildApp({});
+    await expect(
+      runCpuBench({ app, recorder, cases: [{ path: '/api/does-not-exist' }], iterations: 5 }),
+    ).rejects.toThrow(/returned 404, which this case does not expect/);
+  });
+
+  it('can bench an error path deliberately, when the case says so', async () => {
+    const { app, recorder } = buildApp({});
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [{ path: '/api/does-not-exist', expectStatus: 404 }],
+      iterations: 20,
+      warmup: 2,
+    });
+    expect(report.routes[0].samples).toBe(20);
+  });
+});
+
+describe('honesty of the number', () => {
+  it('labels a local reading as a PROXY, in the report and in its formatting', async () => {
+    const { app, recorder } = buildApp({ routes: { 'GET /api/cheap': 5 } });
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [{ path: '/api/cheap' }],
+      iterations: 20,
+    });
+    expect(report.proxy).toBe(true);
+    expect(report.source).toBe('process.cpuUsage');
+    expect(formatCpuBudgetReport(report)).toContain('🔴 PROXY');
+    expect(formatCpuBudgetReport(report)).toContain('NOT Worker CPU-ms');
+  });
+
+  it('does NOT label a runtime-supplied reading as a proxy', () => {
+    let cpu = 0;
+    const recorder = createCpuRecorder({
+      clock: {
+        source: 'worker-runtime',
+        proxy: false,
+        available: true,
+        start: () => {
+          const before = cpu;
+          cpu += 1;
+          return () => cpu - before;
+        },
+      },
+    });
+    for (let i = 0; i < 25; i += 1) recorder.record('GET', '/x', 1);
+    const report = recorder.report();
+    expect(report.proxy).toBe(false);
+    expect(formatCpuBudgetReport(report)).toContain('runtime-reported Worker CPU-ms');
+  });
+});
+
+describe('the bench runner', () => {
+  it('DISCARDS warm-up, so a cold first call cannot become the p99', async () => {
+    // The first span through this clock reads 1000; every later one reads 1. With warm-up
+    // discarded the route is cheap; without it, one cold call owns the p99 of 20 samples.
+    const clock = fixedCpuClock([1000, 1, 1]);
+    const recorder = createCpuRecorder({ clock, config: { routes: { '/api/cheap': 5 } } });
+    const app = new Hono();
+    app.use('*', cpuBudget({ recorder }));
+    app.get('/api/cheap', (c) => c.json({ ok: true }));
+
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [{ path: '/api/cheap' }],
+      iterations: 20,
+      warmup: 1,
+    });
+    expect(report.routes[0].max).toBe(1);
+    expect(report.routes[0].samples).toBe(20);
+    expect(assertCpuBudgets(report)).toEqual([]);
+  });
+
+  // A handler that is expensive only on its error path is exactly what a budget should
+  // catch, so the sample must survive the throw. The middleware re-throws unchanged and
+  // Hono's own onError turns it into the 500 — the CPU is attributed either way.
+  it('records CPU even when the handler throws, and leaves error handling alone', async () => {
+    const recorder = createCpuRecorder({ clock: fixedCpuClock([42]) });
+    const seen: string[] = [];
+    const app = new Hono();
+    app.onError((err, c) => {
+      seen.push((err as Error).message);
+      return c.json({ error: 'handled' }, 500);
+    });
+    app.use('*', cpuBudget({ recorder }));
+    app.get('/boom', () => {
+      throw new Error('kaboom');
+    });
+
+    const res = await app.request('http://cpu-bench.invalid/boom');
+    expect(res.status).toBe(500);
+    // Re-thrown unchanged: the app's own onError saw the original error.
+    expect(seen).toEqual(['kaboom']);
+
+    const report = recorder.report();
+    expect(report.routes[0].key).toBe('GET /boom');
+    expect(report.routes[0].max).toBe(42);
+  });
+
+  it('refuses a run with no cases rather than passing vacuously', async () => {
+    const { app, recorder } = buildApp({});
+    await expect(runCpuBench({ app, recorder, cases: [] })).rejects.toThrow(/no cases/);
+  });
+});

package/src/server/bench/cpuBudget.ts

@@ -0,0 +1,81 @@
+import type { MiddlewareHandler } from 'hono';
+import type { CursedbeltEnv } from '../context';
+import { normalizeRoute } from '../metrics/normalizeRoute';
+import type { CpuBudgetConfig } from './budget';
+import { type CpuClock, processCpuClock } from './cpuClock';
+import { type CpuRecorder, createCpuRecorder } 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 function cpuBudget(
+  opts: CpuBudgetOpts = {},
+): MiddlewareHandler<CursedbeltEnv> & { recorder: CpuRecorder } {
+  const recorder =
+    opts.recorder ??
+    createCpuRecorder({ clock: opts.clock ?? processCpuClock(), config: opts.config });
+
+  const handler: MiddlewareHandler<CursedbeltEnv> = async (c, next) => {
+    const end = recorder.clock.start();
+    let thrown: unknown;
+    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/src/server/bench/cpuClock.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 function processCpuClock(): CpuClock {
+  const usable = typeof process !== 'undefined' && typeof process.cpuUsage === 'function';
+  if (!usable) return unavailableCpuClock('process.cpuUsage (absent)');
+  return {
+    source: 'process.cpuUsage',
+    proxy: true,
+    available: true,
+    start(): CpuSpan {
+      const before = process.cpuUsage();
+      return () => {
+        const d = process.cpuUsage(before);
+        return (d.user + d.system) / 1000;
+      };
+    },
+  };
+}
+
+/**
+ * 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 function workerCpuClock(readCpuMs: () => number, source = 'worker-runtime'): CpuClock {
+  return {
+    source,
+    proxy: false,
+    available: true,
+    start(): CpuSpan {
+      const before = readCpuMs();
+      return () => Math.max(0, readCpuMs() - before);
+    },
+  };
+}
+
+/**
+ * A clock that cannot measure. Recording through it is a no-op, and the report says so
+ * rather than reporting a confident zero.
+ */
+export function unavailableCpuClock(source = 'unavailable'): CpuClock {
+  return {
+    source,
+    proxy: true,
+    available: false,
+    start: () => () => Number.NaN,
+  };
+}
+
+/**
+ * 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 function fixedCpuClock(values: number[], source = 'fixed'): CpuClock {
+  if (values.length === 0) throw new Error('fixedCpuClock: needs at least one value');
+  let i = 0;
+  return {
+    source,
+    proxy: true,
+    available: true,
+    start(): CpuSpan {
+      const v = values[Math.min(i, values.length - 1)];
+      i += 1;
+      return () => v;
+    },
+  };
+}
+
+/** `workerCpuClock` when the platform supplied a reader, else the local proxy. */
+export function resolveCpuClock(readCpuMs?: (() => number) | null): CpuClock {
+  return readCpuMs ? workerCpuClock(readCpuMs) : processCpuClock();
+}

package/src/server/bench/index.ts

@@ -0,0 +1,81 @@
+/**
+ * `cursedbelt-server/bench` — per-route CPU attribution for a Hono app, a budget the app
+ * declares, and an assertion that reddens a build when a route outgrows it.
+ *
+ * ## The shape of a use
+ *
+ * ```ts
+ * // routes.budgets.ts — the app declares what each route may cost
+ * export const BUDGETS: CpuBudgetConfig = {
+ *   routes: {
+ *     'GET /api/notes/:id': 4,
+ *     'POST /api/unlock': { exempt: true, reason: 'argon2id KDF — 332 CPU-ms, measured' },
+ *   },
+ * }
+ *
+ * // app.ts
+ * export const cpu = createCpuRecorder({ clock: processCpuClock(), config: BUDGETS })
+ * app.use('*', cpuBudget({ recorder: cpu }))
+ *
+ * // cpuBudget.spec.ts — the gate
+ * const report = await runCpuBench({ app, recorder: cpu, cases: CASES })
+ * assertCpuBudgets(report, { requireDeclared: true })
+ * ```
+ *
+ * ## 🔴 Two things to carry away
+ *
+ * **Wall clock is never billed.** Cloudflare's own pricing page says *"No charge or limit
+ * for duration"*. `requestLogger` records duration; this records CPU; they are different
+ * numbers and only the second one costs money.
+ *
+ * **A local reading is a PROXY.** `process.cpuUsage()` on this Mac is not Worker CPU-ms.
+ * Every report carries `proxy: true` and every formatted report says so, because the
+ * alternative is a number that gets quoted as a billing fact.
+ */
+
+export {
+  type AssertCpuBudgetsOpts,
+  assertCpuBudgets,
+  checkCpuBudgets,
+  type CpuViolation,
+  type CpuViolationKind,
+  formatCpuBudgetReport,
+} from './assert';
+export {
+  type CpuBudgetConfig,
+  type CpuBudgetExemption,
+  type CpuBudgetLimit,
+  DAYS_PER_MONTH,
+  DEFAULT_ROUTE_CPU_BUDGET_MS,
+  deriveCpuBudgetMs,
+  isExemption,
+  monthlyOverageUsd,
+  OWNER_PROJECTED_REQUESTS_PER_DAY,
+  type ResolvedBudget,
+  resolveBudget,
+  type RouteBudget,
+  validateCpuBudgetConfig,
+  WORKERS_PAID_INCLUDED_CPU_MS,
+  WORKERS_PAID_INCLUDED_REQUESTS,
+  WORKERS_PAID_USD_PER_MILLION_CPU_MS,
+  WORKERS_PAID_USD_PER_MILLION_REQUESTS,
+} from './budget';
+export { type CpuBudgetOpts, cpuBudget } from './cpuBudget';
+export {
+  type CpuClock,
+  type CpuSpan,
+  fixedCpuClock,
+  processCpuClock,
+  resolveCpuClock,
+  unavailableCpuClock,
+  workerCpuClock,
+} from './cpuClock';
+export {
+  type CpuBudgetReport,
+  type CpuRecorder,
+  type CpuRecorderOpts,
+  createCpuRecorder,
+  percentile,
+  type RouteCpuStats,
+} from './recorder';
+export { BENCH_ORIGIN, type BenchCase, runCpuBench, type RunCpuBenchOpts } from './runBench';