@edraj/sauron-node 1.0.0

package/dist/scope.js

@@ -0,0 +1,161 @@
+/**
+ * Scope — global process-wide defaults plus per-request/per-task isolation.
+ *
+ * A single global {@link Scope} holds process-wide user/tags/context/breadcrumbs.
+ * {@link withScope} (or {@link runWithAsyncScope}) layers an isolated child scope
+ * over the current one for the duration of a callback, backed by
+ * {@link AsyncLocalStorage} so concurrent requests never leak state into each
+ * other. Reads merge child-over-parent because a child is a *snapshot* of its
+ * parent taken at entry.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+const DEFAULT_MAX_BREADCRUMBS = 100;
+/** Stamp a breadcrumb, defaulting missing fields; preserves an existing timestamp. */
+export function normalizeBreadcrumb(input) {
+    const existing = input.timestamp;
+    return {
+        type: input.type ?? 'default',
+        category: input.category ?? null,
+        message: input.message ?? null,
+        level: input.level ?? null,
+        timestamp: typeof existing === 'string' ? existing : new Date().toISOString(),
+        data: input.data ?? {},
+    };
+}
+function toErrorUser(user) {
+    if (!user)
+        return null;
+    return {
+        id: user.id ?? null,
+        email: user.email ?? null,
+        username: user.username ?? null,
+    };
+}
+/** The mutable per-scope state and the operations over it. */
+export class Scope {
+    data = {
+        user: null,
+        tags: {},
+        contexts: {},
+        extra: {},
+        breadcrumbs: [],
+    };
+    maxBreadcrumbs;
+    constructor(maxBreadcrumbs = DEFAULT_MAX_BREADCRUMBS) {
+        this.maxBreadcrumbs = Math.max(0, maxBreadcrumbs);
+    }
+    setUser(user) {
+        this.data.user = user;
+        return this;
+    }
+    setTag(key, value) {
+        this.data.tags[key] = value;
+        return this;
+    }
+    setTags(tags) {
+        Object.assign(this.data.tags, tags);
+        return this;
+    }
+    setContext(key, context) {
+        this.data.contexts[key] = context;
+        return this;
+    }
+    setExtra(key, value) {
+        this.data.extra[key] = value;
+        return this;
+    }
+    addBreadcrumb(crumb) {
+        if (this.maxBreadcrumbs <= 0)
+            return this;
+        this.data.breadcrumbs.push(normalizeBreadcrumb(crumb));
+        const overflow = this.data.breadcrumbs.length - this.maxBreadcrumbs;
+        if (overflow > 0)
+            this.data.breadcrumbs.splice(0, overflow);
+        return this;
+    }
+    setMaxBreadcrumbs(max) {
+        this.maxBreadcrumbs = Math.max(0, max);
+        const overflow = this.data.breadcrumbs.length - this.maxBreadcrumbs;
+        if (overflow > 0)
+            this.data.breadcrumbs.splice(0, overflow);
+    }
+    /** A deep-enough snapshot; children never share mutable containers with parents. */
+    clone() {
+        const copy = new Scope(this.maxBreadcrumbs);
+        copy.data.user = this.data.user ? { ...this.data.user } : null;
+        copy.data.tags = { ...this.data.tags };
+        copy.data.contexts = { ...this.data.contexts };
+        copy.data.extra = { ...this.data.extra };
+        copy.data.breadcrumbs = this.data.breadcrumbs.slice();
+        return copy;
+    }
+    /**
+     * Layer this scope onto an error item: fill breadcrumbs from the trail, merge
+     * scope tags *under* any per-call tags, and set the user only when the item
+     * has none (per-call values win).
+     */
+    applyToErrorItem(item) {
+        item.tags = { ...this.data.tags, ...(item.tags ?? {}) };
+        const contexts = { ...this.data.contexts, ...(item.contexts ?? {}) };
+        if (Object.keys(contexts).length > 0)
+            item.contexts = contexts;
+        else
+            delete item.contexts;
+        const extra = { ...this.data.extra, ...(item.extra ?? {}) };
+        if (Object.keys(extra).length > 0)
+            item.extra = extra;
+        else
+            delete item.extra;
+        if (item.user == null)
+            item.user = toErrorUser(this.data.user);
+        item.breadcrumbs = this.data.breadcrumbs.slice();
+    }
+    /**
+     * Merge this scope's metadata *under* per-call overrides for non-error items
+     * (analytics `track`). tags & extra merge by shallow key; contexts merge by
+     * block name (a per-call block replaces the same-named scope block). Empty
+     * maps are omitted from the result per the emit convention.
+     */
+    mergeMetadata(overrides = {}) {
+        const out = {};
+        const tags = { ...this.data.tags, ...(overrides.tags ?? {}) };
+        if (Object.keys(tags).length > 0)
+            out.tags = tags;
+        const contexts = { ...this.data.contexts, ...(overrides.contexts ?? {}) };
+        if (Object.keys(contexts).length > 0)
+            out.contexts = contexts;
+        const extra = { ...this.data.extra, ...(overrides.extra ?? {}) };
+        if (Object.keys(extra).length > 0)
+            out.extra = extra;
+        return out;
+    }
+}
+const globalScope = new Scope();
+const als = new AsyncLocalStorage();
+/** The process-wide scope holding defaults set at/after init. */
+export function getGlobalScope() {
+    return globalScope;
+}
+/** The scope in effect right now: the async-local child if inside a scoped block, else global. */
+export function getCurrentScope() {
+    return als.getStore() ?? globalScope;
+}
+/**
+ * Run `cb` with an isolated child scope (a snapshot of the current one). The
+ * child is passed to `cb` and is what {@link getCurrentScope} returns for the
+ * duration — including across `await`s inside `cb`. Returns whatever `cb`
+ * returns (awaitable if `cb` is async).
+ */
+export function withScope(cb) {
+    const child = getCurrentScope().clone();
+    return als.run(child, () => cb(child));
+}
+/** Like {@link withScope}, but the callback takes no scope argument. */
+export function runWithAsyncScope(cb) {
+    const child = getCurrentScope().clone();
+    return als.run(child, cb);
+}
+/** Mutate the active scope (the global scope outside any {@link withScope}). */
+export function configureScope(cb) {
+    cb(getCurrentScope());
+}

