@aforoai/metering 1.1.2 → 2.0.0

package/dist/cjs/transport-core/core.js

@@ -0,0 +1,1047 @@
+"use strict";
+/**
+ * Aforo Node transport core (wave 5, contract v2).
+ *
+ * THE ONE PLACE TO EDIT. This file lives in `node/src/transport-core/` and is
+ * copied, byte for byte, into every Node variant (`node-ws`, `node-mqtt`,
+ * `node-grpc`, `node-graphql`, `node-mcp`, `node-agent`, `mcp-proxy`) by
+ * `scripts/sync-transport.sh node`. Edit it here, then run the sync; CI fails
+ * when a copy differs. Normative behaviour: `contract/TRANSPORT-SPEC.md`.
+ *
+ * Self-contained on purpose: no imports (not even relative ones, so every
+ * module format and test runner that receives the copy can load it), only
+ * Node built-ins reached through globals (`fetch`, `AbortSignal`, `Buffer`,
+ * timers). Target ES2020.
+ *
+ * What it does, per client:
+ *   - one bounded FIFO queue (evict-oldest, reported as 'overflow');
+ *   - one long-lived flusher: `enqueue()` never sends, it only wakes the
+ *     flusher at `flushCount`; `flush()` hands work to the flusher and waits;
+ *     at most one ingest request is ever in flight;
+ *   - full-jitter retries, Retry-After in both forms (capped), a total
+ *     deadline per request that also covers reading the response body;
+ *   - redirects are never followed (the API key must not reach another
+ *     host): a 3xx keeps the batch queued and opens the breaker;
+ *   - each event is serialized once, at enqueue: an event JSON cannot
+ *     represent (BigInt, a cycle, NaN) is dropped there as 'invalid';
+ *   - 413 splits the batch, 2xx per-event `retryable` failures are requeued,
+ *     other 4xx are dropped as 'rejected';
+ *   - after the last retry (or on 401/403) the batch goes back to the front
+ *     of the queue with its keys and a breaker pauses the flusher;
+ *   - `shutdown()` drains until a deadline and reports leftovers as
+ *     'shutdown'; `enqueue()` after close reports 'closed';
+ *   - no signal handlers: a process `beforeExit` hook flushes within the
+ *     shutdown deadline. Apps call `shutdown()` from their own SIGTERM handler;
+ *   - `onAccepted(body, events)` sees the parsed 2xx body of every accepted
+ *     batch (for fields such as `killedSessionIds`); `onError` receives a
+ *     `CoreTransportError` whose `kind` says what happened.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransportCore = exports.defaultSleep = exports.CORE_DEFAULTS = exports.CoreTransportError = void 0;
+exports.checkBaseUrl = checkBaseUrl;
+exports.fullJitter = fullJitter;
+exports.parseRetryAfter = parseRetryAfter;
+/**
+ * The error every onError report receives. `message` is for people; branch on
+ * `kind`. `events` are the events concerned: the queued ones for outage/auth,
+ * the dropped ones otherwise (empty when the ingestor did not name them).
+ */
+class CoreTransportError extends Error {
+    constructor(kind, message, events, options = {}) {
+        super(message);
+        this.name = 'CoreTransportError';
+        this.kind = kind;
+        this.events = events.slice();
+        if (options.status !== undefined)
+            this.status = options.status;
+        this.willRetry = kind === 'outage' || kind === 'auth';
+    }
+}
+exports.CoreTransportError = CoreTransportError;
+exports.CORE_DEFAULTS = Object.freeze({
+    path: '/v1/ingest/batch',
+    flushCount: 500,
+    maxBatchEvents: 1000,
+    flushIntervalMs: 5000,
+    maxQueueSize: 10000,
+    maxRetries: 3,
+    retryBaseMs: 500,
+    retryMaxDelayMs: 30000,
+    retryAfterMaxMs: 60000,
+    breakerInitialMs: 5000,
+    breakerMaxMs: 300000,
+    timeoutMs: 10000,
+    shutdownTimeoutMs: 5000,
+    targetRequestBodyBytes: 4 * 1024 * 1024,
+});
+const RETRY_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+const AUTH_STATUSES = new Set([401, 403]);
+/** Smallest breaker cooldown, so a 401/3xx loop can never spin. */
+const BREAKER_FLOOR_MS = 250;
+/** A 3xx (or the opaque-redirect status 0 some fetch implementations return for redirect: 'manual'). */
+function isRedirect(status) {
+    return status === 0 || (status >= 300 && status < 400);
+}
+/** Host of a Location header, for the log line. Never the full URL (it could carry a query string). */
+function redirectTarget(location, base) {
+    if (!location)
+        return 'no Location header';
+    try {
+        return new URL(location, base).host || 'an unknown host';
+    }
+    catch {
+        return 'an unparseable Location header';
+    }
+}
+/**
+ * JSON for one event, or a reason why it has none. BigInt and cycles make
+ * JSON.stringify throw; NaN and Infinity would silently become null, which
+ * the ingestor would then reject or misread, so they are refused here too.
+ */
+function serializeEvent(event) {
+    try {
+        const json = JSON.stringify(event, (_key, value) => {
+            if (typeof value === 'number' && !Number.isFinite(value)) {
+                throw new TypeError(`a number field is ${String(value)}, which JSON cannot represent`);
+            }
+            return value;
+        });
+        if (typeof json !== 'string')
+            return { error: 'the event is not a JSON object' };
+        return { json };
+    }
+    catch (err) {
+        const e = err;
+        return { error: `the event cannot be serialized to JSON (${String(e?.message ?? err).slice(0, 200)})` };
+    }
+}
+/** Resolves with `promise`, or rejects as soon as `signal` aborts (even if `promise` never settles). */
+function untilAborted(promise, signal) {
+    if (signal.aborted) {
+        promise.catch(() => undefined);
+        return Promise.reject(signal.reason ?? new Error('aborted'));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason ?? new Error('aborted'));
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((v) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(v);
+        }, (e) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(e);
+        });
+    });
+}
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+const INSPECT = Symbol.for('nodejs.util.inspect.custom');
+/**
+ * Throws when `baseUrl` is not https:// (plain http only for a local host or
+ * with `allowInsecureHttp`). Returns the URL without trailing slashes.
+ */
+function checkBaseUrl(baseUrl, allowInsecureHttp = false) {
+    if (typeof baseUrl !== 'string' || !baseUrl.trim()) {
+        throw new Error('Aforo ingestor URL is required (for example https://api.aforo.ai)');
+    }
+    let parsed;
+    try {
+        parsed = new URL(baseUrl.trim());
+    }
+    catch {
+        throw new Error(`Aforo ingestor URL is not a valid URL: ${JSON.stringify(baseUrl.slice(0, 200))}`);
+    }
+    if (parsed.username || parsed.password) {
+        throw new Error('Aforo ingestor URL must not contain credentials; pass the API key as apiKey');
+    }
+    if (parsed.protocol === 'http:') {
+        if (!allowInsecureHttp && !LOCAL_HOSTS.has(parsed.hostname)) {
+            throw new Error(`Aforo ingestor URL must use https:// (got http://${parsed.host}). Plain http is allowed only for ` +
+                'localhost, 127.0.0.1 and ::1, or with allowInsecureHttp: true.');
+        }
+    }
+    else if (parsed.protocol !== 'https:') {
+        throw new Error(`Aforo ingestor URL must use https:// (got ${parsed.protocol}//)`);
+    }
+    return baseUrl.trim().replace(/\/+$/, '');
+}
+/** Full-jitter backoff: random(0, min(maxDelay, base * 2^attempt)). */
+function fullJitter(attempt, baseMs, maxMs, random) {
+    const ceiling = Math.min(maxMs, baseMs * Math.pow(2, Math.max(0, attempt)));
+    return Math.floor(clamp01(random()) * ceiling);
+}
+/**
+ * Retry-After in ms: delta-seconds or an HTTP-date, capped at `maxMs`.
+ * Undefined when absent or unreadable (the caller then uses its own delay).
+ */
+function parseRetryAfter(value, now, maxMs) {
+    if (value === null || value === undefined)
+        return undefined;
+    const text = String(value).trim();
+    if (!text)
+        return undefined;
+    if (/^\d+(\.\d+)?$/.test(text)) {
+        return Math.min(Math.round(Number(text) * 1000), maxMs);
+    }
+    const at = Date.parse(text);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.min(Math.max(0, at - now), maxMs);
+}
+/** Sleep on an unref'd timer; resolves early when `signal` aborts. */
+const defaultSleep = (ms, signal) => new Promise((resolve) => {
+    if (ms <= 0 || signal?.aborted) {
+        resolve();
+        return;
+    }
+    const done = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', done);
+        resolve();
+    };
+    const timer = setTimeout(done, ms);
+    unref(timer);
+    signal?.addEventListener('abort', done, { once: true });
+});
+exports.defaultSleep = defaultSleep;
+function clamp01(n) {
+    return Number.isFinite(n) ? Math.min(Math.max(n, 0), 0.999999999) : 0;
+}
+function unref(timer) {
+    const t = timer;
+    if (t && typeof t.unref === 'function')
+        t.unref();
+}
+function errorText(err) {
+    if (err && typeof err === 'object') {
+        const e = err;
+        const cause = e.cause?.code ?? e.cause?.message;
+        return `${e.name ?? 'Error'}: ${e.message ?? ''}${cause ? ` (${cause})` : ''}`.slice(0, 300);
+    }
+    return String(err).slice(0, 300);
+}
+/** The ingestor wraps 2xx bodies in {success, data, meta}; return `data` when present. */
+function unwrapEnvelope(body) {
+    const b = body;
+    const data = b && typeof b === 'object' && !Array.isArray(b) ? b.data : undefined;
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : b;
+}
+/**
+ * Bounded FIFO deque over a circular array. Back = newest, front = oldest.
+ * Not exported: the core owns the only instance.
+ */
+class EventDeque {
+    constructor(capacity) {
+        this.capacity = capacity;
+        this.head = 0;
+        this.count = 0;
+        this.items = new Array(capacity);
+    }
+    get size() {
+        return this.count;
+    }
+    /** Append; on overflow evict and return the oldest. */
+    pushBack(event) {
+        let evicted;
+        if (this.count === this.capacity) {
+            evicted = this.items[this.head];
+            this.items[this.head] = undefined;
+            this.head = (this.head + 1) % this.capacity;
+            this.count--;
+        }
+        this.items[(this.head + this.count) % this.capacity] = event;
+        this.count++;
+        return evicted;
+    }
+    /**
+     * Put `events` back at the front, in order (events[0] ends up first).
+     * They are older than anything queued, so when space runs out the oldest
+     * of them are the ones that do not fit; those are returned.
+     */
+    pushFront(events) {
+        const overflow = [];
+        for (let i = events.length - 1; i >= 0; i--) {
+            if (this.count === this.capacity) {
+                overflow.unshift(...events.slice(0, i + 1));
+                break;
+            }
+            this.head = (this.head - 1 + this.capacity) % this.capacity;
+            this.items[this.head] = events[i];
+            this.count++;
+        }
+        return overflow;
+    }
+    /** Remove and return up to `max` events from the front. */
+    take(max) {
+        const n = Math.min(max, this.count);
+        const out = new Array(n);
+        for (let i = 0; i < n; i++) {
+            out[i] = this.items[this.head];
+            this.items[this.head] = undefined;
+            this.head = (this.head + 1) % this.capacity;
+        }
+        this.count -= n;
+        return out;
+    }
+    /** Remove and return everything. */
+    drainAll() {
+        return this.take(this.count);
+    }
+}
+// One process 'beforeExit' listener per copy of this file, shared by every live core.
+const liveCores = new Set();
+let exitHookInstalled = false;
+/**
+ * The event loop has nothing left to do. Every core that still holds events
+ * (queued, or a batch it is sending or waiting to retry) shuts down and keeps
+ * the process alive until that finishes or its shutdown deadline passes. The
+ * core's own timers are unref'd, so without the keep-alive the process would
+ * exit in the middle of a retry and lose the batch. Idle cores stay
+ * registered: the app may still track events later.
+ */
+function onBeforeExit() {
+    for (const core of Array.from(liveCores))
+        core.flushForExit();
+}
+function registerExitHook(core) {
+    liveCores.add(core);
+    if (!exitHookInstalled && typeof process !== 'undefined' && typeof process.on === 'function') {
+        process.on('beforeExit', onBeforeExit);
+        exitHookInstalled = true;
+    }
+}
+function unregisterExitHook(core) {
+    liveCores.delete(core);
+    if (liveCores.size === 0 && exitHookInstalled) {
+        process.removeListener('beforeExit', onBeforeExit);
+        exitHookInstalled = false;
+    }
+}
+/**
+ * The Node transport core. One instance per SDK client.
+ *
+ * ```ts
+ * const core = new TransportCore<MyEvent>({ baseUrl, apiKey, onDrop });
+ * core.enqueue(event);          // never sends, never throws
+ * await core.flush();           // waits for the flusher to drain the queue
+ * await core.shutdown();        // drains until shutdownTimeoutMs, reports leftovers
+ * ```
+ */
+class TransportCore {
+    constructor(options) {
+        this.dropped = 0;
+        this.overflowDrops = 0;
+        this.invalidDrops = 0;
+        this.closedDrops = 0;
+        this.sentTotal = 0;
+        this.inFlight = 0;
+        this.closedFlag = false;
+        this.deadline = Infinity;
+        this.stopController = new AbortController();
+        /** Aborted to wake the flusher from its idle wait (replaced after each wake). */
+        this.idleWake = new AbortController();
+        /** Aborted to cut a breaker wait short (explicit flush / shutdown). */
+        this.breakerWake = new AbortController();
+        this.breakerOpens = 0;
+        this.breakerOpen = false;
+        /** ERROR line for this breaker opening (401/403 or a redirect) already written. */
+        this.configErrorLogged = false;
+        this.flushWaiters = [];
+        this.shutdownPromise = null;
+        this.closingTotals = { sent: 0, failed: 0, requeued: 0 };
+        this.deadlineTimer = null;
+        /** Per-event retryable failures seen so far, keyed by event object. */
+        this.perEventRetries = new WeakMap();
+        /** Highest per-event retry count in the last requeue, for the backoff before the resend. */
+        this.perEventAttempt = 0;
+        /** Each queued event's JSON, taken at enqueue. */
+        this.serialized = new WeakMap();
+        /** Events taken off the queue that are being sent or waiting for a retry. */
+        this.eventsInHand = 0;
+        this.shutdownSettled = false;
+        this.exitKeepAlive = null;
+        if (!options || typeof options.apiKey !== 'string' || !options.apiKey.trim()) {
+            throw new Error('Aforo apiKey is required');
+        }
+        const base = checkBaseUrl(options.baseUrl, options.allowInsecureHttp === true);
+        const path = options.path ?? exports.CORE_DEFAULTS.path;
+        this.url = base + (path.startsWith('/') ? path : `/${path}`);
+        const apiKey = options.apiKey;
+        this.headers = {
+            ...(options.headers ?? {}),
+            ...(options.userAgent ? { 'User-Agent': options.userAgent } : {}),
+            'Content-Type': 'application/json',
+            'X-API-Key': apiKey,
+        };
+        // Header names are case-insensitive: drop any caller copy of the reserved ones.
+        for (const name of Object.keys(this.headers)) {
+            const lower = name.toLowerCase();
+            if ((lower === 'x-api-key' && name !== 'X-API-Key') || (lower === 'content-type' && name !== 'Content-Type') || lower === 'content-encoding' || lower === 'authorization') {
+                delete this.headers[name];
+            }
+        }
+        // The key lives only in this non-enumerable header map.
+        Object.defineProperty(this, 'headers', { enumerable: false });
+        this.flushCount = Math.max(1, Math.min(Math.floor(options.flushCount ?? exports.CORE_DEFAULTS.flushCount), exports.CORE_DEFAULTS.maxBatchEvents));
+        this.flushIntervalMs = Math.max(1, options.flushIntervalMs ?? exports.CORE_DEFAULTS.flushIntervalMs);
+        this.maxRetries = Math.max(0, Math.floor(options.maxRetries ?? exports.CORE_DEFAULTS.maxRetries));
+        this.retryBaseMs = Math.max(0, options.retryBaseMs ?? exports.CORE_DEFAULTS.retryBaseMs);
+        this.retryMaxDelayMs = Math.max(0, options.retryMaxDelayMs ?? exports.CORE_DEFAULTS.retryMaxDelayMs);
+        this.retryAfterMaxMs = Math.max(0, options.retryAfterMaxMs ?? exports.CORE_DEFAULTS.retryAfterMaxMs);
+        this.breakerInitialMs = Math.max(1, options.breakerInitialMs ?? exports.CORE_DEFAULTS.breakerInitialMs);
+        this.breakerMaxMs = Math.max(this.breakerInitialMs, options.breakerMaxMs ?? exports.CORE_DEFAULTS.breakerMaxMs);
+        this.timeoutMs = Math.max(1, options.timeoutMs ?? exports.CORE_DEFAULTS.timeoutMs);
+        this.shutdownTimeoutMs = Math.max(0, options.shutdownTimeoutMs ?? exports.CORE_DEFAULTS.shutdownTimeoutMs);
+        this.targetBytes = Math.max(1024, options.targetRequestBodyBytes ?? exports.CORE_DEFAULTS.targetRequestBodyBytes);
+        this.queue = new EventDeque(Math.max(1, Math.floor(options.maxQueueSize ?? exports.CORE_DEFAULTS.maxQueueSize)));
+        this.fetchFn = options.fetch ?? ((url, init) => globalThis.fetch(url, init));
+        this.clock = options.clock ?? Date.now;
+        this.sleepFn = options.sleep ?? exports.defaultSleep;
+        this.random = options.random ?? Math.random;
+        this.onDrop = options.onDrop;
+        this.onError = options.onError;
+        this.onAccepted = options.onAccepted;
+        const prefix = options.logPrefix ?? '[aforo]';
+        this.logger = options.logger ?? {
+            // Debug lines only with AFORO_DEBUG set, so a library never fills stdout by default.
+            debug: (m) => {
+                if (typeof process !== 'undefined' && process.env && process.env.AFORO_DEBUG)
+                    console.debug(`${prefix} ${m}`);
+            },
+            warn: (m) => console.warn(`${prefix} ${m}`),
+            error: (m) => console.error(`${prefix} ${m}`),
+        };
+        if (options.flushOnExit !== false)
+            registerExitHook(this);
+        this.loop = this.run().catch((err) => {
+            // run() handles its own errors; this is a last-resort guard.
+            this.logger.error(`metering flusher stopped unexpectedly: ${errorText(err)}`);
+        });
+    }
+    // ── Public API ───────────────────────────────────────────────────
+    /**
+     * Queue an event. Never sends and never throws. The event is serialized
+     * now, so later changes to the object are not sent; one JSON cannot
+     * represent is reported through onDrop(…, 'invalid'). After shutdown the
+     * event is reported through onDrop(…, 'closed'). Returns false in both cases.
+     */
+    enqueue(event) {
+        if (this.closedFlag) {
+            const before = this.closedDrops;
+            this.recordDrop([event], 'closed', 'client is shut down');
+            if (before === 0 || Math.floor(this.closedDrops / 1000) > Math.floor(before / 1000)) {
+                this.reportError(new CoreTransportError('closed', `Aforo metering is shut down: event tracked after shutdown was dropped (${this.closedDrops} so far)`, [event]));
+            }
+            return false;
+        }
+        const encoded = serializeEvent(event);
+        if ('error' in encoded) {
+            this.recordDrop([event], 'invalid', encoded.error);
+            return false;
+        }
+        this.serialized.set(event, encoded.json);
+        const evicted = this.queue.pushBack(event);
+        if (evicted !== undefined)
+            this.recordDrop([evicted], 'overflow');
+        if (this.queue.size >= this.flushCount)
+            this.wakeIdle();
+        return true;
+    }
+    /** Count and report events the caller rejected before queueing (reason 'invalid' or another). */
+    reportDrop(events, reason, detail) {
+        this.recordDrop(events, reason, detail);
+    }
+    /**
+     * Hand the queue to the flusher and wait for one drain cycle. Never runs a
+     * second concurrent send. While the breaker is open this makes one attempt
+     * now instead of waiting for the cooldown.
+     */
+    flush() {
+        if (this.shutdownPromise) {
+            return this.shutdownPromise.then((r) => ({ sent: r.sent, failed: r.failed, requeued: r.requeued, queued: r.queued }));
+        }
+        return new Promise((resolve) => {
+            this.flushWaiters.push(resolve);
+            this.wakeIdle();
+            this.wakeBreaker();
+        });
+    }
+    /**
+     * Stop accepting events and drain until `shutdownTimeoutMs`. Each request
+     * in that window uses min(timeoutMs, time left). Events still queued at the
+     * deadline are reported through onDrop(…, 'shutdown'). Idempotent.
+     */
+    shutdown() {
+        if (this.shutdownPromise)
+            return this.shutdownPromise;
+        this.closedFlag = true;
+        this.deadline = this.clock() + this.shutdownTimeoutMs;
+        this.deadlineTimer = setTimeout(() => this.stopController.abort(), this.shutdownTimeoutMs);
+        unref(this.deadlineTimer);
+        this.wakeIdle();
+        this.wakeBreaker();
+        this.shutdownPromise = this.loop.then(() => {
+            if (this.deadlineTimer)
+                clearTimeout(this.deadlineTimer);
+            const leftovers = this.queue.drainAll();
+            if (leftovers.length > 0) {
+                const detail = `still queued when the ${this.shutdownTimeoutMs} ms shutdown deadline passed`;
+                this.recordDrop(leftovers, 'shutdown', detail);
+                this.reportError(new CoreTransportError('shutdown', `Aforo metering shutdown dropped ${leftovers.length} event(s) ${detail}`, leftovers));
+            }
+            unregisterExitHook(this);
+            this.shutdownSettled = true;
+            if (this.exitKeepAlive) {
+                clearTimeout(this.exitKeepAlive);
+                this.exitKeepAlive = null;
+            }
+            const t = this.closingTotals;
+            const result = {
+                sent: t.sent,
+                failed: t.failed + leftovers.length,
+                requeued: t.requeued,
+                queued: 0,
+                leftover: leftovers.length,
+                timedOut: leftovers.length > 0,
+            };
+            // Anyone still waiting on flush() gets the final state.
+            const late = this.flushWaiters;
+            this.flushWaiters = [];
+            for (const resolve of late)
+                resolve({ sent: result.sent, failed: result.failed, requeued: result.requeued, queued: 0 });
+            return result;
+        });
+        return this.shutdownPromise;
+    }
+    /** Events waiting in the queue. */
+    get queued() {
+        return this.queue.size;
+    }
+    /** Events lost for good since creation (every reason, including unattributed per-event rejections). */
+    get droppedCount() {
+        return this.dropped;
+    }
+    /** Events the ingestor accepted since creation. */
+    get sentCount() {
+        return this.sentTotal;
+    }
+    /** True after shutdown() was called. */
+    get closed() {
+        return this.closedFlag;
+    }
+    /** True while the breaker pauses the flusher after an outage. */
+    get isBreakerOpen() {
+        return this.breakerOpen;
+    }
+    /** Ingest requests in flight right now (0 or 1). */
+    get inFlightRequests() {
+        return this.inFlight;
+    }
+    /** True while events are queued or a taken batch is being sent / retried. */
+    get busy() {
+        return this.queue.size > 0 || this.eventsInHand > 0;
+    }
+    /**
+     * @internal Called from the process 'beforeExit' hook. When this core still
+     * holds events (or a shutdown is already running), it shuts down and holds
+     * the event loop open with one timer until the shutdown settles. Never
+     * longer than the shutdown deadline plus a second.
+     */
+    flushForExit() {
+        if (this.shutdownSettled || this.exitKeepAlive)
+            return;
+        if (!this.busy && !this.shutdownPromise)
+            return;
+        const left = this.shutdownPromise ? Math.max(0, this.deadline - this.clock()) : this.shutdownTimeoutMs;
+        this.exitKeepAlive = setTimeout(() => {
+            this.exitKeepAlive = null;
+        }, left + 1000);
+        this.shutdown().catch((err) => this.logDebug(`shutdown on beforeExit failed: ${errorText(err)}`));
+    }
+    /** @internal Debug log, used by the exit hook. */
+    logDebug(message) {
+        try {
+            this.logger.debug(message);
+        }
+        catch {
+            /* a logger must never break metering */
+        }
+    }
+    toJSON() {
+        return { url: this.url, queued: this.queued, dropped: this.dropped, closed: this.closedFlag };
+    }
+    [INSPECT]() {
+        return `TransportCore { url: '${this.url}', queued: ${this.queued}, dropped: ${this.dropped}, closed: ${this.closedFlag}, apiKey: '[redacted]' }`;
+    }
+    // ── Flusher ──────────────────────────────────────────────────────
+    wakeIdle() {
+        if (!this.idleWake.signal.aborted)
+            this.idleWake.abort();
+    }
+    wakeBreaker() {
+        if (!this.breakerWake.signal.aborted)
+            this.breakerWake.abort();
+    }
+    get pastDeadline() {
+        return this.clock() >= this.deadline || this.stopController.signal.aborted;
+    }
+    async run() {
+        let backoff = false;
+        for (;;) {
+            if (!this.closedFlag && this.flushWaiters.length === 0) {
+                if (this.breakerOpen) {
+                    await this.waitBreaker();
+                }
+                else if (backoff) {
+                    // The last cycle put per-event retryable events back: wait before resending them.
+                    await this.waitBackoff();
+                }
+                else if (this.queue.size < this.flushCount) {
+                    await this.waitIdle();
+                }
+            }
+            else if (this.closedFlag && (this.breakerOpen || backoff) && !this.pastDeadline) {
+                // Shutting down during an outage: keep trying until the deadline, with a short pause.
+                await this.sleepFn(Math.min(fullJitter(0, this.retryBaseMs, this.retryMaxDelayMs, this.random), Math.max(0, this.deadline - this.clock())), this.stopController.signal);
+            }
+            const waiters = this.flushWaiters;
+            this.flushWaiters = [];
+            const result = await this.drainCycle();
+            backoff = result.requeued > 0 && !this.breakerOpen;
+            if (this.closedFlag) {
+                this.closingTotals.sent += result.sent;
+                this.closingTotals.failed += result.failed;
+                this.closingTotals.requeued += result.requeued;
+            }
+            for (const resolve of waiters) {
+                try {
+                    resolve(result);
+                }
+                catch (err) {
+                    this.logDebug(`flush waiter failed: ${errorText(err)}`);
+                }
+            }
+            if (this.closedFlag && (this.queue.size === 0 || this.pastDeadline))
+                return;
+        }
+    }
+    async waitBackoff() {
+        if (this.breakerWake.signal.aborted)
+            this.breakerWake = new AbortController();
+        const wake = this.breakerWake;
+        // The normal jittered backoff, growing with how often these events came back retryable.
+        const delay = fullJitter(Math.max(0, this.perEventAttempt - 1), this.retryBaseMs, this.retryMaxDelayMs, this.random);
+        await this.sleepFn(Math.max(1, delay), wake.signal);
+        if (wake.signal.aborted)
+            this.breakerWake = new AbortController();
+    }
+    async waitIdle() {
+        if (this.idleWake.signal.aborted)
+            this.idleWake = new AbortController();
+        const wake = this.idleWake;
+        if (this.queue.size >= this.flushCount)
+            return;
+        await this.sleepFn(this.flushIntervalMs, wake.signal);
+        if (wake.signal.aborted)
+            this.idleWake = new AbortController();
+    }
+    async waitBreaker() {
+        if (this.breakerWake.signal.aborted)
+            this.breakerWake = new AbortController();
+        const wake = this.breakerWake;
+        const ceiling = Math.min(this.breakerMaxMs, this.breakerInitialMs * Math.pow(2, Math.max(0, this.breakerOpens - 1)));
+        // Full jitter with a floor, so a 401/3xx loop cannot spin: max(250 ms, random(0, ceiling)).
+        const cooldown = Math.max(BREAKER_FLOOR_MS, Math.floor(clamp01(this.random()) * ceiling));
+        this.logDebug(`breaker open: next attempt in ${cooldown} ms (${this.queue.size} queued)`);
+        await this.sleepFn(cooldown, wake.signal);
+        if (wake.signal.aborted)
+            this.breakerWake = new AbortController();
+    }
+    /** Send everything queued, one request at a time. Stops on outage or deadline. */
+    async drainCycle() {
+        const result = { sent: 0, failed: 0, requeued: 0, queued: 0 };
+        try {
+            while (this.queue.size > 0) {
+                if (this.closedFlag && this.pastDeadline)
+                    break;
+                const batch = this.queue.take(this.flushCount);
+                this.eventsInHand = batch.length;
+                let stop;
+                try {
+                    stop = await this.sendBatch(batch, result);
+                }
+                finally {
+                    this.eventsInHand = 0;
+                }
+                if (stop)
+                    break;
+            }
+        }
+        catch (err) {
+            this.logger.error(`metering flush failed unexpectedly: ${errorText(err)}`);
+        }
+        result.queued = this.queue.size;
+        return result;
+    }
+    /**
+     * Send one batch (splitting it when the body is too large or the ingestor
+     * answers 413). Returns true when the cycle must stop (outage or deadline);
+     * unsent events are already back at the front of the queue then.
+     */
+    async sendBatch(batch, result) {
+        const pending = [batch];
+        while (pending.length > 0) {
+            const chunk = pending.shift();
+            const body = this.bodyFor(chunk);
+            if (chunk.length > 1 && byteLength(body) > this.targetBytes) {
+                const mid = Math.ceil(chunk.length / 2);
+                pending.unshift(chunk.slice(0, mid), chunk.slice(mid));
+                continue;
+            }
+            const outcome = await this.sendWithRetry(chunk, body);
+            if (outcome.kind === 'split') {
+                if (chunk.length === 1) {
+                    this.recordDrop(chunk, 'rejected', 'HTTP 413: a single event is larger than the ingestor accepts');
+                    result.failed += 1;
+                    this.reportError(new CoreTransportError('rejected', 'Aforo ingestor rejected an event with HTTP 413 (request too large); the event was dropped', chunk, { status: 413 }));
+                }
+                else {
+                    const mid = Math.ceil(chunk.length / 2);
+                    pending.unshift(chunk.slice(0, mid), chunk.slice(mid));
+                }
+                continue;
+            }
+            if (outcome.kind === 'done') {
+                result.sent += outcome.sent;
+                result.failed += outcome.failed;
+                this.sentTotal += outcome.sent;
+                if (outcome.retryable.length > 0) {
+                    const again = outcome.retryable;
+                    result.requeued += again.length;
+                    let exhausted = false;
+                    let highest = 0;
+                    for (const e of again) {
+                        const n = (this.perEventRetries.get(e) ?? 0) + 1;
+                        this.perEventRetries.set(e, n);
+                        highest = Math.max(highest, n);
+                        if (n > this.maxRetries)
+                            exhausted = true;
+                    }
+                    this.perEventAttempt = highest;
+                    const remaining = [].concat(again, ...pending);
+                    this.requeue(remaining);
+                    if (exhausted) {
+                        // The retry cap was reached: an outage. This 2xx does not count as
+                        // the recovery that resets the breaker, so cooldowns keep growing.
+                        this.openBreaker(undefined, 'the ingestor kept reporting events as retryable', remaining);
+                    }
+                    else {
+                        this.closeBreaker();
+                    }
+                    // End the cycle; the flusher waits the backoff before resending.
+                    return true;
+                }
+                this.closeBreaker();
+                continue;
+            }
+            // outage or deadline: put this chunk and everything not yet sent back in front.
+            const unsent = [].concat(chunk, ...pending);
+            result.requeued += unsent.length;
+            this.requeue(unsent);
+            if (outcome.kind === 'outage')
+                this.openBreaker(outcome.status, outcome.reason, unsent, outcome.redirectTo);
+            return true;
+        }
+        return false;
+    }
+    /** Request body from the JSON taken at enqueue. */
+    bodyFor(chunk) {
+        const parts = new Array(chunk.length);
+        for (let i = 0; i < chunk.length; i++) {
+            const cached = this.serialized.get(chunk[i]);
+            // Every queued event passed enqueue(); the fallback covers events placed by reportDrop paths only.
+            parts[i] = cached ?? JSON.stringify(chunk[i]);
+        }
+        return `{"events":[${parts.join(',')}]}`;
+    }
+    requeue(events) {
+        const overflow = this.queue.pushFront(events);
+        if (overflow.length > 0)
+            this.recordDrop(overflow, 'overflow');
+    }
+    /** `kept` are the events just put back on the queue (named in the onError report). */
+    openBreaker(status, reason, kept, redirectTo) {
+        const first = !this.breakerOpen;
+        this.breakerOpen = true;
+        this.breakerOpens += 1;
+        if (redirectTo !== undefined) {
+            // Once per breaker opening. A redirect means the base URL is wrong (or a
+            // proxy is rewriting it); following it would send the API key elsewhere.
+            if (!this.configErrorLogged) {
+                this.configErrorLogged = true;
+                const message = `Aforo ingestor answered HTTP ${status} redirecting to ${redirectTo}; redirects are not followed so the API key ` +
+                    `never reaches another host. Usage stays queued (${this.queue.size} events). Fix the ingestor base URL.`;
+                this.logger.error(message);
+                this.reportError(new CoreTransportError('outage', message, kept, { status }));
+            }
+            return;
+        }
+        if (first) {
+            this.logger.warn(`Aforo ingestor unavailable (${reason}); ${this.queue.size} events queued, retrying with backoff.`);
+        }
+        if (status !== undefined && AUTH_STATUSES.has(status)) {
+            // Once per breaker opening, also when an outage turns into 401/403 while the breaker is open.
+            if (!this.configErrorLogged) {
+                this.configErrorLogged = true;
+                this.logger.error(`Aforo ingestor answered HTTP ${status}: the API key is wrong or revoked. ` +
+                    `Usage stays queued (${this.queue.size} events) and is sent once a valid key is in place.`);
+                this.reportError(new CoreTransportError('auth', `Aforo ingestor answered HTTP ${status}: the API key is wrong or revoked. Events are kept and retried.`, kept, { status }));
+            }
+        }
+        else if (first) {
+            this.reportError(new CoreTransportError('outage', `Aforo ingestor unavailable: ${reason}. Events are kept and retried.`, kept, { status }));
+        }
+    }
+    closeBreaker() {
+        if (this.breakerOpen) {
+            this.logger.warn('Aforo ingestor reachable again; sending queued events.');
+        }
+        this.breakerOpen = false;
+        this.breakerOpens = 0;
+        this.configErrorLogged = false;
+    }
+    /** One chunk, with retries. Never throws. */
+    async sendWithRetry(chunk, body) {
+        let lastReason = 'no attempt';
+        let lastStatus;
+        for (let attempt = 0;; attempt++) {
+            if (this.closedFlag && this.pastDeadline)
+                return { kind: 'deadline' };
+            const timeLeft = this.deadline - this.clock();
+            const requestTimeout = Math.max(1, Math.min(this.timeoutMs, timeLeft));
+            let retryAfterMs;
+            let response;
+            try {
+                response = await this.post(body, requestTimeout);
+            }
+            catch (err) {
+                if (this.closedFlag && this.pastDeadline)
+                    return { kind: 'deadline' };
+                lastReason = `network error: ${errorText(err)}`;
+                lastStatus = undefined;
+            }
+            if (response) {
+                const status = response.status;
+                if (status >= 200 && status < 300) {
+                    return this.handleAccepted(response, chunk);
+                }
+                if (status === 413)
+                    return { kind: 'split' };
+                if (isRedirect(status)) {
+                    return {
+                        kind: 'outage',
+                        status,
+                        reason: `HTTP ${status} redirect`,
+                        redirectTo: redirectTarget(response.headers?.get?.('location') ?? null, this.url),
+                    };
+                }
+                if (AUTH_STATUSES.has(status)) {
+                    await this.discardBody(response);
+                    return { kind: 'outage', status, reason: `HTTP ${status}` };
+                }
+                if (RETRY_STATUSES.has(status) || status >= 500) {
+                    retryAfterMs = parseRetryAfter(response.headers?.get?.('retry-after') ?? null, this.clock(), this.retryAfterMaxMs);
+                    lastReason = `HTTP ${status}`;
+                    lastStatus = status;
+                    await this.discardBody(response);
+                }
+                else {
+                    const detail = await this.readProblem(response);
+                    this.recordDrop(chunk, 'rejected', `HTTP ${status}${detail ? `: ${detail}` : ''}`);
+                    this.reportError(new CoreTransportError('rejected', `Aforo ingestor rejected a batch of ${chunk.length} with HTTP ${status}${detail ? `: ${detail}` : ''} (not retried)`, chunk, { status }));
+                    return { kind: 'done', sent: 0, failed: chunk.length, retryable: [] };
+                }
+            }
+            if (attempt >= this.maxRetries) {
+                return { kind: 'outage', status: lastStatus, reason: `${lastReason} after ${attempt + 1} attempts` };
+            }
+            const jittered = fullJitter(attempt, this.retryBaseMs, this.retryMaxDelayMs, this.random);
+            const delay = retryAfterMs !== undefined ? Math.min(Math.max(retryAfterMs, jittered), this.retryAfterMaxMs) : jittered;
+            if (this.closedFlag && this.clock() + delay >= this.deadline)
+                return { kind: 'deadline' };
+            this.logDebug(`ingest attempt ${attempt + 1} failed (${lastReason}); retrying in ${delay} ms`);
+            await this.sleepFn(delay, this.stopController.signal);
+        }
+    }
+    async post(body, timeoutMs) {
+        const controller = new AbortController();
+        const timeoutSignal = AbortSignal.timeout(timeoutMs);
+        const onTimeout = () => controller.abort(timeoutSignal.reason);
+        const onStop = () => controller.abort(new Error('shutdown deadline passed'));
+        timeoutSignal.addEventListener('abort', onTimeout, { once: true });
+        this.stopController.signal.addEventListener('abort', onStop, { once: true });
+        this.inFlight += 1;
+        try {
+            const response = await untilAborted(Promise.resolve().then(() => this.fetchFn(this.url, { method: 'POST', headers: this.headers, body, signal: controller.signal, redirect: 'manual' })), controller.signal);
+            // Read the body inside the same deadline: a server that sends headers
+            // and then stalls, or drips the body, must not hold the flusher.
+            return await bufferBody(response, controller.signal);
+        }
+        finally {
+            this.inFlight -= 1;
+            timeoutSignal.removeEventListener('abort', onTimeout);
+            this.stopController.signal.removeEventListener('abort', onStop);
+        }
+    }
+    async handleAccepted(response, chunk) {
+        let body;
+        try {
+            body = unwrapEnvelope(await readJson(response));
+        }
+        catch (err) {
+            this.logDebug(`ingest response body unreadable: ${errorText(err)}`);
+        }
+        const errors = Array.isArray(body?.errors) ? body.errors : [];
+        const reportedFailed = typeof body?.failed === 'number' && body.failed > 0 ? Math.floor(body.failed) : 0;
+        const seen = new Set();
+        const rejected = [];
+        const retryable = [];
+        const messages = [];
+        for (const e of errors) {
+            const index = Number(e?.index);
+            if (!Number.isInteger(index) || index < 0 || index >= chunk.length || seen.has(index))
+                continue;
+            seen.add(index);
+            if (e?.retryable === true) {
+                retryable.push(chunk[index]);
+            }
+            else {
+                rejected.push(chunk[index]);
+                if (messages.length < 5)
+                    messages.push(`#${index}: ${String(e?.message ?? 'rejected').slice(0, 200)}`);
+            }
+        }
+        const unattributed = Math.max(0, Math.min(chunk.length, reportedFailed) - seen.size);
+        if (rejected.length > 0) {
+            this.recordDrop(rejected, 'rejected', messages.join('; '));
+            this.reportError(new CoreTransportError('rejected', `Aforo ingestor rejected ${rejected.length} event(s): ${messages.join('; ')}`, rejected, {
+                status: response.status,
+            }));
+        }
+        if (unattributed > 0) {
+            // The ingestor reported failures without saying which: count them, nothing to hand to onDrop.
+            this.dropped += unattributed;
+            this.logger.warn(`Aforo ingestor rejected ${unattributed} event(s) without naming them (${this.dropped} total dropped).`);
+        }
+        const failed = rejected.length + unattributed;
+        if (this.onAccepted) {
+            try {
+                this.onAccepted(body, chunk);
+            }
+            catch (err) {
+                this.logDebug(`onAccepted hook threw: ${errorText(err)}`);
+            }
+        }
+        return { kind: 'done', sent: chunk.length - failed - retryable.length, failed, retryable };
+    }
+    async discardBody(response) {
+        try {
+            if (typeof response.text === 'function')
+                await response.text();
+        }
+        catch (err) {
+            this.logDebug(`could not read error body: ${errorText(err)}`);
+        }
+    }
+    async readProblem(response) {
+        try {
+            const body = unwrapEnvelope(await readJson(response));
+            if (!body)
+                return undefined;
+            const first = Array.isArray(body?.errors) ? body.errors[0] : undefined;
+            const msg = first?.message ?? body?.detail ?? body?.message ?? body?.error ?? body?.title;
+            return typeof msg === 'string' && msg ? msg.slice(0, 300) : undefined;
+        }
+        catch (err) {
+            this.logDebug(`error body is not JSON: ${errorText(err)}`);
+            return undefined;
+        }
+    }
+    // ── Drop accounting ──────────────────────────────────────────────
+    recordDrop(events, reason, detail) {
+        if (!events || events.length === 0)
+            return;
+        this.dropped += events.length;
+        try {
+            if (reason === 'overflow' || reason === 'invalid' || reason === 'closed') {
+                // Hot-path reasons: first, then every 1000th, so a loop cannot storm the log.
+                const before = reason === 'overflow' ? this.overflowDrops : reason === 'invalid' ? this.invalidDrops : this.closedDrops;
+                const after = before + events.length;
+                if (reason === 'overflow')
+                    this.overflowDrops = after;
+                else if (reason === 'invalid')
+                    this.invalidDrops = after;
+                else
+                    this.closedDrops = after;
+                if (before === 0 || Math.floor(after / 1000) > Math.floor(before / 1000)) {
+                    this.logger.warn(`Dropped ${events.length} event(s) — ${reason}${detail ? `: ${detail}` : ''} (${this.dropped} total dropped).` +
+                        (reason === 'overflow' ? ' Raise maxQueueSize or check ingest connectivity.' : ''));
+                }
+            }
+            else {
+                this.logger.warn(`Dropped ${events.length} event(s) — ${reason}${detail ? `: ${detail}` : ''} (${this.dropped} total dropped).`);
+            }
+        }
+        catch {
+            /* a logger must never break metering */
+        }
+        if (this.onDrop) {
+            try {
+                this.onDrop(events, reason, detail);
+            }
+            catch (err) {
+                this.logDebug(`onDrop hook threw: ${errorText(err)}`);
+            }
+        }
+    }
+    reportError(err) {
+        if (!this.onError)
+            return;
+        try {
+            this.onError(err);
+        }
+        catch (hookErr) {
+            this.logDebug(`onError hook threw: ${errorText(hookErr)}`);
+        }
+    }
+}
+exports.TransportCore = TransportCore;
+/**
+ * Read the whole body now, giving up when `signal` aborts, and hand back a
+ * response whose text()/json() return what was read. Callers then parse
+ * without touching the network again.
+ */
+async function bufferBody(response, signal) {
+    if (typeof response.text === 'function') {
+        const text = await untilAborted(Promise.resolve().then(() => response.text()), signal);
+        return { status: response.status, ok: response.ok, headers: response.headers, text: async () => text };
+    }
+    if (typeof response.json === 'function') {
+        const json = await untilAborted(Promise.resolve().then(() => response.json()), signal);
+        return { status: response.status, ok: response.ok, headers: response.headers, json: async () => json };
+    }
+    return response;
+}
+/** Parse a response body as JSON (text() first, json() as a fallback). Empty body → undefined. */
+async function readJson(response) {
+    if (typeof response.text === 'function') {
+        const text = await response.text();
+        return text ? JSON.parse(text) : undefined;
+    }
+    if (typeof response.json === 'function')
+        return response.json();
+    return undefined;
+}
+function byteLength(text) {
+    return Buffer.byteLength(text, 'utf8');
+}
+//# sourceMappingURL=core.js.map