cursedbelt-server 1.0.2 → 2.0.0

package/src/server/metrics/telemetrySink.spec.ts

@@ -0,0 +1,288 @@
+import { Database } from 'bun:sqlite';
+import { beforeEach, describe, expect, it } from 'bun:test';
+import { Hono } from 'hono';
+import { type RequestLoggerOpts, requestLogger } from '../middleware/requestLogger';
+import { createMetricsBuffer } from './metricsBuffer';
+import {
+  type AnalyticsEngineDataset,
+  createTelemetrySink,
+  type TelemetrySink,
+  toDataPoint,
+} from './telemetrySink';
+
+/**
+ * The two claims the seam makes, and nothing else:
+ *
+ *   1. Analytics Engine bound  → a request writes **ZERO** `request_metrics` rows.
+ *      This is the claim with money behind it: a row per request on D1 is billed
+ *      at $1.00 per million rows written, and "we moved to Analytics Engine" is
+ *      worth nothing if the insert is still firing beside it.
+ *   2. Analytics Engine ABSENT → the SQLite path is byte-for-byte what it is
+ *      today. Proven by running the same request through the sink-backed logger
+ *      and through a hand-built `createMetricsBuffer` — the pre-seam call — and
+ *      comparing every column. The gate and every Mac-hosted app ride on this.
+ */
+
+/** The `request_metrics` / `event_logs` DDL `metricsBuffer` + `requestLogger` write. */
+function schema(db: Database): void {
+  db.run(`CREATE TABLE request_metrics (
+    id TEXT PRIMARY KEY, ts INTEGER NOT NULL, method TEXT, route TEXT,
+    status INTEGER, duration_ms REAL, bytes_out INTEGER, user_id TEXT)`);
+  db.run(`CREATE TABLE event_logs (
+    id TEXT PRIMARY KEY, correlation_id TEXT, event_name TEXT, type TEXT, message TEXT,
+    details TEXT, duration_ms INTEGER, user_id TEXT, created_at TEXT)`);
+}
+
+type Point = Parameters<AnalyticsEngineDataset['writeDataPoint']>[0];
+
+/** A recording stand-in for the platform binding. */
+function fakeDataset(): AnalyticsEngineDataset & { points: Point[] } {
+  const points: Point[] = [];
+  return {
+    points,
+    writeDataPoint(point) {
+      points.push(point);
+    },
+  };
+}
+
+const rows = (db: Database) =>
+  db.query('SELECT * FROM request_metrics ORDER BY ts').all() as Record<string, unknown>[];
+
+describe('createTelemetrySink — Analytics Engine bound means ZERO database rows', () => {
+  let db: Database;
+  beforeEach(() => {
+    db = new Database(':memory:');
+    schema(db);
+  });
+
+  it('writes no request_metrics row for a served request, and one data point instead', async () => {
+    const ae = fakeDataset();
+    const app = new Hono();
+    // 🔴 `db` is passed as well: the binding must WIN over an available database,
+    // not merely work in its absence. A Worker mid-migration has both.
+    app.use('*', requestLogger(db, { analytics: ae }));
+    app.get('/api/people/:id/portrait', (c) => c.text('bytes'));
+
+    expect((await app.request('/api/people/42/portrait')).status).toBe(200);
+
+    // The flush timer would be the only other writer; force it and re-check.
+    await Bun.sleep(5);
+    expect(rows(db)).toHaveLength(0);
+    expect(db.query('SELECT COUNT(*) AS n FROM event_logs').get()).toEqual({ n: 0 });
+
+    expect(ae.points).toHaveLength(1);
+    const [point] = ae.points;
+    expect(point.indexes).toEqual(['/api/people/:id/portrait']);
+    expect(point.blobs?.[0]).toBe('GET');
+    expect(point.blobs?.[1]).toBe('/api/people/:id/portrait');
+    expect(point.doubles?.[0]).toBe(200);
+  });
+
+  it('writes no row for a THROWN request either — the error path is the tempting leak', async () => {
+    const ae = fakeDataset();
+    const app = new Hono();
+    app.use('*', requestLogger(db, { analytics: ae }));
+    app.get('/boom', () => {
+      throw new Error('nope');
+    });
+    app.onError((_e, c) => c.text('handled', 500));
+
+    expect((await app.request('/boom')).status).toBe(500);
+    await Bun.sleep(5);
+
+    expect(rows(db)).toHaveLength(0);
+    expect(ae.points).toHaveLength(1);
+    expect(ae.points[0].doubles?.[0]).toBe(500);
+  });
+
+  it('needs no database at all — the Worker shape, where bun:sqlite does not exist', async () => {
+    const ae = fakeDataset();
+    const app = new Hono();
+    app.use('*', requestLogger(null, { analytics: ae }));
+    app.get('/', (c) => c.text('ok'));
+
+    expect((await app.request('/')).status).toBe(200);
+    expect(ae.points).toHaveLength(1);
+  });
+
+  it('holds nothing locally, so there is no buffer to lose on isolate teardown', () => {
+    const sink = createTelemetrySink({ analytics: fakeDataset(), db: null });
+    sink.record({
+      ts: 1,
+      method: 'GET',
+      route: '/',
+      status: 200,
+      durationMs: 1,
+      bytesOut: 2,
+      userId: null,
+    });
+    expect(sink.size).toBe(0);
+    // flush/stop are honest no-ops, not silent drops — calling them changes nothing.
+    sink.flush();
+    sink.stop();
+    expect(sink.size).toBe(0);
+  });
+
+  it('refuses to construct with neither backend rather than drop telemetry silently', () => {
+    expect(() => createTelemetrySink({ db: null, analytics: null })).toThrow(
+      /neither an Analytics Engine binding/,
+    );
+  });
+});
+
+describe('toDataPoint — the layout is a wire format', () => {
+  it('maps every column to its documented position, with -1 for unknown', () => {
+    expect(
+      toDataPoint({
+        ts: 123,
+        method: 'POST',
+        route: '/api/v1/sync/requested',
+        status: 204,
+        durationMs: 12.5,
+        bytesOut: null,
+        userId: 'u-1',
+      }),
+    ).toEqual({
+      indexes: ['/api/v1/sync/requested'],
+      blobs: ['POST', '/api/v1/sync/requested', 'u-1'],
+      // bytesOut null → -1. `0` is a real value for a 204, so it cannot be the marker.
+      doubles: [204, 12.5, -1],
+    });
+  });
+
+  it('truncates the index to 96 BYTES, not 96 characters', () => {
+    // 60 three-byte characters = 180 bytes, but only 60 UTF-16 units — `slice(0, 96)`
+    // would leave 180 bytes and the platform would reject the data point.
+    const route = `/${'路'.repeat(60)}`;
+    const { indexes, blobs } = toDataPoint({
+      ts: 1,
+      method: 'GET',
+      route,
+      status: 200,
+      durationMs: 1,
+      bytesOut: 1,
+      userId: null,
+    });
+    const bytes = new TextEncoder().encode(indexes[0]).length;
+    expect(bytes).toBeLessThanOrEqual(96);
+    // Not split mid-character: it round-trips, so no U+FFFD was left behind.
+    expect(indexes[0]).toBe(new TextDecoder().decode(new TextEncoder().encode(indexes[0])));
+    expect(indexes[0].includes('�')).toBe(false);
+    // …and blob2 keeps the FULL route, so nothing is actually lost.
+    expect(blobs[1]).toBe(route);
+  });
+
+  it('an anonymous request sends an empty userId blob, never a null hole', () => {
+    const { blobs } = toDataPoint({
+      ts: 1,
+      method: 'GET',
+      route: '/',
+      status: 200,
+      durationMs: 1,
+      bytesOut: 0,
+      userId: null,
+    });
+    expect(blobs[2]).toBe('');
+  });
+});
+
+describe('createTelemetrySink — no binding means the SQLite path, unchanged', () => {
+  /** Columns that are allowed to differ between two identical requests. */
+  const stable = (row: Record<string, unknown>) => {
+    const { id: _id, ts: _ts, duration_ms: _d, ...rest } = row;
+    return rest;
+  };
+
+  it('produces the same row the pre-seam createMetricsBuffer call produces', async () => {
+    const viaSink = new Database(':memory:');
+    const viaBuffer = new Database(':memory:');
+    schema(viaSink);
+    schema(viaBuffer);
+
+    const build = (db: Database, logger: ReturnType<typeof requestLogger>) => {
+      const app = new Hono();
+      app.use('*', logger);
+      // 🔴 `content-length` is set EXPLICITLY. `requestLogger` reads `bytes_out` off
+      // that header and Hono does not add one for a small in-process response, so
+      // without it this test would assert `bytes_out: null` and prove nothing about
+      // the column that actually carries bytes.
+      app.get('/api/player', (c) => c.json({ playing: false }, 200, { 'content-length': '18' }));
+      return { app, db };
+    };
+
+    // The new path: no `analytics`, so the sink resolves to the SQLite buffer.
+    const a = build(viaSink, requestLogger(viaSink));
+    // The pre-seam path, spelled exactly as a caller spelled it before this change.
+    const priorBuffer = createMetricsBuffer({ db: viaBuffer });
+    const b = build(viaBuffer, requestLogger(viaBuffer, { buffer: priorBuffer }));
+
+    expect((await a.app.request('/api/player')).status).toBe(200);
+    expect((await b.app.request('/api/player')).status).toBe(200);
+
+    // Both buffer; both must flush the same way. 1500ms is the shared cadence, so
+    // force it rather than sleep through it.
+    priorBuffer.flush();
+    await Bun.sleep(1700);
+
+    const sinkRows = rows(viaSink);
+    const bufferRows = rows(viaBuffer);
+    expect(sinkRows).toHaveLength(1);
+    expect(bufferRows).toHaveLength(1);
+    expect(stable(sinkRows[0])).toEqual(stable(bufferRows[0]));
+    // Column-by-column, so a renamed or dropped column cannot hide behind a deep-equal.
+    expect(Object.keys(sinkRows[0])).toEqual([
+      'id',
+      'ts',
+      'method',
+      'route',
+      'status',
+      'duration_ms',
+      'bytes_out',
+      'user_id',
+    ]);
+    expect(stable(sinkRows[0])).toEqual({
+      method: 'GET',
+      route: '/api/player',
+      status: 200,
+      bytes_out: 18,
+      user_id: null,
+    });
+    expect(typeof sinkRows[0].duration_ms).toBe('number');
+  });
+
+  it('still buffers rather than writing per request — the latency property is not lost', () => {
+    const db = new Database(':memory:');
+    schema(db);
+    const sink = createTelemetrySink({ db });
+    sink.record({
+      ts: 1,
+      method: 'GET',
+      route: '/',
+      status: 200,
+      durationMs: 1,
+      bytesOut: 0,
+      userId: null,
+    });
+    // Buffered, NOT written: `size` is 1 and the table is still empty.
+    expect(sink.size).toBe(1);
+    expect(rows(db)).toHaveLength(0);
+    sink.flush();
+    expect(sink.size).toBe(0);
+    expect(rows(db)).toHaveLength(1);
+    sink.stop();
+  });
+
+  it('a MetricsBuffer satisfies TelemetrySink, so an app can keep passing its own', () => {
+    const db = new Database(':memory:');
+    schema(db);
+    const buffer = createMetricsBuffer({ db });
+    // Structural, and the ASSIGNMENT is the assertion — this line is what would stop
+    // compiling if the two shapes ever diverged, which is why it is typed explicitly.
+    const sink: TelemetrySink = buffer;
+    expect(sink.size).toBe(0);
+    const opts: RequestLoggerOpts = { sink: buffer };
+    expect(opts.sink).toBe(buffer);
+    buffer.stop();
+  });
+});

