@constructive-io/express-context 0.26.1 → 0.27.0

package/esm/loaders/request-protection.js

@@ -0,0 +1,146 @@
+/**
+ * Request Protection Loader
+ *
+ * Reads the per-database bounds and the per-API overrides raw, then resolves
+ * them through the platform's own defaults and ceilings.
+ *
+ * Unlike the feature-flag loader next door this cannot `COALESCE` in SQL: an
+ * API override is lower-only, so the two scopes are combined with `LEAST` and
+ * then clamped in code, where the platform constants live.
+ *
+ * The columns are also selected by feature detection rather than by name
+ * alone. A serving cluster runs routing planes of several ages — the plane is
+ * a published package a tenant upgrades on its own schedule — and a plane that
+ * predates these columns must resolve to the platform defaults, not fail every
+ * request against it with `column ds.… does not exist`.
+ */
+import { resolveRequestProtection } from '../request-protection';
+import { createModuleLoader } from './create-loader';
+import { routingSchemaOf } from './types';
+// ─── SQL ────────────────────────────────────────────────────────────────────
+const PROTECTION_COLUMNS = [
+    'statement_timeout_ms',
+    'idle_in_transaction_timeout_ms',
+    'lock_timeout_ms',
+    'max_concurrent_requests',
+    'max_queue_wait_ms',
+    'rate_limit_rpm',
+    'rate_limit_burst',
+    'max_query_depth',
+    'max_query_cost',
+    'max_page_size',
+    'max_request_bytes',
+    'enable_introspection'
+];
+const availableColumnsSql = `
+  SELECT table_name, column_name
+  FROM information_schema.columns
+  WHERE table_schema = $1
+    AND table_name IN ('database_settings', 'api_settings')
+    AND column_name = ANY($2::text[])
+`;
+const requestProtectionSql = (schema, columns) => {
+    const select = PROTECTION_COLUMNS.flatMap((column) => [
+        columns.database.has(column) ? `ds.${column} AS db_${column}` : null,
+        columns.api.has(column) ? `aps.${column} AS api_${column}` : null
+    ])
+        .filter((expr) => expr !== null)
+        .join(',\n    ');
+    // The join is dropped when the plane carries no API-scope column, so a plane
+    // without an `api_settings` table at all is still readable.
+    const join = columns.api.size
+        ? `\n  LEFT JOIN "${schema}".api_settings aps ON ds.database_id = aps.database_id AND aps.api_id = $2`
+        : '';
+    return `
+  SELECT
+    ds.database_id${select ? `,\n    ${select}` : ''}
+  FROM "${schema}".database_settings ds${join}
+  WHERE ds.database_id = $1
+  LIMIT 1
+`;
+};
+/**
+ * The routing plane's shape changes only when it is redeployed, so it is read
+ * once per pool+schema. Keyed by the pool object so a test pool and a serving
+ * pool never share an answer.
+ */
+const columnCache = new WeakMap();
+const availableColumns = (pool, schema) => {
+    let bySchema = columnCache.get(pool);
+    if (!bySchema) {
+        bySchema = new Map();
+        columnCache.set(pool, bySchema);
+    }
+    const cached = bySchema.get(schema);
+    if (cached)
+        return cached;
+    const pending = pool
+        .query(availableColumnsSql, [
+        schema,
+        [...PROTECTION_COLUMNS]
+    ])
+        .then((result) => {
+        const columns = { database: new Set(), api: new Set() };
+        for (const { table_name, column_name } of result.rows) {
+            if (table_name === 'database_settings')
+                columns.database.add(column_name);
+            else
+                columns.api.add(column_name);
+        }
+        return columns;
+    })
+        .catch((e) => {
+        // A failed probe is not an answer: drop it so the next request retries
+        // rather than caching "this plane has no protection columns" forever.
+        bySchema.delete(schema);
+        throw e;
+    });
+    bySchema.set(schema, pending);
+    return pending;
+};
+/** Test seam: forget what a pool's routing plane looked like. */
+export const forgetProtectionColumns = (pool) => {
+    columnCache.delete(pool);
+};
+/**
+ * `bigint` columns arrive as strings from node-postgres (pg returns int8 as
+ * text to avoid the 2^53 cliff), so every numeric bound is normalized here
+ * rather than trusted to already be a number.
+ */
+const num = (value) => {
+    if (value === null || value === undefined)
+        return null;
+    const parsed = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+};
+const bool = (value) => value === null || value === undefined ? null : Boolean(value);
+const scopeOf = (row, prefix) => ({
+    statementTimeoutMs: num(row[`${prefix}_statement_timeout_ms`]),
+    idleInTransactionTimeoutMs: num(row[`${prefix}_idle_in_transaction_timeout_ms`]),
+    lockTimeoutMs: num(row[`${prefix}_lock_timeout_ms`]),
+    maxConcurrentRequests: num(row[`${prefix}_max_concurrent_requests`]),
+    maxQueueWaitMs: num(row[`${prefix}_max_queue_wait_ms`]),
+    rateLimitRpm: num(row[`${prefix}_rate_limit_rpm`]),
+    rateLimitBurst: num(row[`${prefix}_rate_limit_burst`]),
+    maxQueryDepth: num(row[`${prefix}_max_query_depth`]),
+    maxQueryCost: num(row[`${prefix}_max_query_cost`]),
+    maxPageSize: num(row[`${prefix}_max_page_size`]),
+    maxRequestBytes: num(row[`${prefix}_max_request_bytes`]),
+    enableIntrospection: bool(row[`${prefix}_enable_introspection`])
+});
+// ─── Loader ─────────────────────────────────────────────────────────────────
+export const requestProtectionLoader = createModuleLoader({
+    name: 'requestProtection',
+    ttlMs: 5 * 60_000,
+    async resolve(ctx) {
+        const { routingPool, databaseId, apiId } = ctx;
+        const schema = routingSchemaOf(ctx);
+        const columns = await availableColumns(routingPool, schema);
+        const params = columns.api.size ? [databaseId, apiId ?? null] : [databaseId];
+        const result = await routingPool.query(requestProtectionSql(schema, columns), params);
+        const row = result.rows[0];
+        if (!row)
+            return undefined;
+        return resolveRequestProtection(scopeOf(row, 'db'), scopeOf(row, 'api'));
+    }
+});

