@wtfalch/reporting 0.2.1 → 0.3.1

package/dist/analytics/collector.js

@@ -1,30 +1,6 @@
+import { Buckets } from '../ingest-limit.js';
 import { ANALYTICS_LIMITS, beaconBatchSchema, clampOccurredAt, countryOf, deviceOf, normalisePath, referrerHostOf, } from './schema.js';
 import { insertAnalytics } from './write.js';
-/** A per-process token bucket, enough to bound abuse, never to meter. */
-class Buckets {
-    perMinute;
-    now;
-    buckets = new Map();
-    constructor(perMinute, now) {
-        this.perMinute = perMinute;
-        this.now = now;
-    }
-    take(key, n) {
-        const t = this.now().getTime();
-        const b = this.buckets.get(key) ?? { tokens: this.perMinute, at: t };
-        b.tokens = Math.min(this.perMinute, b.tokens + ((t - b.at) / 60_000) * this.perMinute);
-        b.at = t;
-        if (b.tokens < n) {
-            this.buckets.set(key, b);
-            return false;
-        }
-        b.tokens -= n;
-        this.buckets.set(key, b);
-        if (this.buckets.size > 10_000)
-            this.buckets.clear();
-        return true;
-    }
-}
 const NO_CONTENT = () => new Response(null, { status: 204 });
 /**
  * The collector: a public route handler over the Web `Request`. Always 204,

package/dist/browser/index.d.ts

@@ -12,6 +12,12 @@
  * the session id lives in `sessionStorage` under `consented`/`always` and in
  * memory under `none`. Nothing about the browser is stored beyond that.
  *
+ * With `errors: true` (docs/plans/errors.md, "Surface"), the beacon also
+ * listens for `window.onerror` and `unhandledrejection` and posts them to
+ * `errorCollector` with the same transport and batching as everything
+ * above — capped at 5 distinct errors and 20 sends total per page load, so
+ * a render loop throwing every frame cannot become a request flood.
+ *
  * No dependencies, no globals beyond `window`; under 3 KB gzipped.
  */
 export type ConsentMode = 'none' | 'consented' | 'always';
