@constructive-io/express-context 0.26.1 → 0.27.0

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;