package/esm/refusals.js

@@ -0,0 +1,214 @@
+/**
+ * refusals — the refusal-observability instantiation of `usage-counter`.
+ *
+ * Every refusal the platform issues (a 429 from admission control, a 413 for an
+ * oversized body, a document-gate rejection, a gateway's route or IP window)
+ * is one `RefusalRecorder.record(...)` call at the point the response is
+ * written. That call is an in-memory increment and nothing else — no promise,
+ * no pool, no allocation beyond the key — so a flood costs a counter bump and
+ * refusing traffic keeps working when the recorder's store is down.
+ *
+ * Counts are keyed by `(minute, database, lane, reason, route, source /24)`,
+ * which is exactly the set of questions the platform table answers: which
+ * tenant, why, on which route, from which network, since when. Raw addresses
+ * are never part of the key; `sourceBucket` truncates to a /24 (v4) or /48
+ * (v6) before anything is counted.
+ *
+ * The flush writes the drained batch as one `record_refusals(jsonb)` call —
+ * one statement per window regardless of how many keys it holds.
+ *
+ * @module refusals
+ */
+import { Logger } from '@pgpmjs/logger';
+import { withPgClient } from 'pg-query-context';
+import { BoundedCounter, CounterFlusher } from './usage-counter';
+const log = new Logger('refusals');
+export const REFUSAL_REASONS = [
+    'rate_limited',
+    'concurrency_saturated',
+    'queue_timeout',
+    'request_too_large',
+    'query_too_deep',
+    'query_too_costly',
+    'page_size_too_large',
+    'anonymous_not_callable',
+    'route_rate_limited'
+];
+/** `source_bucket` when the lane could not resolve an address. */
+export const UNKNOWN_SOURCE = 'unknown';
+/** `source_bucket` / `route_key` of the fold-down entry once the counter is full. */
+export const OVERFLOW_SOURCE = 'overflow';
+export const OVERFLOW_ROUTE = '*';
+const MINUTE_MS = 60_000;
+const IPV4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+/**
+ * Reduce a client address to a network prefix: `/24` for IPv4, `/48` for IPv6.
+ * Enough to tell "one network hammering an anonymous route" from "the tenant's
+ * own users"; not enough to be a person. Anything unparseable is `unknown`.
+ */
+export const sourceBucket = (ip) => {
+    if (!ip)
+        return UNKNOWN_SOURCE;
+    let addr = ip.trim();
+    if (addr.startsWith('[')) {
+        const end = addr.indexOf(']');
+        if (end === -1)
+            return UNKNOWN_SOURCE;
+        addr = addr.slice(1, end);
+    }
+    const zone = addr.indexOf('%');
+    if (zone !== -1)
+        addr = addr.slice(0, zone);
+    if (addr.toLowerCase().startsWith('::ffff:')) {
+        const mapped = addr.slice('::ffff:'.length);
+        if (IPV4.test(mapped))
+            addr = mapped;
+    }
+    const v4 = IPV4.exec(addr);
+    if (v4) {
+        const octets = v4.slice(1, 5).map(Number);
+        if (octets.some((o) => o > 255))
+            return UNKNOWN_SOURCE;
+        return `${octets[0]}.${octets[1]}.${octets[2]}.0/24`;
+    }
+    const groups = expandIpv6(addr);
+    if (!groups)
+        return UNKNOWN_SOURCE;
+    return `${groups[0]}:${groups[1]}:${groups[2]}::/48`;
+};
+/** The eight hextets of an IPv6 address, or null when it does not parse. */
+const expandIpv6 = (addr) => {
+    if (!/^[0-9a-fA-F:]+$/.test(addr) || addr.indexOf(':::') !== -1)
+        return null;
+    const halves = addr.split('::');
+    if (halves.length > 2)
+        return null;
+    const head = halves[0] ? halves[0].split(':') : [];
+    const tail = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+    const missing = 8 - head.length - tail.length;
+    if (halves.length === 2 ? missing < 1 : missing !== 0)
+        return null;
+    const groups = [...head, ...Array(missing).fill('0'), ...tail];
+    if (groups.some((g) => g.length === 0 || g.length > 4))
+        return null;
+    return groups.map((g) => parseInt(g, 16).toString(16));
+};
+const minuteOf = (at) => Math.floor(at / MINUTE_MS) * MINUTE_MS;
+export const refusalKeyOf = (key) => `${key.minuteBucket}\u0000${key.databaseId ?? ''}\u0000${key.lane}\u0000${key.reason}\u0000${key.routeKey}\u0000${key.sourceBucket}`;
+/**
+ * Where a key folds to once the counter is full: same minute, tenant, lane and
+ * reason; route and source collapsed. A source-spraying flood therefore costs
+ * `maxKeys` entries plus one per `(database, lane, reason)`, the tenant/reason
+ * attribution is never lost, and the presence of an `overflow` row is itself
+ * the signal that a spray happened.
+ */
+export const refusalOverflowKey = (key) => ({
+    ...key,
+    routeKey: OVERFLOW_ROUTE,
+    sourceBucket: OVERFLOW_SOURCE
+});
+/** Shape a drained batch for `record_refusals(jsonb)`. */
+export const refusalRows = (entries) => entries.map(({ key, count, firstAt, lastAt }) => ({
+    minute_bucket: new Date(key.minuteBucket).toISOString(),
+    database_id: key.databaseId,
+    lane: key.lane,
+    reason: key.reason,
+    route_key: key.routeKey,
+    source_bucket: key.sourceBucket,
+    count,
+    first_seen_at: new Date(firstAt).toISOString(),
+    last_seen_at: new Date(lastAt).toISOString()
+}));
+export const DEFAULT_REFUSAL_FLUSH_INTERVAL_MS = 10_000;
+export const DEFAULT_REFUSAL_FLUSH_JITTER_MS = 2_000;
+export const DEFAULT_REFUSAL_MAX_KEYS = 2_000;
+const defaultOnError = (err, dropped) => {
+    const refusals = dropped.reduce((sum, e) => sum + e.count, 0);
+    const message = err instanceof Error ? err.message : String(err);
+    log.error(`[refusals] flush failed; dropped ${refusals} refusals across ${dropped.length} keys: ${message}`);
+};
+/**
+ * `BoundedCounter<RefusalKey>` + `CounterFlusher` + a `record_refusals` sink.
+ * Construct one per process, `start()` it, `record()` from every refusal site,
+ * `stop()` on shutdown.
+ */
+export class RefusalRecorder {
+    counter;
+    flusher;
+    recordFailures = 0;
+    constructor(opts) {
+        this.counter = new BoundedCounter({
+            maxKeys: opts.maxKeys ?? DEFAULT_REFUSAL_MAX_KEYS,
+            keyOf: refusalKeyOf,
+            overflowKey: refusalOverflowKey
+        });
+        this.flusher = new CounterFlusher(this.counter, (entries) => opts.sink(refusalRows(entries)), {
+            intervalMs: opts.intervalMs ?? DEFAULT_REFUSAL_FLUSH_INTERVAL_MS,
+            jitterMs: opts.jitterMs ?? DEFAULT_REFUSAL_FLUSH_JITTER_MS,
+            onError: opts.onError ?? defaultOnError
+        });
+    }
+    /**
+     * Count one refusal. Synchronous and never throws: the request that is
+     * being refused must finish being refused whatever state the recorder is in.
+     */
+    record(refusal) {
+        try {
+            const at = refusal.at ?? Date.now();
+            this.counter.increment({
+                minuteBucket: minuteOf(at),
+                databaseId: refusal.databaseId,
+                lane: refusal.lane,
+                reason: refusal.reason,
+                routeKey: refusal.routeKey,
+                sourceBucket: sourceBucket(refusal.sourceIp)
+            }, 1, at);
+        }
+        catch (err) {
+            this.recordFailures += 1;
+            const message = err instanceof Error ? err.message : String(err);
+            log.error(`[refusals] record failed (refusal still served): ${message}`);
+        }
+    }
+    start() {
+        this.flusher.start();
+    }
+    /** Final flush, then stop. */
+    stop() {
+        return this.flusher.stop();
+    }
+    /** Drain and write now; a sink failure is reported, never thrown. */
+    flush() {
+        return this.flusher.flush();
+    }
+    stats() {
+        return {
+            keys: this.counter.size,
+            overflowed: this.counter.overflowed,
+            recordFailures: this.recordFailures,
+            flusher: this.flusher.stats()
+        };
+    }
+}
+const FUNCTION_NAME = /^[a-z_][a-z0-9_]*\.[a-z_][a-z0-9_]*$/;
+/**
+ * A sink that writes a batch as one `record_refusals(jsonb)` call inside a
+ * transaction carrying the caller's claims. Claims are resolved per flush so a
+ * pool that was unreachable at startup does not leave the recorder wedged.
+ */
+export const createRecordRefusalsSink = (opts) => {
+    const fn = opts.functionName ?? 'constructive_usage_private.record_refusals';
+    if (!FUNCTION_NAME.test(fn)) {
+        throw new Error(`createRecordRefusalsSink: invalid function name ${JSON.stringify(fn)}`);
+    }
+    const [schema, name] = fn.split('.');
+    const sql = `SELECT "${schema}"."${name}"($1::jsonb) AS recorded`;
+    return async (rows) => {
+        if (rows.length === 0)
+            return;
+        const claims = await opts.claims();
+        await withPgClient(opts.pool, claims, async (client) => {
+            await client.query(sql, [JSON.stringify(rows)]);
+        });
+    };
+};