@@ -28,6 +34,10 @@ export interface BeaconOptions {
     /** For tests: the window to observe and the transport to post with. */
     readonly window?: Window;
     readonly send?: (url: string, body: string) => void;
+    /** `window.onerror` + `unhandledrejection`, capped and de-duplicated. Default false. */
+    readonly errors?: boolean;
+    /** The route `clientErrorHandler` (./next) is mounted at. Required when `errors` is true. */
+    readonly errorCollector?: string;
 }
 export interface Beacon {
     track(name: string, props?: Record<string, string | number | boolean | null>): void;
@@ -37,6 +47,14 @@ export interface Beacon {
     decline(): void;
     answer(): ConsentAnswer;
     visitorId(): string | null;
+    /**
+     * Report an error the browser never threw at `window` -- the one a React
+     * error boundary caught, which is swallowed before `window.onerror` can
+     * see it, and is exactly the case `error.tsx` exists for. Subject to the
+     * same de-duplication and the same per-page caps as a thrown one; a no-op
+     * when `errors` is off.
+     */
+    captureError(error: unknown, kind?: string): void;
     flush(): void;
     destroy(): void;
 }

package/dist/browser/index.js

@@ -12,6 +12,12 @@
  * the session id lives in `sessionStorage` under `consented`/`always` and in
  * memory under `none`. Nothing about the browser is stored beyond that.
  *
+ * With `errors: true` (docs/plans/errors.md, "Surface"), the beacon also
+ * listens for `window.onerror` and `unhandledrejection` and posts them to
+ * `errorCollector` with the same transport and batching as everything
+ * above — capped at 5 distinct errors and 20 sends total per page load, so
+ * a render loop throwing every frame cannot become a request flood.
+ *
  * No dependencies, no globals beyond `window`; under 3 KB gzipped.
  */
 const COOKIE = '_rp';
@@ -118,6 +124,131 @@ export function createBeacon(options) {
         else if (!timer)
             timer = setTimeout(flush, flushMs);
     }
+    // Errors: window.onerror + unhandledrejection, capped and de-duplicated
+    // (docs/plans/errors.md, "Surface"). A render loop throwing every frame
+    // must not become a request flood: at most 5 distinct errors — by kind +
+    // message + first stack line — and 20 sends total are ever posted per
+    // page load; a repeat past the first occurrence only bumps a counter
+    // kept in memory, never resent. Same transport, same batching and the
+    // same destroy() teardown as the queue above.
+    const ERROR_DISTINCT_MAX = 5;
+    const ERROR_TOTAL_MAX = 20;
+    let errCleanup = null;
+    let recordError = null;
+    if (options.errors && options.errorCollector) {
+        const errorCollector = options.errorCollector;
+        const seen = new Map();
+        let total = 0;
+        const errQueue = [];
+        let errTimer = null;
+        function errFlush() {
+            if (errTimer) {
+                clearTimeout(errTimer);
+                errTimer = null;
+            }
+            if (errQueue.length === 0)
+                return;
+            const errors = errQueue.splice(0, batchSize);
+            const body = JSON.stringify({ site: options.site, errors });
+            try {
+                send(errorCollector, body);
+            }
+            catch {
+                // Same rule as the transport above: never throw into the page.
+            }
+            if (errQueue.length > 0)
+                errFlush();
+        }
+        function errPush(entry) {
+            errQueue.push(entry);
+            if (errQueue.length >= batchSize)
+                errFlush();
+            else if (!errTimer)
+                errTimer = setTimeout(errFlush, flushMs);
+        }
+        // A query string can carry a token; a stack's frame URLs are the only
+        // place one could hide here, stripped exactly as the collector strips
+        // one from a pathname (analytics/schema.ts's normalisePath).
+        function stripQuery(text) {
+            return text.replace(/\?[^\s:)]*/g, '');
+        }
+        // The literal first line of `.stack` is just `kind: message` again
+        // (V8) or, on Firefox, already a frame; either way the second line is
+        // the first real call frame when there is one — what actually tells
+        // two same-kind, same-message errors apart.
+        function firstStackLine(stack) {
+            if (!stack)
+                return '';
+            const lines = stack.split('\n');
+            return (lines[1] ?? lines[0] ?? '').trim();
+        }
+        function record(kind, message, stack) {
+            const cleanMessage = stripQuery(message);
+            const cleanStack = stack === null ? null : stripQuery(stack);
+            const key = `${kind}\u0000${cleanMessage}\u0000${firstStackLine(cleanStack)}`;
+            const count = seen.get(key);
+            if (count !== undefined) {
+                seen.set(key, count + 1);
+                return; // a repeat: counted, never resent.
+            }
+            if (seen.size >= ERROR_DISTINCT_MAX || total >= ERROR_TOTAL_MAX)
+                return;
+            seen.set(key, 1);
+            total += 1;
+            errPush({ kind, message: cleanMessage, stack: cleanStack });
+        }
+        function describeReason(reason, fallbackKind) {
+            if (reason instanceof Error) {
+                return {
+                    kind: reason.name || fallbackKind,
+                    message: reason.message || fallbackKind,
+                    stack: typeof reason.stack === 'string' ? reason.stack : null,
+                };
+            }
+            if (typeof reason === 'string')
+                return { kind: fallbackKind, message: reason, stack: null };
+            try {
+                return {
+                    kind: fallbackKind,
+                    message: JSON.stringify(reason) ?? String(reason),
+                    stack: null,
+                };
+            }
+            catch {
+                return { kind: fallbackKind, message: fallbackKind, stack: null };
+            }
+        }
+        recordError = (error, kind) => {
+            const info = describeReason(error, kind ?? 'Error');
+            record(info.kind, info.message, info.stack);
+        };
+        const onError = (event) => {
+            // A cross-origin script with no CORS grant reports exactly this
+            // message, with no line, column or Error object: nothing here is
+            // useful, and every throw from a foreign <script> would otherwise
+            // repeat it.
+            if (event.message === 'Script error.')
+                return;
+            if (event.error instanceof Error || typeof event.error === 'string') {
+                const info = describeReason(event.error, 'Error');
+                record(info.kind, info.message, info.stack);
+            }
+            else {
+                record('Error', event.message || 'Error', null);
+            }
+        };
+        const onRejection = (event) => {
+            const info = describeReason(event.reason, 'UnhandledRejection');
+            record(info.kind, info.message, info.stack);
+        };
+        win.addEventListener('error', onError);
+        win.addEventListener('unhandledrejection', onRejection);
+        errCleanup = () => {
+            errFlush();
+            win.removeEventListener('error', onError);
+            win.removeEventListener('unhandledrejection', onRejection);
+        };
+    }
     const pathOf = () => win.location.pathname || '/';
     let currentPath = pathOf();
     let enteredAt = Date.now();