package/src/server/metrics/telemetrySink.ts

@@ -0,0 +1,181 @@
+import type { Database } from 'bun:sqlite';
+import { createMetricsBuffer, type MetricRow, type MetricsBuffer } from './metricsBuffer';
+
+/**
+ * ONE seam for "this app served a request", with two backends and no third.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────
+ * `request_metrics` is a row per request. On D1 that is the one line in
+ * Cloudflare's pricing with a dollar-scale overage — **$1.00 per million rows
+ * written** — and a row per request is precisely the shape that buys it. Workers
+ * Analytics Engine is purpose-built for the same job: `writeDataPoint()` per
+ * event, SQL to query, unlimited cardinality, **10M data points and 1M read
+ * queries included per month**, and **zero** database writes.
+ *
+ * 🔴 **Adopt it for the ALLOWANCE, not because it is unbilled today.**
+ * Cloudflare's own wording is that you "will not be billed for your use of
+ * Workers Analytics Engine" today and that the published prices are "shared in
+ * advance… once Cloudflare starts billing for usage in the coming months". The
+ * free-today part is temporary; the allowance is not. At this fleet's measured
+ * ~1M requests/month the bill is $0 either way, so building against the
+ * allowance makes the billing switch a non-event.
+ *
+ * ── Why not `prom-client` / a `/metrics` scrape ──────────────────────────────
+ * A scrape genuinely does turn many writes into one, and on a long-lived Bun
+ * process it would work. A Worker is **a stateless V8 isolate with no
+ * long-lived process**: isolates are created and destroyed between requests and
+ * run concurrently in many datacentres, so a `/metrics` scrape reaches ONE
+ * arbitrary isolate holding a random fraction of the counters. The in-process
+ * registry has nowhere to live. (A Durable Object does have a durable identity
+ * *and* memory, and is the real `prom-client` analogue — but it is a whole
+ * stateful object to operate for counters Analytics Engine already aggregates.
+ * Prometheus itself also needs an always-on host to scrape FROM, and that host
+ * is the Mac this fleet is trying to switch off.)
+ *
+ * ── The contract ────────────────────────────────────────────────────────────
+ * · `analytics` bound  → one `writeDataPoint` per event, **zero** SQLite/D1 rows.
+ * · no `analytics`     → the existing {@link MetricsBuffer}, byte-for-byte
+ *                        unchanged, so the gate and a Mac-hosted app keep working.
+ * Both are proven by `telemetrySink.spec.ts`, which is the point of the seam:
+ * the choice is made ONCE here rather than per app.
+ */
+
+/**
+ * The Workers Analytics Engine binding, typed locally so this package needs no
+ * dependency on `@cloudflare/workers-types` (it is a Bun/Hono package, and a
+ * Worker supplies the real binding at runtime).
+ *
+ * Platform limits, which {@link toDataPoint} respects:
+ * **1** index of ≤96 bytes, ≤**20** blobs totalling ≤5120 bytes, ≤**20** doubles.
+ */
+export interface AnalyticsEngineDataset {
+  writeDataPoint(point: {
+    indexes?: (ArrayBuffer | string | null)[];
+    blobs?: (ArrayBuffer | string | null)[];
+    doubles?: number[];
+  }): void;
+}
+
+/** One request's telemetry. Identical to {@link MetricRow} — the seam does not re-shape it. */
+export type TelemetryEvent = MetricRow;
+
+/**
+ * A superset-compatible shape: a {@link MetricsBuffer} IS a `TelemetrySink`, so
+ * an app that already owns a buffer can keep passing it.
+ */
+export interface TelemetrySink {
+  /** Enqueue one request's telemetry. Never blocks the response. */
+  record(event: TelemetryEvent): void;
+  /** Force whatever is pending out now (shutdown + tests). No-op on Analytics Engine. */
+  flush(): void;
+  /** Stop any timer and drain. No-op on Analytics Engine. */
+  stop(): void;
+  /** Events pending locally. Always 0 on Analytics Engine — it has no buffer to hold. */
+  readonly size: number;
+}
+
+export interface TelemetrySinkOptions {
+  /**
+   * The Analytics Engine binding, when the platform supplies one. Present ⇒ it
+   * WINS, and `db` is never written. `null`/`undefined` ⇒ the SQLite path.
+   */
+  analytics?: AnalyticsEngineDataset | null;
+  /** The `request_metrics` database. Required unless `analytics` is bound. */
+  db?: Database | null;
+  /** Flush cadence for the SQLite path, in ms. Default: 1500. Ignored by Analytics Engine. */
+  flushIntervalMs?: number;
+  /** Eager-flush threshold for the SQLite path. Default: 5000. Ignored by Analytics Engine. */
+  maxSize?: number;
+}
+
+/**
+ * 🔴 **The data-point layout is a WIRE FORMAT.** Analytics Engine columns are
+ * positional (`blob1`, `double1`, …), so every saved SQL query breaks if a
+ * position moves. Append only; never reorder, never repurpose.
+ *
+ * ```
+ * index1  = route, truncated to 96 bytes  — the sampling key, so sampling is per route
+ * blob1   = method          blob2  = route (untruncated)     blob3  = userId ('' when anonymous)
+ * double1 = status          double2 = durationMs             double3 = bytesOut
+ * ```
+ *
+ * `ts` is deliberately absent: Analytics Engine stamps its own `timestamp`
+ * column, so sending ours would store the same instant twice.
+ *
+ * `-1` is the "unknown" marker for all three doubles, because a positional
+ * doubles array cannot hold a null and `0` is a real value for every one of them
+ * (a 0-byte 204, notably). Read it as `NULL`, not as a measurement.
+ */
+export const TELEMETRY_POINT_VERSION = 1;
+
+const INDEX_MAX_BYTES = 96;
+
+/**
+ * Truncate to at most `maxBytes` UTF-8 bytes without splitting a code point —
+ * `String.slice` counts UTF-16 units, so a route with one multi-byte character
+ * can be ≤96 chars and still exceed the 96-BYTE index limit.
+ */
+function truncateUtf8(value: string, maxBytes: number): string {
+  const encoded = new TextEncoder().encode(value);
+  if (encoded.length <= maxBytes) return value;
+  return new TextDecoder('utf-8', { fatal: false }).decode(encoded.subarray(0, maxBytes)).replace(
+    // A cut through a multi-byte sequence decodes to U+FFFD; drop that trailing artefact.
+    /�+$/,
+    '',
+  );
+}
+
+const num = (value: number | null | undefined): number =>
+  typeof value === 'number' && Number.isFinite(value) ? value : -1;
+
+/** The documented layout above, as data. Exported so the spec asserts the wire format itself. */
+export function toDataPoint(event: TelemetryEvent): {
+  indexes: string[];
+  blobs: string[];
+  doubles: number[];
+} {
+  const route = event.route ?? '';
+  return {
+    indexes: [truncateUtf8(route, INDEX_MAX_BYTES)],
+    blobs: [event.method ?? '', route, event.userId ?? ''],
+    doubles: [num(event.status), num(event.durationMs), num(event.bytesOut)],
+  };
+}
+
+/**
+ * Build the sink for whatever platform this process is on.
+ *
+ * Throws when NEITHER backend is available, on purpose. "An app with no
+ * `request_metrics` is not quiet; it is unmeasured" — and a sink that silently
+ * drops every event is exactly the failure this seam exists to end. A misbound
+ * Worker should fail at construction, in the deploy, rather than serve traffic
+ * that nothing can see.
+ */
+export function createTelemetrySink(opts: TelemetrySinkOptions): TelemetrySink {
+  const { analytics, db, flushIntervalMs, maxSize } = opts;
+
+  if (analytics) {
+    // Analytics Engine writes are fire-and-forget and already off the response
+    // path — there is nothing to buffer, so flush/stop are honestly no-ops.
+    return {
+      record(event) {
+        analytics.writeDataPoint(toDataPoint(event));
+      },
+      flush() {},
+      stop() {},
+      get size() {
+        return 0;
+      },
+    };
+  }
+
+  if (!db) {
+    throw new Error(
+      'createTelemetrySink: neither an Analytics Engine binding (`analytics`) nor a `db` was ' +
+        'provided. Telemetry would be silently dropped; bind one of the two.',
+    );
+  }
+
+  // The unchanged SQLite path — same module, same batching, same rows.
+  return createMetricsBuffer({ db, flushIntervalMs, maxSize });
+}