package/dist/stacktrace.d.ts

@@ -0,0 +1,23 @@
+import type { Frame } from './types.js';
+/**
+ * V8 (`Error.stack`) parser for Node.
+ *
+ * Produces neutral frames with the CRASHING FRAME LAST (raw V8 stacks list the
+ * crash site first, so the parsed list is reversed). No symbolication is
+ * performed — line/column/filename pass through verbatim.
+ */
+export declare const MAX_FRAMES = 50;
+/**
+ * Heuristic for whether a frame belongs to first-party ("in app") code:
+ * Node internals (`node:` / `internal/`) and `node_modules` dependencies are
+ * not in-app; everything else (the app's own files) is.
+ */
+export declare function isInAppFrame(filename: string | null): boolean;
+/**
+ * Parse a raw `Error.stack` string into normalized frames (crash frame last).
+ * Non-frame lines (the `Error: message` header, `[native code]`, etc.) are
+ * skipped.
+ */
+export declare function parseStackString(stack: string | undefined | null): Frame[];
+/** Parse an `Error`-like object's `.stack`. */
+export declare function parseError(err: unknown): Frame[];

package/dist/stacktrace.js

@@ -0,0 +1,93 @@
+/**
+ * V8 (`Error.stack`) parser for Node.
+ *
+ * Produces neutral frames with the CRASHING FRAME LAST (raw V8 stacks list the
+ * crash site first, so the parsed list is reversed). No symbolication is
+ * performed — line/column/filename pass through verbatim.
+ */
+export const MAX_FRAMES = 50;
+/** V8 / Node: `    at fn (file:line:col)` or `    at file:line:col`. */
+const V8_RE = /^\s*at (?:(.+?) )?\(?((?:[a-z][\w.+-]*:\/\/)?[^\s()]+?):(\d+):(\d+)\)?\s*$/i;
+function cleanFunction(fn) {
+    if (!fn)
+        return null;
+    let name = fn.trim();
+    name = name.replace(/^async\s+/, '').replace(/^new\s+/, 'new ');
+    name = name.replace(/\s+\[as .+\]$/, '');
+    if (name === '<anonymous>' || name === '')
+        return null;
+    return name;
+}
+/**
+ * Heuristic for whether a frame belongs to first-party ("in app") code:
+ * Node internals (`node:` / `internal/`) and `node_modules` dependencies are
+ * not in-app; everything else (the app's own files) is.
+ */
+export function isInAppFrame(filename) {
+    if (!filename)
+        return false;
+    if (filename === '<anonymous>' ||
+        filename.startsWith('node:') ||
+        filename.startsWith('internal/') ||
+        filename.startsWith('node internal')) {
+        return false;
+    }
+    if (filename.includes('node_modules'))
+        return false;
+    return true;
+}
+function stripFileProtocol(filename) {
+    return filename.startsWith('file://') ? filename.slice('file://'.length) : filename;
+}
+function parseLine(line) {
+    const m = V8_RE.exec(line);
+    if (!m)
+        return null;
+    const rawFile = m[2] || null;
+    const filename = rawFile ? stripFileProtocol(rawFile) : null;
+    const lineno = m[3] ? parseInt(m[3], 10) : null;
+    const colno = m[4] ? parseInt(m[4], 10) : null;
+    return {
+        function: cleanFunction(m[1]),
+        module: null,
+        filename,
+        abs_path: filename,
+        lineno: lineno !== null && Number.isNaN(lineno) ? null : lineno,
+        colno: colno !== null && Number.isNaN(colno) ? null : colno,
+        in_app: isInAppFrame(filename),
+    };
+}
+/**
+ * Parse a raw `Error.stack` string into normalized frames (crash frame last).
+ * Non-frame lines (the `Error: message` header, `[native code]`, etc.) are
+ * skipped.
+ */
+export function parseStackString(stack) {
+    if (!stack)
+        return [];
+    const frames = [];
+    const lines = stack.split('\n');
+    for (const raw of lines) {
+        const line = raw.replace(/\r$/, '');
+        if (!line.trim())
+            continue;
+        const frame = parseLine(line);
+        if (frame) {
+            frames.push(frame);
+            if (frames.length >= MAX_FRAMES)
+                break; // keep frames nearest the crash
+        }
+    }
+    // Raw V8 stacks are crash-first; the wire contract wants crash-last.
+    frames.reverse();
+    return frames;
+}
+/** Parse an `Error`-like object's `.stack`. */
+export function parseError(err) {
+    if (err && typeof err === 'object' && 'stack' in err) {
+        const stack = err.stack;
+        if (typeof stack === 'string')
+            return parseStackString(stack);
+    }
+    return [];
+}

