@realuptime/errors 0.4.0

package/dist/buffer.js

@@ -0,0 +1,42 @@
+/**
+ * Bounded in-memory event buffer, modelled on apps/agent/buffer.ts: oldest
+ * dropped when full, every drop counted, and the count is reported in the
+ * next successful batch (`droppedClient` on the wire) so even client-side
+ * drops reach the product's visible drop counters. In-memory only; an error
+ * SDK that writes to the customer's filesystem is over the line.
+ */
+export const BUFFER_MAX = 200;
+export class EventBuffer {
+    events = [];
+    droppedSinceReport = 0;
+    push(event) {
+        if (this.events.length >= BUFFER_MAX) {
+            this.events.shift();
+            this.droppedSinceReport += 1;
+        }
+        this.events.push(event);
+    }
+    get length() {
+        return this.events.length;
+    }
+    /** Reads up to `n` events without removing them; `commit(n)` removes them
+     * only after the server acknowledged the batch, so a failed delivery
+     * retries the same events instead of losing them. */
+    peekBatch(n) {
+        return this.events.slice(0, n);
+    }
+    commit(n) {
+        this.events.splice(0, n);
+    }
+    /** The drop count to carry on the NEXT batch. Taken (reset to zero) only
+     * when the caller is about to put it on the wire; if that delivery fails
+     * the caller must give it back via `restoreDropped`. */
+    takeDropped() {
+        const n = this.droppedSinceReport;
+        this.droppedSinceReport = 0;
+        return n;
+    }
+    restoreDropped(n) {
+        this.droppedSinceReport += n;
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,53 @@
+import { type WireEvent } from "./types.ts";
+/**
+ * Delivery: batched, buffered, backed off, and incapable of crashing the
+ * host app (docs/errors-plan.md, "The SDKs"). Disciplines inherited from
+ * apps/agent/api.ts and runtime.ts:
+ *
+ *   - Failures never throw out of the SDK. Everything is caught; the first
+ *     failure of each kind logs ONCE and further ones are silent, because
+ *     an error tracker that floods the console is nearly as bad as one that
+ *     throws.
+ *   - Transient failures (network, 5xx, unparseable body) back off
+ *     exponentially and the events stay buffered.
+ *   - `over_quota` responses stop delivery until the reset instant the
+ *     server names. Retrying into a hard cap burns the customer's cycles
+ *     and our ingest budget for nothing; the drop already happened and is
+ *     already counted server-side.
+ *   - `key_revoked` (403) disables the SDK for the process lifetime after
+ *     one log line naming the fix. A revoked key never becomes an event
+ *     black hole or a retry storm.
+ *   - `rate_limited` (429) is transient: back off and keep the events.
+ */
+export declare const SEND_TIMEOUT_MS = 10000;
+export declare const BACKOFF_START_MS = 5000;
+export declare const BACKOFF_MAX_MS = 300000;
+export interface TransportOptions {
+    endpoint: string;
+    sdk: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    log?: (message: string) => void;
+}
+export declare class Transport {
+    private readonly options;
+    private readonly buffer;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly log;
+    private backoffMs;
+    private nextAttemptAt;
+    private pausedUntil;
+    private disabled;
+    private loggedKinds;
+    private inFlight;
+    constructor(options: TransportOptions);
+    enqueue(event: WireEvent): void;
+    /** Sends what is due. Serialized: one delivery in flight at a time, so a
+     * burst of captures becomes one batch, not a request per event. */
+    flush(): Promise<void>;
+    private logOnce;
+    private deliver;
+    private pauseUntil;
+    private backOff;
+}

package/dist/client.js

@@ -0,0 +1,151 @@
+import { EventBuffer } from "./buffer.js";
+import { MAX_EVENTS_PER_BATCH } from "./types.js";
+/**
+ * Delivery: batched, buffered, backed off, and incapable of crashing the
+ * host app (docs/errors-plan.md, "The SDKs"). Disciplines inherited from
+ * apps/agent/api.ts and runtime.ts:
+ *
+ *   - Failures never throw out of the SDK. Everything is caught; the first
+ *     failure of each kind logs ONCE and further ones are silent, because
+ *     an error tracker that floods the console is nearly as bad as one that
+ *     throws.
+ *   - Transient failures (network, 5xx, unparseable body) back off
+ *     exponentially and the events stay buffered.
+ *   - `over_quota` responses stop delivery until the reset instant the
+ *     server names. Retrying into a hard cap burns the customer's cycles
+ *     and our ingest budget for nothing; the drop already happened and is
+ *     already counted server-side.
+ *   - `key_revoked` (403) disables the SDK for the process lifetime after
+ *     one log line naming the fix. A revoked key never becomes an event
+ *     black hole or a retry storm.
+ *   - `rate_limited` (429) is transient: back off and keep the events.
+ */
+export const SEND_TIMEOUT_MS = 10_000;
+export const BACKOFF_START_MS = 5_000;
+export const BACKOFF_MAX_MS = 300_000;
+export class Transport {
+    options;
+    buffer = new EventBuffer();
+    fetchImpl;
+    now;
+    log;
+    backoffMs = 0;
+    nextAttemptAt = 0;
+    pausedUntil = 0;
+    disabled = false;
+    loggedKinds = new Set();
+    inFlight = null;
+    constructor(options) {
+        this.options = options;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.now = options.now ?? Date.now;
+        this.log = options.log ?? ((message) => console.error(message));
+    }
+    enqueue(event) {
+        if (this.disabled)
+            return;
+        this.buffer.push(event);
+        void this.flush();
+    }
+    /** Sends what is due. Serialized: one delivery in flight at a time, so a
+     * burst of captures becomes one batch, not a request per event. */
+    flush() {
+        if (this.inFlight)
+            return this.inFlight;
+        this.inFlight = this.deliver().finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+    logOnce(kind, message) {
+        if (this.loggedKinds.has(kind))
+            return;
+        this.loggedKinds.add(kind);
+        this.log(`[realuptime-errors] ${message}`);
+    }
+    async deliver() {
+        while (this.buffer.length > 0) {
+            const now = this.now();
+            if (this.disabled || now < this.nextAttemptAt || now < this.pausedUntil)
+                return;
+            const events = this.buffer.peekBatch(MAX_EVENTS_PER_BATCH);
+            const droppedClient = this.buffer.takeDropped();
+            const batch = { sdk: this.options.sdk, droppedClient, events };
+            let response;
+            try {
+                response = await this.fetchImpl(this.options.endpoint, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify(batch),
+                    signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+                });
+            }
+            catch {
+                this.buffer.restoreDropped(droppedClient);
+                this.backOff("network", "cannot reach the ingest endpoint; buffering and retrying");
+                return;
+            }
+            if (response.ok) {
+                this.buffer.commit(events.length);
+                this.backoffMs = 0;
+                this.nextAttemptAt = 0;
+                let body = null;
+                try {
+                    body = (await response.json());
+                }
+                catch {
+                    body = null;
+                }
+                if (body?.overQuota) {
+                    this.pauseUntil(body.quota?.resetsAt);
+                    this.logOnce("over-quota", `monthly event quota reached (${body.quota?.limit ?? "?"}); pausing until ${body.quota?.resetsAt ?? "the window resets"}. Dropped events are counted and shown on your realuptime Errors dashboard.`);
+                    return;
+                }
+                continue;
+            }
+            let refusal = {};
+            try {
+                refusal = (await response.json());
+            }
+            catch {
+                refusal = {};
+            }
+            if (response.status === 403 && refusal.reason === "key_revoked") {
+                this.disabled = true;
+                this.logOnce("revoked", "this project's ingest key was revoked; error reporting is disabled for this process. Rotate the key in realuptime Errors settings and redeploy with the new DSN.");
+                return;
+            }
+            if (response.status === 429 && refusal.reason === "over_quota") {
+                // The whole batch was refused at the cap: nothing was written, and
+                // holding the events would only re-refuse them all window long.
+                this.buffer.commit(events.length);
+                this.pauseUntil(refusal.resetsAt);
+                this.logOnce("over-quota", `monthly event quota reached; pausing until ${refusal.resetsAt ?? "the window resets"}. Dropped events are counted and shown on your realuptime Errors dashboard.`);
+                return;
+            }
+            if (response.status === 400) {
+                // A malformed batch will never become well-formed by retrying; drop
+                // it rather than wedging the buffer, and say so once.
+                this.buffer.commit(events.length);
+                this.buffer.restoreDropped(droppedClient);
+                this.logOnce("malformed", `the server refused a batch as malformed: ${refusal.error ?? "no detail"}. This is an SDK bug worth reporting.`);
+                continue;
+            }
+            this.buffer.restoreDropped(droppedClient);
+            this.backOff("transient", `ingest endpoint answered ${response.status}; buffering and retrying`);
+            return;
+        }
+    }
+    pauseUntil(resetsAt) {
+        const parsed = resetsAt ? Date.parse(resetsAt) : Number.NaN;
+        // A missing or unparseable reset instant still pauses meaningfully: an
+        // hour is long enough to stop the burn, short enough to recover early
+        // in a new window.
+        this.pausedUntil = Number.isFinite(parsed) ? parsed : this.now() + 60 * 60_000;
+    }
+    backOff(kind, message) {
+        this.backoffMs = this.backoffMs <= 0 ? BACKOFF_START_MS : Math.min(this.backoffMs * 2, BACKOFF_MAX_MS);
+        this.nextAttemptAt = this.now() + this.backoffMs;
+        this.logOnce(kind, `${message} (backing off).`);
+    }
+}

package/dist/custom-scrub.d.ts

@@ -0,0 +1,48 @@
+import type { WireEvent } from "./types.ts";
+/**
+ * Customer-defined ADDITIONAL scrub rules, client side (REA-264). The rules
+ * a project's owner set in the realuptime Errors settings are fetched once
+ * at init (see index.ts, `fetchScrubRules`) and applied here AFTER the
+ * default scrub (scrub.ts), never instead of it. There is nothing in this
+ * file that can relax a default: a rule can only add a field name, a key
+ * glob, or a value regex that turns more into `[scrubbed]`.
+ *
+ * DUPLICATED from packages/db/error-scrub-rules.ts, the scrub.ts
+ * convention: this package must stay import-free. custom-scrub-vectors.json
+ * pins the two (and the Python SDK) to byte-identical output; a semantic
+ * change is a three-implementation change.
+ *
+ * The validator is carried here too, even though rules only ever arrive
+ * from our own endpoint, because "only ever" is not a guarantee the host
+ * app should depend on: a rule that fails the same safe-subset check the
+ * server applies is skipped, so no network response can hand this process
+ * a catastrophic-backtracking pattern.
+ */
+export type CustomScrubRuleKind = "field_name" | "key_glob" | "value_regex";
+export interface CustomScrubRule {
+    kind: CustomScrubRuleKind;
+    pattern: string;
+}
+/** Most rules a response may carry; matches the server's per-project cap. */
+export declare const MAX_CUSTOM_SCRUB_RULES = 50;
+export declare function validateCustomScrubRule(input: {
+    kind: unknown;
+    pattern: unknown;
+}): boolean;
+export interface CompiledCustomScrubRules {
+    matchesKey: (name: string) => boolean;
+    valueRegexes: RegExp[];
+    count: number;
+}
+/** Compiles rules, skipping any that fail validation. Never throws. */
+export declare function compileCustomScrubRules(rules: readonly unknown[]): CompiledCustomScrubRules;
+export declare const NO_CUSTOM_SCRUB_RULES: CompiledCustomScrubRules;
+/** Applies compiled rules to an event that has ALREADY been through
+ * scrubEvent. Returns a new object; never mutates the input. */
+export declare function applyCustomScrubRules(event: WireEvent, compiled: CompiledCustomScrubRules): WireEvent;
+/**
+ * The rules endpoint for a DSN: the ingest URL with `/ingest/` swapped for
+ * `/scrub-rules/`. Returns null for a DSN that is not ingest-shaped, in
+ * which case no fetch is attempted and the defaults run alone.
+ */
+export declare function scrubRulesUrlFor(dsn: string): string | null;

package/dist/custom-scrub.js

@@ -0,0 +1,262 @@
+import { SCRUBBED } from "./scrub.js";
+const KINDS = ["field_name", "key_glob", "value_regex"];
+const MAX_PATTERN_LENGTH = 200;
+const MAX_QUANTIFIERS = 10;
+const MAX_REPEAT = 100;
+/** Most rules a response may carry; matches the server's per-project cap. */
+export const MAX_CUSTOM_SCRUB_RULES = 50;
+export function validateCustomScrubRule(input) {
+    if (typeof input?.kind !== "string" || !KINDS.includes(input.kind))
+        return false;
+    if (typeof input.pattern !== "string")
+        return false;
+    const pattern = input.pattern;
+    if (pattern.trim().length === 0 || pattern.length > MAX_PATTERN_LENGTH)
+        return false;
+    if (/[\r\n]/.test(pattern))
+        return false;
+    if (input.kind === "field_name" || input.kind === "key_glob") {
+        if (pattern !== pattern.trim())
+            return false;
+        const hasWildcard = /[*?]/.test(pattern);
+        return input.kind === "key_glob" ? hasWildcard : !hasWildcard;
+    }
+    return safeRegex(pattern);
+}
+function safeRegex(pattern) {
+    const groupHasQuantifier = [];
+    let quantifiers = 0;
+    let inClass = false;
+    let lastClosedGroupHadQuantifier = false;
+    let lastWasQuantifier = false;
+    let lastWasAtom = false;
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "\\") {
+            const next = pattern[i + 1];
+            if (next === undefined)
+                return false;
+            if (/[1-9]/.test(next) || next === "k")
+                return false;
+            if (next === "p" || next === "P" || next === "u" || next === "c")
+                return false;
+            i += 1;
+            if (!inClass) {
+                lastWasAtom = true;
+                lastWasQuantifier = false;
+                lastClosedGroupHadQuantifier = false;
+            }
+            continue;
+        }
+        if (inClass) {
+            if (ch === "]")
+                inClass = false;
+            continue;
+        }
+        if (ch === "[") {
+            inClass = true;
+            if (pattern[i + 1] === "^")
+                i += 1;
+            if (pattern[i + 1] === "]")
+                i += 1;
+            lastWasAtom = true;
+            lastWasQuantifier = false;
+            lastClosedGroupHadQuantifier = false;
+            continue;
+        }
+        if (ch === "(") {
+            if (pattern[i + 1] === "?") {
+                if (pattern[i + 2] !== ":")
+                    return false;
+                i += 2;
+            }
+            groupHasQuantifier.push(false);
+            lastWasAtom = false;
+            lastWasQuantifier = false;
+            lastClosedGroupHadQuantifier = false;
+            continue;
+        }
+        if (ch === ")") {
+            const had = groupHasQuantifier.pop();
+            if (had === undefined)
+                return false;
+            lastClosedGroupHadQuantifier = had;
+            if (had && groupHasQuantifier.length > 0)
+                groupHasQuantifier[groupHasQuantifier.length - 1] = true;
+            lastWasAtom = true;
+            lastWasQuantifier = false;
+            continue;
+        }
+        const isBrace = ch === "{";
+        if (ch === "*" || ch === "+" || ch === "?" || isBrace) {
+            if (isBrace) {
+                const close = pattern.indexOf("}", i);
+                const body = close === -1 ? null : pattern.slice(i + 1, close);
+                const m = body === null ? null : /^(\d+)(?:,(\d*))?$/.exec(body);
+                if (!m) {
+                    lastWasAtom = true;
+                    lastWasQuantifier = false;
+                    lastClosedGroupHadQuantifier = false;
+                    continue;
+                }
+                const lo = Number(m[1]);
+                const hi = m[2] === undefined ? lo : m[2] === "" ? Number.POSITIVE_INFINITY : Number(m[2]);
+                if (lo > MAX_REPEAT || (Number.isFinite(hi) && hi > MAX_REPEAT))
+                    return false;
+                if (Number.isFinite(hi) && hi < lo)
+                    return false;
+                i = close;
+            }
+            if (ch === "?" && lastWasQuantifier) {
+                lastWasQuantifier = false;
+                continue;
+            }
+            if (!lastWasAtom)
+                return false;
+            if (lastClosedGroupHadQuantifier)
+                return false;
+            quantifiers += 1;
+            if (quantifiers > MAX_QUANTIFIERS)
+                return false;
+            if (groupHasQuantifier.length > 0)
+                groupHasQuantifier[groupHasQuantifier.length - 1] = true;
+            lastWasAtom = false;
+            lastWasQuantifier = true;
+            lastClosedGroupHadQuantifier = false;
+            continue;
+        }
+        if (ch === "|") {
+            lastWasAtom = false;
+            lastWasQuantifier = false;
+            lastClosedGroupHadQuantifier = false;
+            continue;
+        }
+        lastWasAtom = true;
+        lastWasQuantifier = false;
+        lastClosedGroupHadQuantifier = false;
+    }
+    if (inClass || groupHasQuantifier.length > 0)
+        return false;
+    let compiled;
+    try {
+        compiled = new RegExp(pattern, "g");
+    }
+    catch {
+        return false;
+    }
+    return !new RegExp(compiled.source).test("");
+}
+function globToRegExp(glob) {
+    let out = "^";
+    for (const ch of glob) {
+        if (ch === "*")
+            out += ".*";
+        else if (ch === "?")
+            out += ".";
+        else
+            out += ch.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+    }
+    return new RegExp(`${out}$`, "i");
+}
+/** Compiles rules, skipping any that fail validation. Never throws. */
+export function compileCustomScrubRules(rules) {
+    const names = new Set();
+    const globs = [];
+    const valueRegexes = [];
+    let count = 0;
+    for (const raw of rules.slice(0, MAX_CUSTOM_SCRUB_RULES)) {
+        const rule = raw;
+        if (!rule || typeof rule !== "object" || !validateCustomScrubRule({ kind: rule.kind, pattern: rule.pattern }))
+            continue;
+        count += 1;
+        const pattern = rule.pattern;
+        if (rule.kind === "field_name")
+            names.add(pattern.toLowerCase());
+        else if (rule.kind === "key_glob")
+            globs.push(globToRegExp(pattern));
+        else
+            valueRegexes.push(new RegExp(pattern, "g"));
+    }
+    return {
+        matchesKey: (name) => {
+            const lower = name.toLowerCase();
+            if (names.has(lower))
+                return true;
+            for (const glob of globs)
+                if (glob.test(lower))
+                    return true;
+            return false;
+        },
+        valueRegexes,
+        count,
+    };
+}
+export const NO_CUSTOM_SCRUB_RULES = { matchesKey: () => false, valueRegexes: [], count: 0 };
+function applyValue(value, compiled) {
+    let out = value;
+    for (const re of compiled.valueRegexes) {
+        re.lastIndex = 0;
+        out = out.replace(re, SCRUBBED);
+    }
+    return out;
+}
+/** Applies compiled rules to an event that has ALREADY been through
+ * scrubEvent. Returns a new object; never mutates the input. */
+export function applyCustomScrubRules(event, compiled) {
+    if (compiled.count === 0)
+        return event;
+    const value = (input) => applyValue(input, compiled);
+    const entry = (name, input) => (compiled.matchesKey(name) ? SCRUBBED : value(input));
+    const map = (input, prefix = "") => {
+        const out = {};
+        for (const [name, v] of Object.entries(input))
+            out[name] = typeof v === "string" ? entry(prefix + name, v) : v;
+        return out;
+    };
+    return {
+        ...event,
+        message: value(event.message),
+        request: event.request
+            ? {
+                ...event.request,
+                ...(typeof event.request.path === "string" ? { path: value(event.request.path) } : {}),
+                ...(typeof event.request.route === "string" ? { route: value(event.request.route) } : {}),
+                ...(event.request.headers ? { headers: map(event.request.headers) } : {}),
+            }
+            : event.request,
+        breadcrumbs: event.breadcrumbs
+            ? event.breadcrumbs.map((crumb) => ({
+                ...crumb,
+                message: value(crumb.message),
+                ...(crumb.data ? { data: map(crumb.data) } : {}),
+            }))
+            : event.breadcrumbs,
+        frames: event.frames
+            ? event.frames.map((frame) => frame.contextLine != null || frame.preContext?.length || frame.postContext?.length || frame.vars
+                ? {
+                    ...frame,
+                    ...(frame.contextLine != null ? { contextLine: value(frame.contextLine) } : {}),
+                    ...(frame.preContext ? { preContext: frame.preContext.map(value) } : {}),
+                    ...(frame.postContext ? { postContext: frame.postContext.map(value) } : {}),
+                    ...(frame.vars ? { vars: map(frame.vars) } : {}),
+                }
+                : frame)
+            : event.frames,
+        ...(event.user ? { user: map(event.user, "user.") } : {}),
+        ...(event.tags ? { tags: map(event.tags) } : {}),
+        ...(event.context ? { context: map(event.context) } : {}),
+        ...(event.device ? { device: map(event.device) } : {}),
+    };
+}
+/**
+ * The rules endpoint for a DSN: the ingest URL with `/ingest/` swapped for
+ * `/scrub-rules/`. Returns null for a DSN that is not ingest-shaped, in
+ * which case no fetch is attempted and the defaults run alone.
+ */
+export function scrubRulesUrlFor(dsn) {
+    const marker = "/api/errors/v1/ingest/";
+    const at = dsn.indexOf(marker);
+    if (at === -1)
+        return null;
+    return `${dsn.slice(0, at)}/api/errors/v1/scrub-rules/${dsn.slice(at + marker.length)}`;
+}