package/src/server/middleware/index.ts

@@ -5,6 +5,15 @@ export { errorEnvelope } from './errorEnvelope';
 export { crossOriginRefusal } from './localOrigin';
 export { clientIp, createRateLimiter, type RateLimitOpts } from './rateLimit';
 export { type RequestLoggerOpts, requestLogger } from './requestLogger';
+// The telemetry seam `requestLogger` writes through — re-exported here so a caller
+// that reaches `./middleware` for the logger can bind Analytics Engine in the same import.
+export {
+  type AnalyticsEngineDataset,
+  createTelemetrySink,
+  type TelemetryEvent,
+  type TelemetrySink,
+  type TelemetrySinkOptions,
+} from '../metrics/telemetrySink';
 export {
   type CspDirectives,
   type SecurityHeadersOpts,

package/src/server/middleware/requestLogger.ts

@@ -3,28 +3,44 @@ import type { MiddlewareHandler } from 'hono';
 import { HTTPException } from 'hono/http-exception';
 import type { CursedbeltEnv } from '../context';
 import { isApiError } from '../errors';
-import { createMetricsBuffer, type MetricsBuffer } from '../metrics/metricsBuffer';
+import type { MetricsBuffer } from '../metrics/metricsBuffer';
 import { normalizeRoute } from '../metrics/normalizeRoute';
+import {
+  type AnalyticsEngineDataset,
+  createTelemetrySink,
+  type TelemetrySink,
+} from '../metrics/telemetrySink';
 
 /**
- * Structured request/response logging. After each request it records one slim
- * `request_metrics` row (via the batched {@link MetricsBuffer}, off the hot path)
- * and, for errors (status ≥ 400) or slow requests, one `event_logs` row tagged with
- * the correlation id. Attributes rows to `c.get('userId')` when the app's auth
+ * Structured request/response logging. After each request it records one
+ * telemetry event through the {@link TelemetrySink} (off the hot path) and, for
+ * errors (status ≥ 400) or slow requests, one `event_logs` row tagged with the
+ * correlation id. Attributes rows to `c.get('userId')` when the app's auth
  * middleware has set it.
  *
+ * 🔴 **Where the telemetry LANDS is the sink's decision, not this file's.** With
+ * an Analytics Engine binding it is one `writeDataPoint` and **zero** database
+ * rows; without one it is the same batched `request_metrics` insert it has always
+ * been. See `../metrics/telemetrySink.ts` for why that is the only choice offered.
+ *
  * It records metrics even when a downstream handler THROWS: the error is caught,
- * the would-be status derived, the row written, then the error re-thrown so the
+ * the would-be status derived, the event recorded, then the error re-thrown so the
  * error-envelope `onError` still produces the response.
  */
 
 export interface RequestLoggerOpts {
   /**
-   * The metrics buffer to write through. Provide one (and own its lifecycle via
-   * `buffer.stop()`) to share it / flush deterministically; omit to create one from
-   * `db`. Its flush timer is `unref()`'d, so an internally-created buffer is fine for
-   * long-running servers.
+   * The Analytics Engine binding, when the platform supplies one. Present ⇒ the
+   * telemetry goes there and NOTHING is written to `request_metrics`.
+   */
+  analytics?: AnalyticsEngineDataset | null;
+  /**
+   * The sink to write through. Provide one (and own its lifecycle via
+   * `sink.stop()`) to share it / flush deterministically; omit to build one from
+   * `db` + `analytics`. A {@link MetricsBuffer} is a valid sink.
    */
+  sink?: TelemetrySink;
+  /** @deprecated Use {@link RequestLoggerOpts.sink} — a `MetricsBuffer` is one. Kept for callers that predate the sink. */
   buffer?: MetricsBuffer;
   /** Duration (ms) at/above which a 2xx request also logs an `event_logs` row. Default: 2000. */
   slowMs?: number;
@@ -38,19 +54,29 @@ function statusOfThrown(err: unknown): number {
   return 500;
 }
 
+/**
+ * @param db The `request_metrics` / `event_logs` database. Pass `null` on a
+ *   platform that has no `bun:sqlite` — a Worker with `analytics` bound — in
+ *   which case `event_logs` is not written either, because there is nowhere to
+ *   put it. `analytics` or `sink` is then mandatory; `createTelemetrySink`
+ *   throws rather than drop telemetry silently.
+ */
 export function requestLogger(
-  db: Database,
+  db: Database | null,
   opts: RequestLoggerOpts = {},
 ): MiddlewareHandler<CursedbeltEnv> {
-  const buffer = opts.buffer ?? createMetricsBuffer({ db });
+  const sink =
+    opts.sink ?? opts.buffer ?? createTelemetrySink({ db, analytics: opts.analytics ?? null });
   const slowMs = opts.slowMs ?? 2000;
   const logErrors = opts.logErrors ?? true;
 
-  const insertEvent = db.prepare(
-    `INSERT INTO event_logs
+  const insertEvent = db
+    ? db.prepare(
+        `INSERT INTO event_logs
        (id, correlation_id, event_name, type, message, details, duration_ms, user_id, created_at)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-  );
+      )
+    : null;
 
   return async (c, next) => {
     const start = performance.now();
@@ -70,11 +96,11 @@ export function requestLogger(
     const bytesOut = lenHeader ? Number(lenHeader) : null;
     const userId = c.get('userId') ?? null;
 
-    buffer.record({ ts: Date.now(), method, route, status, durationMs, bytesOut, userId });
+    sink.record({ ts: Date.now(), method, route, status, durationMs, bytesOut, userId });
 
     const isError = status >= 400;
     const isSlow = durationMs >= slowMs;
-    if ((logErrors && isError) || isSlow) {
+    if (insertEvent && ((logErrors && isError) || isSlow)) {
       const type = status >= 500 ? 'error' : isError ? 'warn' : 'info';
       insertEvent.run(
         crypto.randomUUID(),

package/src/server/sync/http.ts

@@ -12,6 +12,7 @@ import { Hono } from "hono";
 import type { OpLog } from "./opLog";
 import type { ApplyContext, ApplyOne, ApplyReport, PeerInfo, RemoteApi, SyncOp } from "./types";
 import { createSyncApplier } from "./engine";
+import { type SyncSignalHub, signalResponse } from "./signal";
 
 const noStore = { "cache-control": "no-store" } as const;
 const SYNC_PAGE = 500;
@@ -65,8 +66,6 @@ export interface ReceiverHooks {
 	/** Every authenticated hit — the only evidence a non-dialing half has that it is
 	 *  in step (vault's `lastPeerContactAt` lesson). */
 	onPeerContact?: (peerId: string) => void;
-	/** The "Sync now was pressed HERE" stamp the dialer polls. */
-	readRequest?: () => number | null;
 }
 
 export interface ReceiverOptions {
@@ -98,9 +97,27 @@ export interface ReceiverOptions {
 	 */
 	afterBatch?: (report: ApplyReport) => void | Promise<void>;
 	hooks?: ReceiverHooks;
+	/**
+	 * Mount `GET /signal` — the long-lived stream that replaced the dialer's
+	 * 20-second `GET /requested` probe. Omitted ⇒ the route does not exist, the
+	 * orch-companion idiom: nothing to probe, nothing to authenticate against.
+	 *
+	 * Call {@link SyncSignalHub.announce} after a local write on THIS half and the
+	 * dialing half reconciles within the round trip. See `./signal.ts`.
+	 */
+	signal?: SyncSignalHub;
 }
 
-/** Build the receiver: GET /info, GET /pull, POST /push, GET /requested. */
+/**
+ * Build the receiver: GET /info, GET /pull, POST /push.
+ *
+ * 🔴 There was a fourth route, `GET /requested`, and it is gone (2026-09-15). It
+ * served a single integer — "was Sync now pressed here?" — and existed only to be
+ * asked, every 20 seconds, by a dialer that otherwise had nothing to say. That made
+ * it **68 % of `vault`'s entire traffic**. A receiver with news now says so over
+ * {@link import("./signal")} instead of waiting to be asked; deleting the route is
+ * what stops a stale consumer from keeping the poll alive against a new build.
+ */
 export function createSyncReceiver(options: ReceiverOptions): Hono {
 	const { log, verifyToken } = options;
 	if ((options.applyOne === undefined) === (options.beginBatch === undefined)) {
@@ -135,9 +152,17 @@ export function createSyncReceiver(options: ReceiverOptions): Hono {
 		return c.json(body, 200, noStore);
 	});
 
-	api.get("/requested", (c) =>
-		c.json({ requestedAt: options.hooks?.readRequest?.() ?? null }, 200, noStore),
-	);
+	const signal = options.signal;
+	if (signal !== undefined) {
+		api.get("/signal", (c) =>
+			signalResponse(signal, {
+				// The catch-up frame: a client reconnecting after a sleep learns the
+				// current head without a round trip of its own.
+				initial: { head: log.head(), instanceId: log.instanceId() },
+				signal: c.req.raw.signal,
+			}),
+		);
+	}
 
 	api.get("/pull", (c) => {
 		const afterRaw = c.req.query("after");
@@ -302,15 +327,5 @@ export function createHttpRemote(options: {
 			if (!r.ok && r.status !== 409) throw new Error(`sync/push: ${r.status}`);
 			return await readJson<ApplyReport>(r, "sync/push");
 		},
-		async requestedAt() {
-			try {
-				const r = await request("/requested");
-				if (!r.ok) return null;
-				const body = await readJson<{ requestedAt?: unknown }>(r, "sync/requested");
-				return typeof body.requestedAt === "number" ? body.requestedAt : null;
-			} catch {
-				return null;
-			}
-		},
 	};
 }