package/dist/transport.d.ts

@@ -0,0 +1,93 @@
+import type { Dsn } from './dsn.js';
+import type { Context, EnvelopeItem, FetchLike, SleepFn } from './types.js';
+export interface TransportConfig {
+    dsn: Dsn;
+    environment: string;
+    release: string | null;
+    context: Context;
+    flushInterval: number;
+    maxBatch: number;
+    fetchImpl?: FetchLike;
+    debug: boolean;
+    /** Gzip the body once it exceeds this many bytes. Default 1024. */
+    gzipThresholdBytes?: number;
+    /** Drop-oldest byte cap for the in-memory buffer. Default 1 MiB. */
+    maxQueueBytes?: number;
+    /**
+     * Hard cap on items per envelope. Default 1000, matching the server's limit —
+     * exceeding it is a non-retryable 400, which would discard the batch.
+     */
+    maxItemsPerEnvelope?: number;
+    /** Opt-in directory for FIFO disk persistence. Default off. */
+    offlineDir?: string | null;
+    /** Max retries after the first attempt. Default 3. */
+    maxRetries?: number;
+    /** Backoff base (ms). Default 200. */
+    retryBaseMs?: number;
+    /** Deterministic sleep seam (tests). Defaults to a real timer. */
+    sleep?: SleepFn;
+    /** Jitter source (tests). Defaults to `Math.random`. */
+    random?: () => number;
+}
+/**
+ * Parse a `Retry-After` header (delta-seconds or an HTTP-date) into a delay in
+ * ms, clamped to non-negative. Returns `null` when absent/unparseable.
+ */
+export declare function parseRetryAfter(value: string | null | undefined, nowMs: number): number | null;
+/**
+ * Buffered background transport.
+ *
+ * Items accumulate in a byte-bounded {@link BoundedQueue} (optionally persisted
+ * to disk). A `setInterval` timer (unref'd, so it never keeps the event loop
+ * alive) flushes every `flushInterval` ms, and an eager flush fires once the
+ * queue reaches `maxBatch`. Each flush drains a batch into one envelope, gzips
+ * it when large, and POSTs it with an exponential-backoff retry policy:
+ *
+ * - retry 408/429/5xx and network errors (honoring `Retry-After` on 429),
+ * - shrink and re-buffer on 413 rather than retrying an identically-sized body,
+ * - drop (no retry) on 400/401/403/404 — 401/403 also disable the SDK,
+ * - after `maxRetries` transient failures, the batch is re-buffered (kept for a
+ *   later flush / next process start) rather than lost.
+ *
+ * Flushes are serialized through a promise chain so a batch is never drained by
+ * two overlapping flushes.
+ */
+export declare class Transport {
+    private readonly config;
+    private readonly buffer;
+    private timer;
+    private readonly fetchImpl;
+    private disabled;
+    private readonly gzipThreshold;
+    private readonly maxRetries;
+    private readonly retryBaseMs;
+    private readonly sleep;
+    private readonly random;
+    /** Configured ceiling on items per envelope. */
+    private readonly maxItemsPerEnvelope;
+    /**
+     * Working chunk size, halved whenever the server rejects an envelope as too
+     * large. Without this a 413 was retried with the identical body forever.
+     */
+    private chunkItems;
+    /** Serializes flushes so a batch is drained/committed atomically. */
+    private flushChain;
+    constructor(config: TransportConfig);
+    private startTimer;
+    /** Enqueue an item; triggers an eager flush at `maxBatch`. */
+    enqueue(item: EnvelopeItem): void;
+    private buildEnvelope;
+    /**
+     * Drain a batch and send it. Serialized through {@link flushChain} so
+     * overlapping calls (eager + timer + manual) never race the queue.
+     */
+    flush(): Promise<void>;
+    private drainAndSend;
+    private send;
+    /** Exponential backoff with equal-jitter, capped at {@link RETRY_CAP_MS}. */
+    private backoffDelay;
+    /** Flush then stop the timer. After close the transport still accepts a
+     * final manual `flush`, but the background timer no longer fires. */
+    close(): Promise<void>;
+    private log;
+}

