@constructive-io/express-context 0.26.2 → 0.28.0

package/refusals.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRecordRefusalsSink = exports.RefusalRecorder = exports.DEFAULT_REFUSAL_MAX_KEYS = exports.DEFAULT_REFUSAL_FLUSH_JITTER_MS = exports.DEFAULT_REFUSAL_FLUSH_INTERVAL_MS = exports.refusalRows = exports.refusalOverflowKey = exports.refusalKeyOf = exports.sourceBucket = exports.OVERFLOW_ROUTE = exports.OVERFLOW_SOURCE = exports.UNKNOWN_SOURCE = exports.REFUSAL_REASONS = void 0;
+const logger_1 = require("@pgpmjs/logger");
+const pg_query_context_1 = require("pg-query-context");
+const usage_counter_1 = require("./usage-counter");
+const log = new logger_1.Logger('refusals');
+exports.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. */
+exports.UNKNOWN_SOURCE = 'unknown';
+/** `source_bucket` / `route_key` of the fold-down entry once the counter is full. */
+exports.OVERFLOW_SOURCE = 'overflow';
+exports.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`.
+ */
+const sourceBucket = (ip) => {
+    if (!ip)
+        return exports.UNKNOWN_SOURCE;
+    let addr = ip.trim();
+    if (addr.startsWith('[')) {
+        const end = addr.indexOf(']');
+        if (end === -1)
+            return exports.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 exports.UNKNOWN_SOURCE;
+        return `${octets[0]}.${octets[1]}.${octets[2]}.0/24`;
+    }
+    const groups = expandIpv6(addr);
+    if (!groups)
+        return exports.UNKNOWN_SOURCE;
+    return `${groups[0]}:${groups[1]}:${groups[2]}::/48`;
+};
+exports.sourceBucket = sourceBucket;
+/** 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;
+const refusalKeyOf = (key) => `${key.minuteBucket}\u0000${key.databaseId ?? ''}\u0000${key.lane}\u0000${key.reason}\u0000${key.routeKey}\u0000${key.sourceBucket}`;
+exports.refusalKeyOf = refusalKeyOf;
+/**
+ * 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.
+ */
+const refusalOverflowKey = (key) => ({
+    ...key,
+    routeKey: exports.OVERFLOW_ROUTE,
+    sourceBucket: exports.OVERFLOW_SOURCE
+});
+exports.refusalOverflowKey = refusalOverflowKey;
+/** Shape a drained batch for `record_refusals(jsonb)`. */
+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()
+}));
+exports.refusalRows = refusalRows;
+exports.DEFAULT_REFUSAL_FLUSH_INTERVAL_MS = 10_000;
+exports.DEFAULT_REFUSAL_FLUSH_JITTER_MS = 2_000;
+exports.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.
+ */
+class RefusalRecorder {
+    counter;
+    flusher;
+    recordFailures = 0;
+    constructor(opts) {
+        this.counter = new usage_counter_1.BoundedCounter({
+            maxKeys: opts.maxKeys ?? exports.DEFAULT_REFUSAL_MAX_KEYS,
+            keyOf: exports.refusalKeyOf,
+            overflowKey: exports.refusalOverflowKey
+        });
+        this.flusher = new usage_counter_1.CounterFlusher(this.counter, (entries) => opts.sink((0, exports.refusalRows)(entries)), {
+            intervalMs: opts.intervalMs ?? exports.DEFAULT_REFUSAL_FLUSH_INTERVAL_MS,
+            jitterMs: opts.jitterMs ?? exports.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: (0, exports.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()
+        };
+    }
+}
+exports.RefusalRecorder = RefusalRecorder;
+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.
+ */
+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 (0, pg_query_context_1.withPgClient)(opts.pool, claims, async (client) => {
+            await client.query(sql, [JSON.stringify(rows)]);
+        });
+    };
+};
+exports.createRecordRefusalsSink = createRecordRefusalsSink;

package/request-protection.d.ts

@@ -23,13 +23,13 @@ export interface RequestProtection {
     idleInTransactionTimeoutMs: number;
     /** `lock_timeout` for the request's transaction. */
     lockTimeoutMs: number;
-    /** In-flight requests allowed per tenant (not yet enforced). */
+    /** In-flight requests admitted per database, per replica. */
     maxConcurrentRequests: number;
-    /** How long a request may wait for a concurrency slot (not yet enforced). */
+    /** How long a request may wait for a concurrency slot. `0` never queues. */
     maxQueueWaitMs: number;
-    /** Sustained request rate per tenant (not yet enforced). */
+    /** Sustained request rate allowed one caller on one route. */
     rateLimitRpm: number;
-    /** Burst allowance above `rateLimitRpm` (not yet enforced). */
+    /** Burst allowance above `rateLimitRpm` within the same window. */
     rateLimitBurst: number;
     /** Deepest selection set accepted in an operation. */
     maxQueryDepth: number;

package/types.d.ts

@@ -152,6 +152,12 @@ export type ConstructiveAPIToken = {
     session_id?: string;
     access_level?: string;
     kind?: string;
+    /** Session lineage: the top of this session's exchange chain. */
+    root_session_id?: string;
+    /** Session lineage: the session this one was exchanged from, if any. */
+    parent_session_id?: string;
+    /** Caller-declared purpose recorded on the credential at exchange time. */
+    intent?: string;
     [key: string]: unknown;
 };
 export interface BillingConfig {

package/usage-counter.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 interface CounterEntry<K> {
+    key: K;
+    /** Sum of every `by` since this entry was created (or last drained). */
+    count: number;
+    /** Earliest `at` folded into this entry. */
+    firstAt: number;
+    /** Latest `at` folded into this entry. */
+    lastAt: number;
+}
+export interface BoundedCounterOptions<K> {
+    /**
+     * Distinct keys the counter will hold between drains. Past this, a *new* key
+     * is replaced by `overflowKey(key)` before it is counted; keys already
+     * present keep incrementing. Overflow keys are always admitted, so the true
+     * ceiling is `maxKeys` plus the number of distinct overflow keys the
+     * consumer's `overflowKey` can produce — keep that small.
+     */
+    maxKeys: number;
+    /** Serialise a key. Two keys with the same string share one entry. */
+    keyOf: (key: K) => string;
+    /**
+     * Where a key folds to once the map is full. Should collapse the
+     * high-cardinality parts of the key (a source address, a route) while
+     * keeping the attribution the consumer cannot afford to lose.
+     */
+    overflowKey: (key: K) => K;
+}
+export declare class BoundedCounter<K> {
+    private readonly entries;
+    private overflowedSinceDrain;
+    private readonly maxKeys;
+    private readonly keyOf;
+    private readonly overflowKey;
+    constructor(opts: BoundedCounterOptions<K>);
+    /** Distinct keys currently held. */
+    get size(): number;
+    /** Increments folded into an overflow key since the last drain. */
+    get overflowed(): number;
+    /**
+     * 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: K, by?: number, at?: number): void;
+    /**
+     * 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(): CounterEntry<K>[];
+}
+export type CounterSink<K> = (entries: CounterEntry<K>[]) => Promise<void>;
+export interface CounterFlusherOptions<K> {
+    /** Base time between flushes. */
+    intervalMs: number;
+    /**
+     * Uniform random offset added to each interval so replicas started together
+     * do not hit the store on the same tick.
+     */
+    jitterMs: number;
+    /**
+     * Called for every failed flush with the batch that was dropped. Every
+     * failure is reported — there is no "log once then go quiet" — and the
+     * request path is not involved, so making this loud is free.
+     */
+    onError: (err: unknown, dropped: CounterEntry<K>[]) => void;
+}
+export interface CounterFlusherStats {
+    /** Epoch ms of the last flush attempt that returned without error, or null. */
+    lastFlushAt: number | null;
+    /** Epoch ms of the last failed flush, or null. */
+    lastErrorAt: number | null;
+    /** Message of the last failed flush, or null. */
+    lastError: string | null;
+    /** Failed flushes since the last success. */
+    consecutiveFailures: number;
+    /** Entries handed to `onError` over the flusher's lifetime. */
+    droppedEntries: number;
+    /** Whether the timer is armed. */
+    running: boolean;
+}
+export declare class CounterFlusher<K> {
+    private readonly counter;
+    private readonly sink;
+    private readonly opts;
+    private timer;
+    private inFlight;
+    private running;
+    private lastFlushAt;
+    private lastErrorAt;
+    private lastError;
+    private consecutiveFailures;
+    private droppedEntries;
+    constructor(counter: BoundedCounter<K>, sink: CounterSink<K>, opts: CounterFlusherOptions<K>);
+    /** Arm the timer. Idempotent. The timer is unref'd so it never pins the process. */
+    start(): void;
+    /** Disarm the timer and flush whatever is pending. Idempotent. */
+    stop(): Promise<void>;
+    /**
+     * 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.
+     */
+    flush(): Promise<void>;
+    stats(): CounterFlusherStats;
+    private arm;
+    private flushOnce;
+}

package/usage-counter.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CounterFlusher = exports.BoundedCounter = void 0;
+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;
+    }
+}
+exports.BoundedCounter = BoundedCounter;
+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().
+            }
+        }
+    }
+}
+exports.CounterFlusher = CounterFlusher;