package/esm/request-protection.js

@@ -0,0 +1,106 @@
+/**
+ * request-protection — platform bounds for the per-request protection settings.
+ *
+ * `database_settings` / `api_settings` carry a tenant's *preferences*; this
+ * module owns the numbers the platform will actually honour. The platform
+ * default and the hard ceiling are code constants rather than rows, so a
+ * tenant can never widen a bound by writing metadata: a setting is only ever
+ * read as a request to be *stricter* than the platform is.
+ *
+ *   effective = clamp(LEAST(api_override, database_setting) ?? default, floor, max)
+ *
+ * `LEAST` (not `COALESCE`) is what makes an API override lower-only: an API
+ * that asks for a 60s statement timeout under a database that says 10s gets
+ * 10s. The floor exists so a tenant cannot write a value that makes its own
+ * API unusable (a 0ms statement timeout), and the ceiling so it cannot raise
+ * one past what the shared cluster will absorb.
+ */
+// ─── Platform bounds ────────────────────────────────────────────────────────
+/**
+ * The platform's own numbers. Deliberately constants: a ceiling stored next to
+ * the value it caps is a ceiling a tenant can edit.
+ */
+export const PROTECTION_BOUNDS = {
+    statementTimeoutMs: { default: 30_000, floor: 1_000, max: 120_000 },
+    idleInTransactionTimeoutMs: { default: 60_000, floor: 1_000, max: 300_000 },
+    lockTimeoutMs: { default: 5_000, floor: 100, max: 60_000 },
+    maxConcurrentRequests: { default: 50, floor: 1, max: 500 },
+    maxQueueWaitMs: { default: 5_000, floor: 0, max: 60_000 },
+    rateLimitRpm: { default: 600, floor: 1, max: 60_000 },
+    rateLimitBurst: { default: 60, floor: 1, max: 10_000 },
+    maxQueryDepth: { default: 12, floor: 1, max: 50 },
+    // Cost is measured in rows a document can pull (see ASSUMED_PAGE_SIZE), so
+    // the default has to leave room for the nesting Graphile encourages while
+    // still refusing the millions-of-rows shapes.
+    maxQueryCost: { default: 1_000_000, floor: 100, max: 100_000_000 },
+    maxPageSize: { default: 1_000, floor: 1, max: 10_000 },
+    maxRequestBytes: { default: 1_000_000, floor: 1_024, max: 10_000_000 }
+};
+/**
+ * What a connection with no `first`/`last` is charged.
+ *
+ * Such a field is unbounded in principle, so charging it the tenant's
+ * `maxPageSize` would make a large ceiling self-defeating: raising the page
+ * size a client *may* ask for would shrink the query it can write. A fixed
+ * estimate keeps the two bounds independent.
+ */
+export const ASSUMED_PAGE_SIZE = 100;
+/**
+ * Introspection stays on until metadata says otherwise, and `platformAllows`
+ * is the kill switch that takes it away cluster-wide regardless.
+ *
+ * The platform default is permissive here where the metadata default is not
+ * (`database_settings.enable_introspection` is `NOT NULL DEFAULT false`) on
+ * purpose: this value applies to a database that has expressed *no*
+ * preference — typically one whose routing plane predates the column — and
+ * silently disabling introspection for it would break GraphiQL and codegen for
+ * every tenant the moment this code deployed, without anyone opting in.
+ */
+export const INTROSPECTION_BOUND = {
+    default: true,
+    platformAllows: true
+};
+/** What a database with no settings row gets. */
+export const DEFAULT_REQUEST_PROTECTION = resolveDefaults();
+function resolveDefaults() {
+    const numeric = Object.fromEntries(Object.entries(PROTECTION_BOUNDS).map(([key, bound]) => [key, bound.default]));
+    return { ...numeric, enableIntrospection: INTROSPECTION_BOUND.default };
+}
+// ─── Resolution ─────────────────────────────────────────────────────────────
+const clamp = (value, bound) => Math.min(Math.max(value, bound.floor), bound.max);
+/** The stricter of two preferences, ignoring the scopes that expressed none. */
+const strictest = (a, b) => {
+    const values = [a, b].filter((v) => typeof v === 'number' && Number.isFinite(v));
+    return values.length > 0 ? Math.min(...values) : null;
+};
+/**
+ * Resolve the bounds a request runs under.
+ *
+ * @param database - the `database_settings` row for the tenant, if any
+ * @param api - the `api_settings` overrides for the API the request arrived on
+ */
+export function resolveRequestProtection(database, api) {
+    const resolved = {};
+    for (const [name, bound] of Object.entries(PROTECTION_BOUNDS)) {
+        const preferred = strictest(database?.[name], api?.[name]);
+        resolved[name] = clamp(preferred ?? bound.default, bound);
+    }
+    // Lower-only applies to the flag too: an API may switch introspection off
+    // for itself, never back on for a database that turned it off, and the
+    // platform switch can only ever take it away.
+    const enableIntrospection = (database?.enableIntrospection ?? INTROSPECTION_BOUND.default) &&
+        (api?.enableIntrospection ?? true) &&
+        INTROSPECTION_BOUND.platformAllows;
+    return { ...resolved, enableIntrospection };
+}
+/**
+ * The timeout GUCs as `SET LOCAL` pairs, for merging into a request's
+ * pgSettings. PostgreSQL reads a bare integer for all three as milliseconds.
+ */
+export function protectionPgSettings(protection) {
+    return {
+        statement_timeout: String(protection.statementTimeoutMs),
+        idle_in_transaction_session_timeout: String(protection.idleInTransactionTimeoutMs),
+        lock_timeout: String(protection.lockTimeoutMs)
+    };
+}