package/dist/transport.js

@@ -0,0 +1,250 @@
+import { maybeGzip } from './gzip.js';
+import { BoundedQueue } from './queue.js';
+const SDK_NAME = 'sauron-node';
+const SDK_VERSION = '1.0.0';
+/** Default exponential-backoff base (ms) for the first retry. */
+const DEFAULT_RETRY_BASE_MS = 200;
+/** Hard cap on any single backoff delay (ms). */
+const RETRY_CAP_MS = 30_000;
+/** Statuses that are worth retrying (plus any 5xx and network errors). */
+function isRetryableStatus(status) {
+    return status === 408 || status === 413 || status === 429 || status >= 500;
+}
+/**
+ * Parse a `Retry-After` header (delta-seconds or an HTTP-date) into a delay in
+ * ms, clamped to non-negative. Returns `null` when absent/unparseable.
+ */
+export function parseRetryAfter(value, nowMs) {
+    if (value == null)
+        return null;
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return null;
+    const secs = Number(trimmed);
+    if (Number.isFinite(secs))
+        return Math.max(0, secs * 1000);
+    const dateMs = Date.parse(trimmed);
+    if (!Number.isNaN(dateMs))
+        return Math.max(0, dateMs - nowMs);
+    return null;
+}
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Buffered background transport.
+ *
+ * Items accumulate in a byte-bounded {@link BoundedQueue} (optionally persisted
+ * to disk). A `setInterval` timer (unref'd, so it never keeps the event loop
+ * alive) flushes every `flushInterval` ms, and an eager flush fires once the
+ * queue reaches `maxBatch`. Each flush drains a batch into one envelope, gzips
+ * it when large, and POSTs it with an exponential-backoff retry policy:
+ *
+ * - retry 408/429/5xx and network errors (honoring `Retry-After` on 429),
+ * - shrink and re-buffer on 413 rather than retrying an identically-sized body,
+ * - drop (no retry) on 400/401/403/404 — 401/403 also disable the SDK,
+ * - after `maxRetries` transient failures, the batch is re-buffered (kept for a
+ *   later flush / next process start) rather than lost.
+ *
+ * Flushes are serialized through a promise chain so a batch is never drained by
+ * two overlapping flushes.
+ */
+export class Transport {
+    config;
+    buffer;
+    timer = null;
+    fetchImpl;
+    disabled = false;
+    gzipThreshold;
+    maxRetries;
+    retryBaseMs;
+    sleep;
+    random;
+    /** Configured ceiling on items per envelope. */
+    maxItemsPerEnvelope;
+    /**
+     * Working chunk size, halved whenever the server rejects an envelope as too
+     * large. Without this a 413 was retried with the identical body forever.
+     */
+    chunkItems;
+    /** Serializes flushes so a batch is drained/committed atomically. */
+    flushChain = Promise.resolve();
+    constructor(config) {
+        this.config = config;
+        const injected = config.fetchImpl;
+        const globalFetch = globalThis.fetch;
+        const chosen = injected ?? globalFetch;
+        if (!chosen) {
+            throw new Error('[sauron] global fetch is unavailable (Node >= 18 required) and no fetchImpl was provided');
+        }
+        this.fetchImpl = chosen;
+        this.gzipThreshold = config.gzipThresholdBytes ?? 1024;
+        this.maxRetries = Math.max(0, config.maxRetries ?? 3);
+        this.retryBaseMs = config.retryBaseMs ?? DEFAULT_RETRY_BASE_MS;
+        this.maxItemsPerEnvelope = Math.max(1, config.maxItemsPerEnvelope ?? 1000);
+        this.chunkItems = this.maxItemsPerEnvelope;
+        this.sleep = config.sleep ?? realSleep;
+        this.random = config.random ?? Math.random;
+        this.buffer = new BoundedQueue({
+            maxBytes: config.maxQueueBytes ?? 1_048_576,
+            offlineDir: config.offlineDir ?? null,
+        });
+        this.startTimer();
+    }
+    startTimer() {
+        if (this.timer || this.config.flushInterval <= 0)
+            return;
+        this.timer = setInterval(() => {
+            void this.flush();
+        }, this.config.flushInterval);
+        // Do not hold the event loop open for the flush timer.
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    /** Enqueue an item; triggers an eager flush at `maxBatch`. */
+    enqueue(item) {
+        if (this.disabled)
+            return;
+        this.buffer.push(item);
+        if (this.buffer.size >= this.config.maxBatch) {
+            void this.flush();
+        }
+    }
+    buildEnvelope(items) {
+        const header = {
+            dsn: this.config.dsn.raw,
+            sdk: { name: SDK_NAME, version: SDK_VERSION },
+            sent_at: new Date().toISOString(),
+            environment: this.config.environment,
+            release: this.config.release,
+        };
+        return { header, context: this.config.context, items };
+    }
+    /**
+     * Drain a batch and send it. Serialized through {@link flushChain} so
+     * overlapping calls (eager + timer + manual) never race the queue.
+     */
+    flush() {
+        const next = this.flushChain.then(() => this.drainAndSend());
+        // Swallow rejections on the chain so one failure can't poison later flushes.
+        this.flushChain = next.catch(() => undefined);
+        return this.flushChain;
+    }
+    async drainAndSend() {
+        if (this.disabled)
+            return;
+        // Send in bounded chunks rather than one envelope per flush. A queue that
+        // filled during an outage would otherwise go out as a single oversized
+        // envelope and be rejected outright.
+        for (;;) {
+            const items = this.buffer.drain(this.chunkItems);
+            if (items.length === 0) {
+                this.buffer.commit();
+                return;
+            }
+            const before = this.buffer.pending;
+            await this.send(this.buildEnvelope(items));
+            if (this.disabled)
+                return;
+            // Nothing left, or the send failed and re-buffered: stop rather than spin.
+            if (this.buffer.pending === 0 || this.buffer.pending >= before + items.length) {
+                return;
+            }
+        }
+    }
+    async send(envelope) {
+        const { dsn } = this.config;
+        const raw = JSON.stringify(envelope);
+        const { body, headers: encodingHeaders } = maybeGzip(raw, this.gzipThreshold);
+        const headers = {
+            'Content-Type': 'application/json',
+            'X-Sauron-Key': dsn.publicKey,
+            ...encodingHeaders,
+        };
+        let attempt = 0;
+        for (;;) {
+            let retryAfterMs = null;
+            try {
+                const res = await this.fetchImpl(dsn.envelopeUrl, {
+                    method: 'POST',
+                    headers,
+                    body,
+                });
+                const status = res.status;
+                if (status >= 200 && status < 300) {
+                    this.buffer.commit();
+                    // A successful send means the shrunken chunk size did its job; go
+                    // back to full-size envelopes rather than staying degraded forever.
+                    this.chunkItems = this.maxItemsPerEnvelope;
+                    return;
+                }
+                if (status === 401 || status === 403) {
+                    this.disabled = true;
+                    this.log(`auth failed (${status}); disabling SDK`);
+                    this.buffer.commit();
+                    return;
+                }
+                if (status === 413) {
+                    // Retrying the identical body can only fail identically. Shrink the
+                    // envelope and re-buffer so the next flush makes progress; retrying
+                    // as-is wedged the transport permanently once the queue was full.
+                    if (envelope.items.length > 1) {
+                        this.chunkItems = Math.max(1, Math.floor(envelope.items.length / 2));
+                        this.buffer.restore();
+                        this.log(`ingest returned 413; halving envelope to ${this.chunkItems} item(s)`);
+                        return;
+                    }
+                    // A single item that still doesn't fit never will.
+                    this.log('ingest returned 413 for a single item; dropping it');
+                    this.buffer.commit();
+                    this.chunkItems = this.maxItemsPerEnvelope;
+                    return;
+                }
+                if (!isRetryableStatus(status)) {
+                    this.log(`ingest returned ${status}; dropping ${envelope.items.length} item(s)`);
+                    this.buffer.commit();
+                    return;
+                }
+                // Retryable HTTP status.
+                if (status === 429) {
+                    retryAfterMs = parseRetryAfter(res.headers?.get('retry-after'), Date.now());
+                }
+                this.log(`ingest returned ${status}; will retry (attempt ${attempt + 1})`);
+            }
+            catch (err) {
+                // Network-level failure — retryable.
+                this.log(`transport error: ${String(err)} (attempt ${attempt + 1})`);
+            }
+            if (attempt >= this.maxRetries) {
+                // Out of retries: keep the batch buffered for a later flush / restart
+                // rather than dropping it on the floor.
+                this.buffer.restore();
+                this.log(`giving up after ${attempt + 1} attempt(s); re-buffering batch`);
+                return;
+            }
+            const delay = retryAfterMs ?? this.backoffDelay(attempt);
+            await this.sleep(Math.min(delay, RETRY_CAP_MS));
+            attempt += 1;
+        }
+    }
+    /** Exponential backoff with equal-jitter, capped at {@link RETRY_CAP_MS}. */
+    backoffDelay(attempt) {
+        const exp = Math.min(RETRY_CAP_MS, this.retryBaseMs * 2 ** attempt);
+        const half = exp / 2;
+        return Math.min(RETRY_CAP_MS, half + this.random() * half);
+    }
+    /** Flush then stop the timer. After close the transport still accepts a
+     * final manual `flush`, but the background timer no longer fires. */
+    async close() {
+        await this.flush();
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.flushChain;
+    }
+    log(message) {
+        if (this.config.debug) {
+            // eslint-disable-next-line no-console
+            console.warn(`[sauron] ${message}`);
+        }
+    }
+}