@@ -190,9 +321,11 @@ export function createBeacon(options) {
         },
         answer: () => answer,
         visitorId: () => (declined() ? null : (cookie?.id ?? null)),
+        captureError: (error, kind) => recordError?.(error, kind),
         flush,
         destroy() {
             flush();
+            errCleanup?.();
             history.pushState = pushState;
             history.replaceState = replaceState;
             win.removeEventListener('popstate', onPop);

package/dist/errors/capture.d.ts

@@ -0,0 +1,52 @@
+import type { CaptureContext, Db, EventInput, Logger } from '../types.js';
+/**
+ * The one path an uncaught exception takes into the estate
+ * (docs/plans/errors.md, "Surface" and "Why a second table, not just an
+ * event row"): one `reporting_events` row for the timeline, through the
+ * writer's own `event()` so it shares its queue, batching and logger line,
+ * and one upsert into the fingerprint's group — first seen, last seen, how
+ * many, and whether an operator has already dealt with it.
+ *
+ * Two contracts this must never break, both sharpened from the writer's own
+ * (writer.ts's header comment) for an error reporter specifically:
+ *
+ * 1. A capture must never carry a secret. Redaction runs on `message` and
+ *    `stack` before anything else touches them — a stack is the likeliest
+ *    way a wrapping key leaves the process (redact.ts) — and the
+ *    fingerprint is computed on that same redacted text, so a secret can
+ *    never reach the digest basis either.
+ * 2. A capture must never throw back into the code that threw the original
+ *    error. The whole body of `captureError` is one try/catch, and the
+ *    group upsert — the one part of this that touches a database that can
+ *    be down — is scheduled through the host's `defer` and wrapped in its
+ *    own catch, exactly as the writer's flush protects the request from a
+ *    failed insert. An error reporter that itself throws while reporting an
+ *    error is the one failure mode worse than not reporting it.
+ */
+export interface CaptureOptions {
+    readonly db: Db;
+    readonly log: Logger;
+    readonly site: string;
+    readonly now: () => Date;
+    /** Runs the group upsert after the current unit of work, same as the writer's flush (writer.ts). */
+    readonly defer: (fn: () => Promise<void>) => void;
+    /** The Writer's own `event()`, so the timeline row shares its queue, batching and logger line. */
+    readonly event: (input: EventInput) => void;
+    /** Stamped on a fresh group when a capture's own context supplies none. */
+    readonly release?: string | null;
+}
+/**
+ * `captureError(error, context?)`: the class from `errorKind` (or the
+ * context's own, when the caller already knows it), the message and stack
+ * from the value itself — never assuming it is an `Error` — redacted before
+ * anything else touches them, bounded to what the table accepts, then
+ * fingerprinted on that same redacted, bounded text so a secret can never
+ * reach the digest either.
+ *
+ * Writes the timeline row synchronously through `o.event()` (the writer
+ * queues and logs it), then schedules the group upsert through `o.defer` —
+ * no timer of its own, same as the writer's flush. The whole body is one
+ * try/catch: nothing here may throw back into the code that threw the
+ * original error.
+ */
+export declare function createCapture(o: CaptureOptions): (error: unknown, context?: CaptureContext) => void;

package/dist/errors/capture.js

@@ -0,0 +1,187 @@
+import { sql } from 'drizzle-orm';
+import { ERROR_RUNTIMES, KIND_PATTERN, LIMITS } from '../schema.js';
+import { reportingErrors } from '../tables.js';
+import { describe } from '../writer.js';
+import { errorKind, fingerprint } from './fingerprint.js';
+import { heldSecrets, redactText } from './redact.js';
+const CAMEL_BOUNDARY = /([a-z0-9])([A-Z])/g;
+const INVALID_KIND_CHARS = /[^a-z0-9_]+/g;
+/** camelCase/PascalCase/anything, folded down to what `KIND_PATTERN` allows. */
+function snakeCase(name) {
+    const lowered = name.replace(CAMEL_BOUNDARY, '$1_$2').toLowerCase();
+    return lowered
+        .replace(INVALID_KIND_CHARS, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+/**
+ * `error.<snake_case class name>` for the timeline row's `kind`. Falls back
+ * to `error.unknown` rather than refuse the capture: a class name that
+ * cannot become a valid `namespace.name` once lower-cased (it leads with a
+ * digit, or is nothing but punctuation) is itself informative, but not worth
+ * losing the whole report over.
+ */
+function eventKindFor(kind) {
+    const candidate = `error.${snakeCase(kind)}`;
+    return KIND_PATTERN.test(candidate) ? candidate : 'error.unknown';
+}
+/** `errorKind(error)`, unless the caller already knows the class better than the thrown value can say (a JSON-serialised browser report, say). */
+function resolveKind(error, override) {
+    const trimmed = override?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed.slice(0, 100) : errorKind(error);
+}
+/** Safe for every throw JavaScript actually allows: a string, `null`, an object with no message at all. Never empty, so it always clears the table's and the schema's non-empty checks. */
+function messageOf(error, kind) {
+    if (error instanceof Error)
+        return error.message || error.name || kind;
+    if (typeof error === 'string')
+        return error || kind;
+    if (error === null)
+        return 'null';
+    if (error === undefined)
+        return 'undefined';
+    try {
+        return String(error) || kind;
+    }
+    catch {
+        return kind;
+    }
+}
+/** Only a real `Error` has a stack worth keeping; everything else groups on `kind` and the message alone (fingerprint.ts). */
+function stackOf(error) {
+    return error instanceof Error && typeof error.stack === 'string' ? error.stack : null;
+}
+/** Keeps the top of the text — the start, where the throw site and its callers are — and drops the rest. */
+function truncateEnd(text, max) {
+    return text.length > max ? text.slice(0, max) : text;
+}
+/**
+ * `reporting_errors.tenant_id` is a uuid column and the event row's schema
+ * refuses anything else, so a caller that hands over a slug, an empty string
+ * or a number loses the whole group row rather than just the attribution.
+ * Callers are not all trusted to the same degree -- `./next`'s client ingest
+ * takes what a browser posted -- so the guard lives here, at the one door
+ * every capture goes through.
+ */
+function validTenant(value) {
+    return typeof value === 'string' && UUID.test(value) ? value : null;
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function normaliseRuntime(runtime) {
+    return runtime && ERROR_RUNTIMES.includes(runtime) ? runtime : 'server';
+}
+/**
+ * `insert ... on conflict (fingerprint) do update`, one round trip so two
+ * occurrences arriving at once still land as one row: bump `occurrences`,
+ * move `last_seen_at`, overwrite the sample fields with the newest
+ * occurrence. `first_seen_at` is left out of `set` entirely, so a conflict
+ * never moves it.
+ *
+ * A resolved or ignored group reopens: the pair the table's own CHECK
+ * enforces (`reporting_errors_resolved_pair_check`, 0003_errors.sql) means
+ * `state` can only move back to 'open' by clearing `resolved_at` and
+ * `resolved_by` in the same statement, never one alone.
+ */
+async function upsertGroup(db, site, s) {
+    const reopened = sql `case when ${reportingErrors.state} in ('resolved', 'ignored') then 'open' else ${reportingErrors.state} end`;
+    await db
+        .insert(reportingErrors)
+        .values({
+        fingerprint: s.fingerprint,
+        site,
+        kind: s.kind,
+        message: s.message,
+        stack: s.stack,
+        runtime: s.runtime,
+        release: s.release,
+        firstSeenAt: s.at,
+        lastSeenAt: s.at,
+        occurrences: 1,
+        tenantId: s.tenantId,
+        requestId: s.requestId,
+    })
+        .onConflictDoUpdate({
+        target: reportingErrors.fingerprint,
+        set: {
+            occurrences: sql `${reportingErrors.occurrences} + 1`,
+            lastSeenAt: s.at,
+            message: s.message,
+            stack: s.stack,
+            tenantId: s.tenantId,
+            requestId: s.requestId,
+            release: s.release,
+            state: reopened,
+            resolvedAt: sql `case when ${reportingErrors.state} in ('resolved', 'ignored') then null else ${reportingErrors.resolvedAt} end`,
+            resolvedBy: sql `case when ${reportingErrors.state} in ('resolved', 'ignored') then null else ${reportingErrors.resolvedBy} end`,
+        },
+    });
+}
+/**
+ * `captureError(error, context?)`: the class from `errorKind` (or the
+ * context's own, when the caller already knows it), the message and stack
+ * from the value itself — never assuming it is an `Error` — redacted before
+ * anything else touches them, bounded to what the table accepts, then
+ * fingerprinted on that same redacted, bounded text so a secret can never
+ * reach the digest either.
+ *
+ * Writes the timeline row synchronously through `o.event()` (the writer
+ * queues and logs it), then schedules the group upsert through `o.defer` —
+ * no timer of its own, same as the writer's flush. The whole body is one
+ * try/catch: nothing here may throw back into the code that threw the
+ * original error.
+ */
+export function createCapture(o) {
+    return function captureError(error, context = {}) {
+        try {
+            const kind = resolveKind(error, context.kind);
+            const secrets = heldSecrets(process.env);
+            const message = truncateEnd(redactText(messageOf(error, kind), secrets), LIMITS.message);
+            const rawStack = stackOf(error);
+            const stack = rawStack === null ? null : truncateEnd(redactText(rawStack, secrets), LIMITS.stack);
+            const fp = fingerprint({ kind, message, stack });
+            const runtime = normaliseRuntime(context.runtime);
+            // A tenant id that is not a uuid would be refused by the event row's
+            // own zod check (schema.ts: `tenantId: z.uuid().nullish()`) and would
+            // fail the group upsert at Postgres's cast, which is caught, logged and
+            // dropped -- leaving an occurrence with a timeline row and no group.
+            // The attribution is worth less than the report, so a malformed id is
+            // dropped and the capture goes on.
+            const tenantId = validTenant(context.tenantId);
+            const requestId = context.requestId ?? null;
+            const release = context.release ?? o.release ?? null;
+            const at = o.now();
+            o.event({
+                kind: eventKindFor(kind),
+                level: 'error',
+                message,
+                tenantId,
+                requestId,
+                data: { fingerprint: fp, runtime },
+            });
+            const sample = {
+                fingerprint: fp,
+                kind,
+                message,
+                stack,
+                runtime,
+                release,
+                tenantId,
+                requestId,
+                at,
+            };
+            try {
+                o.defer(() => upsertGroup(o.db, o.site, sample).catch((err) => {
+                    o.log.error({ err: describe(err), fingerprint: fp }, 'reporting: error group upsert failed');
+                }));
+            }
+            catch (err) {
+                // A host's defer that throws (called outside a request scope, say)
+                // must not take the report with it, same as writer.ts's schedule().
+                o.log.warn({ err: describe(err) }, 'reporting: defer threw; the error group upsert was dropped');
+            }
+        }
+        catch (err) {
+            o.log.error({ err: describe(err) }, 'reporting: captureError failed');
+        }
+    };
+}

package/dist/errors/fingerprint.d.ts

@@ -0,0 +1,36 @@
+/**
+ * One V8 stack frame to its stable identity: the function name (if any) and
+ * the location, with everything that drifts for reasons unrelated to the
+ * bug removed.
+ *
+ * Handles both formats Node/V8 produce:
+ *   at functionName (/path/to/file.ts:10:5)
+ *   at /path/to/file.ts:10:5
+ */
+export declare function normaliseFrame(frame: string): string;
+/**
+ * The group an error belongs to: sha256 over the kind and the top five
+ * normalised frames, truncated to 32 lower-case hex characters. Five frames
+ * because the throw site and its immediate callers are what identifies a
+ * bug; frames further up are shared by every request and add nothing but
+ * noise a coincidental match in them could exploit.
+ *
+ * Falls back to `kind + masked message` when there is no stack at all, or
+ * the stack has no line this package recognises as a frame (a non-V8
+ * runtime, or a stack someone already stripped).
+ */
+export declare function fingerprint(input: {
+    kind: string;
+    message: string;
+    stack?: string | null;
+}): string;
+/**
+ * The class name a `kind` column and a fingerprint are built from —
+ * `TypeError`, `ZodError` — bounded so a pathological name cannot blow out
+ * the 512-character message column it eventually contributes to, and safe
+ * for the throws JavaScript actually allows: a string, `null`, an object
+ * with no prototype at all. None of those may throw out of this function;
+ * an error reporter that itself throws while reporting an error is the one
+ * failure mode worse than not reporting it.
+ */
+export declare function errorKind(error: unknown): string;