package/esm/usage-counter.js

@@ -0,0 +1,190 @@
+/**
+ * usage-counter — the shared in-memory count + batch-flush mechanism.
+ *
+ * Two classes, neither of which knows what is being counted:
+ *
+ *   - `BoundedCounter<K>` is the map. Consumers pass the key type, how a key
+ *     serialises (`keyOf`) and where a key folds to once the map is full
+ *     (`overflowKey`). `increment` is O(1), synchronous and never throws, so a
+ *     request path can call it while refusing traffic without ever waiting on,
+ *     or being affected by, whatever eventually stores the counts.
+ *   - `CounterFlusher<K>` is the loop. It drains the counter on a jittered
+ *     interval, hands the batch to a `sink`, and owns the failure policy: a
+ *     batch the sink cannot write is reported through `onError` *and dropped*.
+ *     Re-queuing under a broken sink is how a bounded counter becomes an
+ *     unbounded one, and the counter is already accumulating the next window.
+ *
+ * Refusal observability instantiates these with a refusal key and a sink that
+ * calls `constructive_usage_private.record_refusals` (see `refusals.ts`); the
+ * page/request metering lane instantiates the same two classes with its own
+ * `K`, `keyOf`, `overflowKey`, bound, interval and sink. The seam is the
+ * constructor arguments — nothing in this file is specific to either.
+ *
+ * Counters live in process memory only. A crash loses at most one interval's
+ * worth of counts; `stop()` flushes on graceful shutdown. That is deliberate:
+ * the alternative is a durable write per event, which is the thing counting in
+ * memory exists to avoid.
+ *
+ * @module usage-counter
+ */
+export class BoundedCounter {
+    entries = new Map();
+    overflowedSinceDrain = 0;
+    maxKeys;
+    keyOf;
+    overflowKey;
+    constructor(opts) {
+        if (!Number.isInteger(opts.maxKeys) || opts.maxKeys < 1) {
+            throw new Error(`BoundedCounter: maxKeys must be a positive integer, got ${opts.maxKeys}`);
+        }
+        this.maxKeys = opts.maxKeys;
+        this.keyOf = opts.keyOf;
+        this.overflowKey = opts.overflowKey;
+    }
+    /** Distinct keys currently held. */
+    get size() {
+        return this.entries.size;
+    }
+    /** Increments folded into an overflow key since the last drain. */
+    get overflowed() {
+        return this.overflowedSinceDrain;
+    }
+    /**
+     * Add `by` to `key`. Synchronous, O(1), never throws for a well-formed
+     * `keyOf`/`overflowKey`; the caller's request path must not depend on it in
+     * any other way.
+     */
+    increment(key, by = 1, at = Date.now()) {
+        let id = this.keyOf(key);
+        let entry = this.entries.get(id);
+        if (!entry && this.entries.size >= this.maxKeys) {
+            key = this.overflowKey(key);
+            id = this.keyOf(key);
+            entry = this.entries.get(id);
+            this.overflowedSinceDrain += by;
+        }
+        if (!entry) {
+            this.entries.set(id, { key, count: by, firstAt: at, lastAt: at });
+            return;
+        }
+        entry.count += by;
+        if (at < entry.firstAt)
+            entry.firstAt = at;
+        if (at > entry.lastAt)
+            entry.lastAt = at;
+    }
+    /**
+     * Return every entry and start a fresh window. The returned array is the
+     * only reference to those entries, so a slow sink never contends with the
+     * hot path.
+     */
+    drain() {
+        const drained = Array.from(this.entries.values());
+        this.entries.clear();
+        this.overflowedSinceDrain = 0;
+        return drained;
+    }
+}
+export class CounterFlusher {
+    counter;
+    sink;
+    opts;
+    timer = null;
+    inFlight = null;
+    running = false;
+    lastFlushAt = null;
+    lastErrorAt = null;
+    lastError = null;
+    consecutiveFailures = 0;
+    droppedEntries = 0;
+    constructor(counter, sink, opts) {
+        this.counter = counter;
+        this.sink = sink;
+        this.opts = opts;
+        if (!(opts.intervalMs > 0)) {
+            throw new Error(`CounterFlusher: intervalMs must be positive, got ${opts.intervalMs}`);
+        }
+        if (!(opts.jitterMs >= 0)) {
+            throw new Error(`CounterFlusher: jitterMs must be non-negative, got ${opts.jitterMs}`);
+        }
+    }
+    /** Arm the timer. Idempotent. The timer is unref'd so it never pins the process. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.arm();
+    }
+    /** Disarm the timer and flush whatever is pending. Idempotent. */
+    async stop() {
+        this.running = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        await this.flush();
+    }
+    /**
+     * Drain and write now. Never rejects: a sink failure goes to `onError`. If a
+     * flush is already in flight the call waits for it and then runs its own, so
+     * two overlapping timers cannot send batches out of order.
+     */
+    async flush() {
+        if (this.inFlight)
+            await this.inFlight;
+        const run = this.flushOnce();
+        this.inFlight = run;
+        try {
+            await run;
+        }
+        finally {
+            if (this.inFlight === run)
+                this.inFlight = null;
+        }
+    }
+    stats() {
+        return {
+            lastFlushAt: this.lastFlushAt,
+            lastErrorAt: this.lastErrorAt,
+            lastError: this.lastError,
+            consecutiveFailures: this.consecutiveFailures,
+            droppedEntries: this.droppedEntries,
+            running: this.running
+        };
+    }
+    arm() {
+        const delay = this.opts.intervalMs + Math.floor(Math.random() * (this.opts.jitterMs + 1));
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.flush().finally(() => {
+                if (this.running)
+                    this.arm();
+            });
+        }, delay);
+        this.timer.unref?.();
+    }
+    async flushOnce() {
+        const entries = this.counter.drain();
+        if (entries.length === 0)
+            return;
+        try {
+            await this.sink(entries);
+            this.lastFlushAt = Date.now();
+            this.consecutiveFailures = 0;
+        }
+        catch (err) {
+            this.lastErrorAt = Date.now();
+            this.lastError = err instanceof Error ? err.message : String(err);
+            this.consecutiveFailures += 1;
+            this.droppedEntries += entries.length;
+            // The batch is gone whether or not onError itself misbehaves; a
+            // reporter that throws must not turn one lost window into a stuck loop.
+            try {
+                this.opts.onError(err, entries);
+            }
+            catch {
+                // Fire-and-forget by design: the failure is already recorded in stats().
+            }
+        }
+    }
+}

