@autter/otlp-ingester 1.5.0 → 1.6.0

package/dist/stack-frames.js

@@ -0,0 +1,441 @@
+import { detectStackLanguage } from "./fingerprint.js";
+/**
+ * Raw stack text → structured frames, INNERMOST (crash site) FIRST.
+ *
+ * The legacy `message-v1` fingerprint hashes stack lines as text, which
+ * keeps Python line numbers, takes Python's outermost frames, and counts
+ * dependency frames. `frames-v3` (fingerprint-v3.ts) hashes structured
+ * frames instead, so every supported language is parsed into the sink's
+ * StackFrame shape here, in one consistent orientation:
+ *
+ * - V8 (Node, Chrome, Edge): `at fn (file:line:col)` / `at file:line:col`
+ * - Firefox / Safari: `fn@url:line:col` / `@url:line:col`
+ * - Python: `File "…", line N, in fn` — tracebacks list the OUTERMOST frame
+ *   first, so the frames are reversed; only the last (reported) traceback
+ *   of a chained exception is used
+ * - Go: function line + `\t<file>.go:<line> +0x…`, first goroutine only
+ * - JVM: `at pkg.Class.method(File.java:N)`, first exception block only
+ *   (before `Caused by:`)
+ * - .NET: `at Ns.Type.Method(args) in <file>:line N`; for wrapped
+ *   exceptions only the frames after the last "End of inner exception"
+ * - Rust: `N: path::to::fn` + `at <file>:<line>:<col>`
+ * - Ruby / PHP best effort, so those stacks do not collapse to the message
+ *
+ * `inApp` follows the contract §3 rule (isInAppFrame). `resolved` is always
+ * false here; symbolicate.ts sets it for frames a source map resolved.
+ * Shared parity vectors: stack-parse-vectors.json.
+ */
+/** Frames kept per stack (contract §1: at most 50). */
+export const MAX_FRAMES = 50;
+const MAX_FUNCTION_CHARS = 500;
+const MAX_PATH_CHARS = 1000;
+// ── In-app rule (contract §3) ─────────────────────────────────────────────
+const NOT_IN_APP_PATH_PARTS = [
+    "node_modules/",
+    "/site-packages/",
+    "/dist-packages/",
+    "/vendor/",
+    "/.pnpm/",
+];
+const NOT_IN_APP_PATH_PREFIXES = ["node:", "internal/"];
+const EXTENSION_SCHEMES = [
+    "chrome-extension:",
+    "moz-extension:",
+    "safari-extension:",
+    "safari-web-extension:",
+    "webkit-masked-url:",
+];
+/**
+ * Path half of §3: dependency directories, Node internals and browser
+ * extension scripts are not in-app. Windows separators are normalised so
+ * `C:\app\node_modules\x.js` counts too. A frame with no path is in-app.
+ */
+export function isInAppPath(path) {
+    if (!path)
+        return true;
+    const normalized = path.replace(/\\/g, "/");
+    if (NOT_IN_APP_PATH_PARTS.some((part) => normalized.includes(part)))
+        return false;
+    if (NOT_IN_APP_PATH_PREFIXES.some((prefix) => normalized.startsWith(prefix)))
+        return false;
+    const lower = normalized.toLowerCase();
+    if (EXTENSION_SCHEMES.some((scheme) => lower.startsWith(scheme)))
+        return false;
+    return true;
+}
+/** Fully qualified name for the language rules (`module.function`). */
+function qualifiedName(frame) {
+    if (frame.module && frame.function)
+        return `${frame.module}.${frame.function}`;
+    return frame.module ?? frame.function ?? "";
+}
+/**
+ * Contract §3. Source-map ignore lists are applied by symbolicate.ts; the
+ * language rules apply only to frames of that language, so a JS object
+ * that happens to be called `runtime` or `System` stays in-app.
+ */
+export function isInAppFrame(frame, language) {
+    if (!isInAppPath(frame.filename))
+        return false;
+    const qualified = qualifiedName(frame);
+    if (language === "go") {
+        if (qualified.startsWith("runtime."))
+            return false;
+        if ((frame.filename ?? "").replace(/\\/g, "/").includes("/usr/local/go/"))
+            return false;
+    }
+    if (language === "jvm" && /^(?:java|javax|kotlin|jdk)\./.test(qualified))
+        return false;
+    if (language === "dotnet" && /^(?:System|Microsoft)\./.test(qualified))
+        return false;
+    return true;
+}
+// ── Helpers ───────────────────────────────────────────────────────────────
+/** Strip a query string and/or hash from a path or URL. */
+export function stripQueryAndHash(path) {
+    const at = path.search(/[?#]/);
+    return at === -1 ? path : path.slice(0, at);
+}
+function clean(value, max) {
+    if (value == null)
+        return null;
+    const trimmed = value.trim();
+    return trimmed ? trimmed.slice(0, max) : null;
+}
+function toInt(value) {
+    if (value === undefined)
+        return null;
+    const n = Number.parseInt(value, 10);
+    return Number.isFinite(n) ? n : null;
+}
+function frame(language, parts) {
+    const filename = clean(parts.filename ? stripQueryAndHash(parts.filename) : null, MAX_PATH_CHARS);
+    const out = {
+        function: clean(parts.function, MAX_FUNCTION_CHARS),
+        module: clean(parts.module, MAX_FUNCTION_CHARS),
+        filename,
+        lineno: parts.lineno ?? null,
+        colno: parts.colno ?? null,
+        inApp: true,
+        resolved: false,
+    };
+    out.inApp = isInAppFrame(out, language);
+    return out;
+}
+/**
+ * Drop the trailing (balanced) call-argument group: "f(0x1, 0x2)" → "f",
+ * "C->handle(Object(Request))" → "C->handle". Receiver parentheses earlier
+ * in the name ("main.(*T).M(…)") are kept.
+ */
+function stripTrailingArgs(fn) {
+    const trimmed = fn.trim();
+    if (!trimmed.endsWith(")"))
+        return trimmed;
+    let depth = 0;
+    for (let i = trimmed.length - 1; i >= 0; i--) {
+        const ch = trimmed[i];
+        if (ch === ")")
+            depth++;
+        else if (ch === "(" && --depth === 0)
+            return i > 0 ? trimmed.slice(0, i).trim() : trimmed;
+    }
+    return trimmed;
+}
+/** Split at the last "." outside brackets/angles: "A.B.C[T]" → ["A.B", "C[T]"]. */
+function splitLastDot(name) {
+    let depth = 0;
+    for (let i = name.length - 1; i > 0; i--) {
+        const ch = name[i];
+        if (ch === "]" || ch === ">" || ch === ")")
+            depth++;
+        else if (ch === "[" || ch === "<" || ch === "(")
+            depth = Math.max(0, depth - 1);
+        else if (ch === "." && depth === 0) {
+            // ".ctor" / ".cctor": the dot belongs to the method name.
+            if (name[i - 1] === ".")
+                return [name.slice(0, i - 1), name.slice(i)];
+            return [name.slice(0, i), name.slice(i + 1)];
+        }
+    }
+    return [null, name];
+}
+// ── JavaScript ────────────────────────────────────────────────────────────
+const V8_LINE_RE = /^\s*at\s+(.*)$/;
+const V8_WITH_FN_RE = /^(.*?)\s+\((.*)\)$/;
+const LOCATION_RE = /^(.*?):(\d+)(?::(\d+))?$/;
+const GECKO_LINE_RE = /^\s*(.*?)@(.*?)\s*$/;
+/** "file:line:col" (or a bare non-path marker) → location parts. */
+function jsLocation(raw) {
+    let location = raw.trim();
+    // eval frames: "eval at fn (file:1:2), <anonymous>:3:4" — use the
+    // evaluating script's position.
+    if (location.startsWith("eval at ")) {
+        const inner = /\(([^()]+?):(\d+):(\d+)\)/.exec(location);
+        if (inner)
+            return { filename: inner[1], lineno: toInt(inner[2]), colno: toInt(inner[3]) };
+    }
+    if (/^(?:native|<anonymous>|\[native code\]|index \d+|unknown location)$/i.test(location)) {
+        return { filename: null, lineno: null, colno: null };
+    }
+    const m = LOCATION_RE.exec(location);
+    if (m && m[1])
+        return { filename: m[1], lineno: toInt(m[2]), colno: toInt(m[3]) };
+    location = location.replace(/^address at /, "");
+    return { filename: location || null, lineno: null, colno: null };
+}
+function parseV8(lines) {
+    const frames = [];
+    for (const line of lines) {
+        const m = V8_LINE_RE.exec(line);
+        if (!m)
+            continue;
+        const body = m[1].trim();
+        const withFn = V8_WITH_FN_RE.exec(body);
+        if (withFn) {
+            frames.push(frame("javascript", { function: withFn[1], ...jsLocation(withFn[2]) }));
+        }
+        else {
+            // "at async file:1:2" is an anonymous async function: the location
+            // is what follows "async " (the platform parser mirrors this).
+            frames.push(frame("javascript", jsLocation(body.replace(/^async /, ""))));
+        }
+        if (frames.length >= MAX_FRAMES)
+            break;
+    }
+    return frames;
+}
+/** A Firefox/Safari location: something with :line(:col), or [native code]. */
+function isGeckoLocation(location) {
+    return /:\d+(?::\d+)?$/.test(location) || location === "[native code]";
+}
+function parseGecko(lines) {
+    const frames = [];
+    for (const line of lines) {
+        const m = GECKO_LINE_RE.exec(line);
+        if (!m || !isGeckoLocation(m[2]))
+            continue;
+        // Firefox eval frames: "fn@url line 2 > eval:1:5" — keep the script.
+        const location = m[2].replace(/ line (\d+) > (?:eval|Function)(?::\d+:\d+)?$/, ":$1");
+        frames.push(frame("javascript", { function: m[1] || null, ...jsLocation(location) }));
+        if (frames.length >= MAX_FRAMES)
+            break;
+    }
+    return frames;
+}
+// ── Python ────────────────────────────────────────────────────────────────
+const PY_FILE_RE = /^\s*File "(.+)", line (\d+)(?:, in (.+?))?\s*$/;
+const PY_TRACEBACK_RE = /^\s*Traceback \(most recent call last\):\s*$/;
+function parsePython(lines) {
+    // A chained exception prints one traceback per exception; the reported
+    // (final) exception's frames are the last block.
+    let start = 0;
+    for (let i = 0; i < lines.length; i++)
+        if (PY_TRACEBACK_RE.test(lines[i]))
+            start = i;
+    const outermostFirst = [];
+    for (const line of lines.slice(start)) {
+        const m = PY_FILE_RE.exec(line);
+        if (!m)
+            continue;
+        outermostFirst.push(frame("python", { function: m[3] ?? null, filename: m[1], lineno: toInt(m[2]) }));
+    }
+    return outermostFirst.reverse().slice(0, MAX_FRAMES);
+}
+// ── Go ────────────────────────────────────────────────────────────────────
+const GO_LOCATION_RE = /^\s*(.+\.go):(\d+)(?:\s+\+0x[0-9a-f]+)?\s*$/;
+const GO_GOROUTINE_RE = /\bgoroutine \d+ \[/;
+/** "net/http.(*conn).serve" → module "net/http", function "(*conn).serve". */
+function splitGoName(qualified) {
+    const slash = qualified.lastIndexOf("/", qualified.indexOf("(") === -1 ? qualified.length : qualified.indexOf("("));
+    const dot = qualified.indexOf(".", slash + 1);
+    if (dot <= 0)
+        return { module: null, function: qualified };
+    return { module: qualified.slice(0, dot), function: qualified.slice(dot + 1) };
+}
+function parseGo(lines) {
+    const frames = [];
+    let fn = "";
+    let goroutines = 0;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (GO_GOROUTINE_RE.test(trimmed)) {
+            // Only the first goroutine is the one that failed.
+            if (++goroutines > 1 && frames.length > 0)
+                break;
+            fn = "";
+            continue;
+        }
+        const loc = GO_LOCATION_RE.exec(line);
+        if (loc && fn) {
+            const name = stripTrailingArgs(fn.replace(/^created by\s+/, "").replace(/\s+in goroutine \d+\s*$/, ""));
+            const { module, function: func } = splitGoName(name);
+            frames.push(frame("go", { function: func, module, filename: loc[1].trim(), lineno: toInt(loc[2]) }));
+            if (frames.length >= MAX_FRAMES)
+                break;
+            fn = "";
+            continue;
+        }
+        if (trimmed && !loc)
+            fn = trimmed;
+    }
+    return frames;
+}
+// ── JVM ───────────────────────────────────────────────────────────────────
+function parseJvm(lines) {
+    const frames = [];
+    for (const line of lines) {
+        // The reported exception's frames come first; causes follow.
+        if (/^\s*(?:Caused by|Suppressed):/.test(line) && frames.length > 0)
+            break;
+        const m = /^\s*at\s+(.+?)\((.*)\)\s*$/.exec(line);
+        if (!m)
+            continue;
+        // "java.base/java.lang.Thread.run", "app//com.example.Foo.bar"
+        const qualified = m[1].trim().replace(/^.*\//, "");
+        const [module, method] = splitLastDot(qualified);
+        const location = m[2].trim();
+        let filename = null;
+        let lineno = null;
+        if (!/^(?:Native Method|Unknown Source)$/.test(location)) {
+            const loc = /^(.*?)(?::(\d+))?$/.exec(location);
+            filename = loc[1] || null;
+            lineno = toInt(loc[2]);
+        }
+        frames.push(frame("jvm", { function: method, module, filename, lineno }));
+        if (frames.length >= MAX_FRAMES)
+            break;
+    }
+    return frames;
+}
+// ── .NET ──────────────────────────────────────────────────────────────────
+function parseDotnet(lines) {
+    let frames = [];
+    for (const line of lines) {
+        // "Outer ---> Inner\n at inner…\n --- End of inner exception stack
+        // trace ---\n at outer…": the reported (outer) frames come last.
+        if (/---\s*End of inner exception stack trace\s*---/i.test(line)) {
+            frames = [];
+            continue;
+        }
+        const m = /^\s*at\s+(.+?)(?:\s+in\s+(.+?):line\s+(\d+))?\s*$/.exec(line);
+        if (!m)
+            continue;
+        const [module, method] = splitLastDot(stripTrailingArgs(m[1]));
+        frames.push(frame("dotnet", { function: method, module, filename: m[2] ?? null, lineno: toInt(m[3]) }));
+    }
+    return frames.slice(0, MAX_FRAMES);
+}
+// ── Rust ──────────────────────────────────────────────────────────────────
+function parseRust(lines) {
+    const frames = [];
+    for (let i = 0; i < lines.length && frames.length < MAX_FRAMES; i++) {
+        const m = /^\s*\d+:\s+(?:0x[0-9a-f]+\s+-\s+)?(.+?)\s*$/.exec(lines[i]);
+        if (!m)
+            continue;
+        const fn = m[1].replace(/::h[0-9a-f]{6,}$/, "").trim();
+        if (!fn)
+            continue;
+        const at = /^\s*at\s+(.+?):(\d+)(?::(\d+))?\s*$/.exec(lines[i + 1] ?? "");
+        if (at)
+            i++;
+        frames.push(frame("rust", {
+            function: fn,
+            filename: at?.[1] ?? null,
+            lineno: toInt(at?.[2]),
+            colno: toInt(at?.[3]),
+        }));
+    }
+    return frames;
+}
+// ── Ruby / PHP (best effort) ──────────────────────────────────────────────
+// A .NET frame without source locations: "at Ns.Type.Method(Type arg)".
+// V8 always puts a space before "(" or has no parentheses at all.
+const DOTNET_BARE_RE = /^\s*at\s+[\w.`<>\[\],+|]+\([\w.`<>\[\],&*\s]*\)\s*$/;
+const RUBY_RE = /^\s*(?:from\s+)?(.+?):(\d+)(?::in\s+[`'](?:[\w:#.]+[#.])?(.+?)')?\s*$/;
+const PHP_RE = /^\s*#\d+\s+(.+?)\((\d+)\):\s+(.+?)\s*$/;
+function parseRuby(lines) {
+    const frames = [];
+    for (const line of lines) {
+        const m = RUBY_RE.exec(line);
+        if (!m || !/\.(?:rb|erb|rake)$/.test(m[1]))
+            continue;
+        frames.push(frame("ruby", { function: m[3] ?? null, filename: m[1], lineno: toInt(m[2]) }));
+        if (frames.length >= MAX_FRAMES)
+            break;
+    }
+    return frames;
+}
+function parsePhp(lines) {
+    const frames = [];
+    for (const line of lines) {
+        const m = PHP_RE.exec(line);
+        if (!m)
+            continue;
+        frames.push(frame("php", { function: stripTrailingArgs(m[3]), filename: m[1], lineno: toInt(m[2]) }));
+        if (frames.length >= MAX_FRAMES)
+            break;
+    }
+    return frames;
+}
+// ── Entry point ───────────────────────────────────────────────────────────
+/** The language of a raw stack, or null when it has no recognisable frames. */
+export function detectFrameLanguage(lines) {
+    switch (detectStackLanguage(lines)) {
+        case "go":
+            return "go";
+        case "rust":
+            return "rust";
+        case "jvm":
+            return "jvm";
+        case "dotnet":
+            return "dotnet";
+        default:
+    }
+    if (lines.some((line) => PY_FILE_RE.test(line)))
+        return "python";
+    if (lines.some((line) => DOTNET_BARE_RE.test(line)) &&
+        !lines.some((line) => /:\d+(?::\d+)?\)?\s*$/.test(line))) {
+        return "dotnet";
+    }
+    if (lines.some((line) => V8_LINE_RE.test(line)))
+        return "javascript";
+    if (lines.some((line) => {
+        const m = GECKO_LINE_RE.exec(line);
+        return Boolean(m && isGeckoLocation(m[2]));
+    }))
+        return "javascript";
+    if (lines.some((line) => PHP_RE.test(line)))
+        return "php";
+    if (lines.some((line) => {
+        const m = RUBY_RE.exec(line);
+        return Boolean(m && /\.(?:rb|erb|rake)$/.test(m[1]));
+    }))
+        return "ruby";
+    return null;
+}
+/** Parse a raw stack into frames, innermost first (≤ MAX_FRAMES). */
+export function parseStackFrames(stack) {
+    if (!stack)
+        return [];
+    const lines = stack.split(/\r?\n/);
+    switch (detectFrameLanguage(lines)) {
+        case "go":
+            return parseGo(lines);
+        case "rust":
+            return parseRust(lines);
+        case "jvm":
+            return parseJvm(lines);
+        case "dotnet":
+            return parseDotnet(lines);
+        case "python":
+            return parsePython(lines);
+        case "javascript":
+            return lines.some((line) => V8_LINE_RE.test(line)) ? parseV8(lines) : parseGecko(lines);
+        case "php":
+            return parsePhp(lines);
+        case "ruby":
+            return parseRuby(lines);
+        default:
+            return [];
+    }
+}

package/dist/symbolicate.d.ts

@@ -0,0 +1,79 @@
+import { TraceMap } from "@jridgewell/trace-mapping";
+import type { SourceMapKey } from "./source-maps-lookup.js";
+import type { StackFrame } from "./types.js";
+/**
+ * Symbolication at ingest: minified browser frames are resolved through the
+ * source maps uploaded for the release (`/v1/sourcemaps`) BEFORE they are
+ * fingerprinted, so `frames-v3` hashes `checkout.tsx`, not
+ * `index-5f3a9c1e.js` — and an issue survives deploys and preview domains.
+ *
+ * - Function names come from the map's `names`: the name mapped at the
+ *   CALLER's position is the callee's original name (the call site names
+ *   what it calls). Without one, a resolved frame keeps its parsed name
+ *   only when that is not an obviously mangled one (≤ 2 characters), since
+ *   a mangled name changes on every build.
+ * - Sources the map lists in `ignoreList` / `x_google_ignoreList` are not
+ *   in-app; a resolved path under node_modules/ etc. is not in-app either.
+ * - Context lines only when the map carries `sourcesContent` (the upload
+ *   strips it today, so there are none for now).
+ * - Never fails ingest: any error leaves the frame as parsed.
+ *
+ * Parsed maps are cached per (org, repository, release, file) — or per debug
+ * id — in a byte-bounded LRU, so a busy issue never refetches its map.
+ */
+export type MapFetcher = (key: SourceMapKey) => Promise<string | null>;
+export interface SymbolicationScope {
+    orgId: string;
+    repositoryId: string;
+    release: string | null;
+    /** Script URL → debug id (EI-13), when the browser sent them. */
+    debugIds?: Record<string, string> | null;
+}
+/** Path-only form of a script URL — the key uploads are stored under. */
+export declare function scriptPath(filename: string): string | null;
+export interface SourceMapCacheOptions {
+    /** Budget for the estimated in-memory size of parsed maps (default 64 MiB). */
+    maxBytes?: number;
+    maxEntries?: number;
+    /** How long a found map is reused (default 1 h). */
+    hitTtlMs?: number;
+    /** How long "no map uploaded" is remembered (default 5 min). */
+    missTtlMs?: number;
+    /** How long a failed lookup is remembered (default 30 s). */
+    errorTtlMs?: number;
+    now?: () => number;
+}
+export declare class SourceMapCache {
+    private readonly entries;
+    private readonly inFlight;
+    private weight;
+    private readonly maxBytes;
+    private readonly maxEntries;
+    private readonly hitTtlMs;
+    private readonly missTtlMs;
+    private readonly errorTtlMs;
+    private readonly now;
+    /** Fetches made (cache misses) — for tests and /healthz-style debugging. */
+    fetches: number;
+    constructor(options?: SourceMapCacheOptions);
+    static keyOf(key: SourceMapKey): string;
+    get size(): number;
+    /** The parsed map for `key` (null when none), fetching at most once at a time. */
+    get(key: SourceMapKey, fetchMap: MapFetcher): Promise<TraceMap | null>;
+    private load;
+    private store;
+    private remove;
+}
+export declare class Symbolicator {
+    private readonly fetchMap;
+    readonly cache: SourceMapCache;
+    constructor(fetchMap: MapFetcher, cache?: SourceMapCache);
+    /**
+     * Resolve the JS frames of one stack. Returns a new array; frames that
+     * cannot be resolved (no map, no position, non-JS) are returned as given.
+     */
+    symbolicate(frames: StackFrame[], scope: SymbolicationScope): Promise<StackFrame[]>;
+    private debugIdFor;
+    private keyFor;
+    private resolveAll;
+}