package/index.d.ts

@@ -40,9 +40,17 @@ export { createBillingClient } from './billing-client';
 export type { PgSettingsInput } from './pg-settings';
 export { buildPgSettings } from './pg-settings';
 export { withPgClient } from './pg-client';
+export type { NumericProtectionKey, ProtectionBound, RequestProtection, RequestProtectionInput, } from './request-protection';
+export { ASSUMED_PAGE_SIZE, DEFAULT_REQUEST_PROTECTION, INTROSPECTION_BOUND, PROTECTION_BOUNDS, protectionPgSettings, resolveRequestProtection, } from './request-protection';
+export type { AdmissionLease, AdmissionRefusal, AdmissionRequest } from './admission';
+export { clientIpFrom, ConcurrencyLimiter, RateWindow, trustedProxyHops } from './admission';
+export type { RecordRefusalsSinkOptions, Refusal, RefusalKey, RefusalLane, RefusalReason, RefusalRecorderOptions, RefusalRecorderStats, RefusalRow, RefusalSink } from './refusals';
+export { createRecordRefusalsSink, DEFAULT_REFUSAL_FLUSH_INTERVAL_MS, DEFAULT_REFUSAL_FLUSH_JITTER_MS, DEFAULT_REFUSAL_MAX_KEYS, OVERFLOW_ROUTE, OVERFLOW_SOURCE, REFUSAL_REASONS, refusalKeyOf, refusalOverflowKey, RefusalRecorder, refusalRows, sourceBucket, UNKNOWN_SOURCE } from './refusals';
+export type { BoundedCounterOptions, CounterEntry, CounterFlusherOptions, CounterFlusherStats, CounterSink } from './usage-counter';
+export { BoundedCounter, CounterFlusher } from './usage-counter';
 export { requestIdMiddleware } from './request-id';
 export type { ContextMiddlewareOptions } from './context';
 export { buildContext, createContextMiddleware } from './context';
 export type { CreateLoaderOptions, LoaderContext, LoaderRegistry, ModuleLoader, } from './loaders';
-export { agentChatLoader, authSettingsLoader, authSurfaceLoader, billingLoader, computeLoader, corsLoader, createDefaultRegistry, createLoaderRegistry, createModuleLoader, databaseSettingsLoader, identityProvidersLoader, inferenceLogLoader, llmLoader, pubkeyLoader, requireDatabaseId, requireIdentityProvider, rlsLoader, webauthnLoader, } from './loaders';
+export { agentChatLoader, authSettingsLoader, authSurfaceLoader, billingLoader, computeLoader, corsLoader, createDefaultRegistry, createLoaderRegistry, createModuleLoader, databaseSettingsLoader, identityProvidersLoader, inferenceLogLoader, llmLoader, pubkeyLoader, requestProtectionLoader, requireDatabaseId, requireIdentityProvider, rlsLoader, webauthnLoader, } from './loaders';
 import './types';