@fixback/node 0.2.0 → 0.3.0

package/src/process.ts

@@ -1,153 +0,0 @@
-/**
- * Process-level capture (spec §D9, stories 4 & 5) — the *polite* `uncaughtException`
- * and `unhandledRejection` handlers that **never change the app's exit behaviour**.
- *
- * The subtlety: merely *adding* an `uncaughtException` listener suppresses Node's
- * default crash. So to stay polite:
- *
- * - **uncaughtException:** capture (`handled: false`), then — only when we are the
- *   *sole* listener (the app installed none of its own) — best-effort flush and hand
- *   off to `onFatalError`, which preserves Node's default (log + non-zero exit). When
- *   the app has its own handler, we do nothing further: the app owns the exit.
- * - **unhandledRejection:** capture (`handled: false`) and stop. We never escalate a
- *   rejection to a process exit — exactly the "never turn a logged rejection into an
- *   exit" guarantee (story 5).
- *
- * Everything is wrapped so a capture failure can never break the handler.
- */
-
-/** The `process` slice these handlers touch — injectable so tests never touch the real one. */
-export interface ProcessLike {
-  on(event: string, listener: (...args: unknown[]) => void): unknown;
-  removeListener(event: string, listener: (...args: unknown[]) => void): unknown;
-  listeners(event: string): Array<(...args: unknown[]) => void>;
-}
-
-/** What a captured process error is filed through — the {@link FixbackClient} satisfies it. */
-export interface CaptureSink {
-  captureException(error: unknown, context?: { handled?: boolean }): void;
-  flush(): Promise<void>;
-}
-
-/** Which process handlers to install. */
-export interface ProcessHandlerOptions {
-  readonly captureUncaughtException: boolean;
-  readonly captureUnhandledRejection: boolean;
-  /** How long a fatal-path flush may take before the process exits anyway. */
-  readonly flushTimeoutMs?: number;
-}
-
-/** Injectable collaborators for {@link installProcessHandlers}. */
-export interface ProcessHandlerDeps {
-  readonly process?: ProcessLike;
-  /**
-   * Preserve Node's default fatal behaviour after a sole-listener uncaught exception.
-   * Defaults to logging the error and exiting non-zero (exactly what Node would do).
-   */
-  readonly onFatalError?: (error: unknown) => void;
-}
-
-const DEFAULT_FLUSH_TIMEOUT_MS = 2_000;
-
-/** The real `process`, when running on Node. */
-function resolveProcess(): ProcessLike | undefined {
-  const g = globalThis as unknown as { process?: ProcessLike };
-  const proc = g.process;
-  return proc && typeof proc.on === "function" ? proc : undefined;
-}
-
-/** Node's default fatal behaviour: print the error and exit non-zero. */
-function defaultOnFatalError(proc: ProcessLike): (error: unknown) => void {
-  return (error: unknown) => {
-    try {
-      console.error(error);
-    } catch {
-      /* a hostile console must not stop the exit */
-    }
-    const exit = (proc as { exit?: (code?: number) => never }).exit;
-    if (typeof exit === "function") {
-      try {
-        exit(1);
-      } catch {
-        /* exit is terminal; nothing to do if it throws */
-      }
-    }
-  };
-}
-
-/** Race a flush against a timeout so a wedged transport can't hang a crashing process. */
-function flushWithTimeout(flush: () => Promise<void>, ms: number): Promise<void> {
-  let result: Promise<void>;
-  try {
-    result = Promise.resolve(flush());
-  } catch {
-    return Promise.resolve();
-  }
-  if (ms <= 0) return result.catch(() => {});
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const timeout = new Promise<void>((resolve) => {
-    timer = setTimeout(resolve, ms);
-  });
-  return Promise.race([result.catch(() => {}), timeout]).finally(() => {
-    if (timer !== undefined) clearTimeout(timer);
-  });
-}
-
-/**
- * Install the polite process handlers for `sink`, returning an uninstall function.
- * A no-op (and a no-op uninstall) when no `process` is available or when both gates
- * are off.
- */
-export function installProcessHandlers(
-  sink: CaptureSink,
-  options: ProcessHandlerOptions,
-  deps: ProcessHandlerDeps = {},
-): () => void {
-  const proc = deps.process ?? resolveProcess();
-  if (!proc) return () => {};
-
-  const onFatalError = deps.onFatalError ?? defaultOnFatalError(proc);
-  const flushTimeoutMs = options.flushTimeoutMs ?? DEFAULT_FLUSH_TIMEOUT_MS;
-
-  const onUncaughtException = (...args: unknown[]): void => {
-    const error = args[0];
-    try {
-      sink.captureException(error, { handled: false });
-    } catch {
-      /* capture must never break the handler */
-    }
-    // If the app installed its own uncaughtException handler, it owns the exit — we
-    // must not force one (that would *change* its behaviour). Only when we are the
-    // sole listener do we preserve Node's default crash.
-    const others = proc.listeners("uncaughtException").filter((l) => l !== onUncaughtException);
-    if (others.length > 0) return;
-    void flushWithTimeout(() => sink.flush(), flushTimeoutMs).finally(() => {
-      try {
-        onFatalError(error);
-      } catch {
-        /* the fatal handler is terminal */
-      }
-    });
-  };
-
-  const onUnhandledRejection = (...args: unknown[]): void => {
-    // Capture only — never escalate a rejection to a process exit (story 5).
-    try {
-      sink.captureException(args[0], { handled: false });
-    } catch {
-      /* capture must never break the handler */
-    }
-  };
-
-  if (options.captureUncaughtException) proc.on("uncaughtException", onUncaughtException);
-  if (options.captureUnhandledRejection) proc.on("unhandledRejection", onUnhandledRejection);
-
-  return () => {
-    if (options.captureUncaughtException) {
-      proc.removeListener("uncaughtException", onUncaughtException);
-    }
-    if (options.captureUnhandledRejection) {
-      proc.removeListener("unhandledRejection", onUnhandledRejection);
-    }
-  };
-}

package/src/stack.test.ts

@@ -1,89 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { extractError, extractStructuredFrames } from "./stack";
-
-const V8_STACK = [
-  "TypeError: Cannot read properties of undefined (reading 'id')",
-  "    at renderTotal (/srv/app/dist/checkout.js:88:12)",
-  "    at Object.<anonymous> (/srv/app/dist/server.js:42:5)",
-  "    at processTicksAndRejections (node:internal/process/task_queues:95:5)",
-].join("\n");
-
-describe("extractStructuredFrames", () => {
-  it("parses V8 frames into file/line/column/function, top of stack first", () => {
-    const frames = extractStructuredFrames(V8_STACK);
-    expect(frames[0]).toEqual({
-      file: "/srv/app/dist/checkout.js",
-      line: 88,
-      column: 12,
-      function: "renderTotal",
-    });
-    expect(frames[1]).toEqual({
-      file: "/srv/app/dist/server.js",
-      line: 42,
-      column: 5,
-      function: "Object.<anonymous>",
-    });
-  });
-
-  it("scrubs credentials and query strings from a frame's file url (shared-core scrub)", () => {
-    const stack = [
-      "Error: boom",
-      "    at handler (https://user:pass@cdn.example.com/app.js?token=secret123:5:1)",
-    ].join("\n");
-    const [frame] = extractStructuredFrames(stack);
-    expect(frame?.file).not.toContain("token=secret123");
-    expect(frame?.file).not.toContain("user:pass@");
-    expect(frame?.file).toContain("cdn.example.com/app.js");
-  });
-
-  it("caps the number of frames it keeps", () => {
-    const many = ["Error: boom"]
-      .concat(Array.from({ length: 100 }, (_, i) => `    at fn${i} (/srv/app/f${i}.js:${i + 1}:1)`))
-      .join("\n");
-    expect(extractStructuredFrames(many, 5)).toHaveLength(5);
-  });
-
-  it("returns no frames for a missing or stackless input", () => {
-    expect(extractStructuredFrames(undefined)).toEqual([]);
-    expect(extractStructuredFrames("")).toEqual([]);
-    expect(extractStructuredFrames("Error: no frames here")).toEqual([]);
-  });
-});
-
-describe("extractError", () => {
-  it("distils an Error into type / value / stack", () => {
-    const err = new TypeError("nope");
-    const extracted = extractError(err);
-    expect(extracted.type).toBe("TypeError");
-    expect(extracted.value).toBe("nope");
-    expect(extracted.stack).toBe(err.stack);
-  });
-
-  it("falls back to Error for an anonymous error and keeps an empty message", () => {
-    const bare = new Error();
-    expect(extractError(bare).type).toBe("Error");
-    expect(extractError(bare).value).toBe("");
-  });
-
-  it("distils a thrown string", () => {
-    expect(extractError("kaboom")).toEqual({ type: "Error", value: "kaboom", stack: undefined });
-  });
-
-  it("distils a thrown non-error object without throwing", () => {
-    const extracted = extractError({ weird: true });
-    expect(extracted.type).toBe("Error");
-    expect(typeof extracted.value).toBe("string");
-    expect(extracted.stack).toBeUndefined();
-  });
-
-  it("uses a custom error subclass name as the type", () => {
-    class PaymentError extends Error {
-      constructor(message: string) {
-        super(message);
-        this.name = "PaymentError";
-      }
-    }
-    expect(extractError(new PaymentError("declined")).type).toBe("PaymentError");
-  });
-});

package/src/stack.ts

@@ -1,153 +0,0 @@
-/**
- * Turning a thrown value into the pieces a capture needs: the distilled
- * `type | value | stack` a fingerprint is built from ({@link extractError}), and the
- * **structured stack frames** for the wire ({@link extractStructuredFrames}).
- *
- * The distillation mirrors the browser SDK's exactly (`packages/sdk/src/error-capture.ts`)
- * — `type = error.name`, `value = error.message`, `stack = error.stack` — so the same
- * logical error yields the same shared-core fingerprint on either surface (the
- * ADR-0028 parity guarantee). Frame parsing keeps the full script path (server-side
- * symbolication matches it against uploaded sourcemaps) but scrubs each URL through
- * the shared-core scrubber before it can leave the process.
- */
-
-import { type CapturedFrame, scrubUrl } from "@fixback/sdk-core";
-
-/** The most structured frames shipped per error (mirrors the server's cap). */
-const STRUCTURED_FRAME_LIMIT = 30;
-
-/** The distilled shape a fingerprint and a report are built from. */
-export interface ExtractedError {
-  readonly type: string;
-  readonly value: string;
-  readonly stack?: string;
-}
-
-interface ErrorLike {
-  name?: unknown;
-  message?: unknown;
-  stack?: unknown;
-}
-
-/** Coerce any value to a string without throwing (a hostile `toString` can throw). */
-function asString(value: unknown): string {
-  if (typeof value === "string") return value;
-  if (value == null) return "";
-  try {
-    return String(value);
-  } catch {
-    return "";
-  }
-}
-
-/** Best-effort JSON for a non-Error thrown object, falling back to `String`. */
-function safeStringify(value: unknown): string {
-  try {
-    return JSON.stringify(value) ?? asString(value);
-  } catch {
-    return asString(value);
-  }
-}
-
-/** True for a duck-typed error (a cross-realm Error, or an error-shaped throwable). */
-function isErrorLike(value: object): value is ErrorLike {
-  const err = value as ErrorLike;
-  return (
-    typeof err.message === "string" ||
-    typeof err.stack === "string" ||
-    typeof err.name === "string"
-  );
-}
-
-/**
- * Distil any thrown value into `{ type, value, stack }`. An `Error` (or error-shaped
- * object) contributes its `name` / `message` / `stack`; a thrown string becomes the
- * value; any other value is stringified. Never throws.
- */
-export function extractError(input: unknown): ExtractedError {
-  if (input instanceof Error) {
-    return {
-      type: asString(input.name) || "Error",
-      value: asString(input.message),
-      stack: typeof input.stack === "string" ? input.stack : undefined,
-    };
-  }
-  if (typeof input === "string") {
-    return { type: "Error", value: input, stack: undefined };
-  }
-  if (input && typeof input === "object") {
-    if (isErrorLike(input)) {
-      const err = input as ErrorLike;
-      return {
-        type: asString(err.name) || "Error",
-        value: asString(err.message),
-        stack: typeof err.stack === "string" ? err.stack : undefined,
-      };
-    }
-    return { type: "Error", value: safeStringify(input), stack: undefined };
-  }
-  return { type: "Error", value: asString(input), stack: undefined };
-}
-
-/** Split a `file:line:col` location into parts; `null` when it has no line. */
-function parseLocation(
-  location: string,
-): { file: string; line: number; column: number | null } | null {
-  // The file may itself contain colons (https://…, node:internal/…), so split from
-  // the right: the trailing `:line(:col)?` are the numeric groups.
-  const match = location.match(/^(.*?):(\d+)(?::(\d+))?$/);
-  if (!match) return null;
-  const file = match[1] ?? "";
-  if (file.length === 0 || file === "native" || file.includes("<anonymous>")) {
-    return null;
-  }
-  const line = Number(match[2]);
-  if (!Number.isFinite(line)) return null;
-  const column = match[3] !== undefined ? Number(match[3]) : null;
-  return { file, line, column };
-}
-
-/**
- * Extract structured frames from a stack for the wire (#117, ADR-0024), top of stack
- * first. Keeps the full (scrubbed) script path so server-side symbolication can match
- * it against uploaded sourcemaps; skips unlocatable frames (`native`, `<anonymous>`,
- * eval); caps the count. V8 is Node's format; the Firefox/Safari form is handled too
- * so the parser matches the browser SDK's exactly.
- */
-export function extractStructuredFrames(
-  stack: string | undefined,
-  limit = STRUCTURED_FRAME_LIMIT,
-): CapturedFrame[] {
-  if (typeof stack !== "string" || stack.length === 0) return [];
-  const frames: CapturedFrame[] = [];
-  for (const raw of stack.split("\n")) {
-    if (frames.length >= limit) break;
-    const line = raw.trim();
-    let fn: string | null = null;
-    let location: string | null = null;
-    // V8: "at fn (loc)" | "at loc"
-    const v8Named = line.match(/^at\s+(.+?)\s+\((.+)\)$/);
-    const v8Bare = v8Named ? null : line.match(/^at\s+(.+)$/);
-    const geckoAt = v8Named || v8Bare ? -1 : line.indexOf("@");
-    if (v8Named) {
-      fn = v8Named[1] ?? null;
-      location = v8Named[2] ?? null;
-    } else if (v8Bare) {
-      location = v8Bare[1] ?? null;
-    } else if (geckoAt >= 0) {
-      // Firefox / Safari: "fn@loc" | "@loc"
-      fn = geckoAt > 0 ? line.slice(0, geckoAt) : null;
-      location = line.slice(geckoAt + 1);
-    }
-    if (!location) continue;
-    const parsed = parseLocation(location);
-    if (!parsed) continue;
-    frames.push({
-      file: scrubUrl(parsed.file),
-      line: parsed.line,
-      column: parsed.column,
-      function: fn && fn.length > 0 ? fn : null,
-    });
-  }
-  return frames;
-}

package/src/transport.test.ts

@@ -1,187 +0,0 @@
-import { AutoReportBackoff } from "@fixback/sdk-core";
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-import { Transport } from "./transport";
-import type { FetchLike } from "./transport";
-
-interface FakeResponse {
-  readonly ok?: boolean;
-  readonly status?: number;
-  readonly headers?: Record<string, string>;
-  readonly throw?: boolean;
-}
-
-interface RecordedCall {
-  url: string;
-  headers: Record<string, string>;
-  body: { errors: Array<Record<string, unknown>> };
-}
-
-function fakeFetch(responses: FakeResponse[]): { fetchImpl: FetchLike; calls: RecordedCall[] } {
-  const calls: RecordedCall[] = [];
-  const fetchImpl: FetchLike = async (url, init) => {
-    calls.push({
-      url,
-      headers: init.headers ?? {},
-      body: JSON.parse(String(init.body)) as RecordedCall["body"],
-    });
-    const next = responses.shift() ?? { ok: true, status: 201 };
-    if (next.throw) throw new Error("network down");
-    return {
-      ok: next.ok ?? true,
-      status: next.status ?? 201,
-      headers: { get: (name: string) => next.headers?.[name.toLowerCase()] ?? null },
-      json: async () => ({}),
-    };
-  };
-  return { fetchImpl, calls };
-}
-
-const baseConfig = {
-  endpoint: "https://api.test/api/errors",
-  secretKey: "sk_secret",
-  maxBatchSize: 100,
-  maxQueueSize: 1000,
-  flushIntervalMs: 0,
-  timeoutMs: 0,
-};
-
-afterEach(() => {
-  vi.useRealTimers();
-});
-
-describe("Transport", () => {
-  it("posts a JSON batch to the errors endpoint with a Bearer secret-key header", async () => {
-    const { fetchImpl, calls } = fakeFetch([{ ok: true, status: 201 }]);
-    const transport = new Transport(baseConfig, { fetchImpl });
-
-    transport.enqueue({ errorSignature: "fp-1", handled: true });
-    transport.enqueue({ errorSignature: "fp-2", handled: false });
-    await transport.flush();
-
-    expect(calls).toHaveLength(1);
-    expect(calls[0]!.url).toBe("https://api.test/api/errors");
-    expect(calls[0]!.headers.authorization).toBe("Bearer sk_secret");
-    expect(calls[0]!.headers["content-type"]).toContain("application/json");
-    expect(calls[0]!.body.errors).toHaveLength(2);
-    expect(calls[0]!.body.errors.map((e) => e.errorSignature)).toEqual(["fp-1", "fp-2"]);
-  });
-
-  it("coalesces same-fingerprint errors into one item, summing occurrences", async () => {
-    const { fetchImpl, calls } = fakeFetch([{ ok: true, status: 201 }]);
-    const transport = new Transport(baseConfig, { fetchImpl });
-
-    transport.enqueue({ errorSignature: "loop" });
-    transport.enqueue({ errorSignature: "loop" });
-    transport.enqueue({ errorSignature: "loop", occurrences: 3 });
-    await transport.flush();
-
-    expect(calls[0]!.body.errors).toHaveLength(1);
-    expect(calls[0]!.body.errors[0]!.occurrences).toBe(5);
-  });
-
-  it("keeps the first occurrence's evidence when coalescing", async () => {
-    const { fetchImpl, calls } = fakeFetch([{ ok: true, status: 201 }]);
-    const transport = new Transport(baseConfig, { fetchImpl });
-    transport.enqueue({ errorSignature: "loop", handled: false, server: { route: "/a" } });
-    transport.enqueue({ errorSignature: "loop", handled: false, server: { route: "/b" } });
-    await transport.flush();
-    expect(calls[0]!.body.errors[0]!.server).toEqual({ route: "/a" });
-    expect(calls[0]!.body.errors[0]!.occurrences).toBe(2);
-  });
-
-  it("flushes nothing when the buffer is empty", async () => {
-    const { fetchImpl, calls } = fakeFetch([]);
-    const transport = new Transport(baseConfig, { fetchImpl });
-    await transport.flush();
-    expect(calls).toHaveLength(0);
-  });
-
-  it("opens a backoff window on 429 + Retry-After and sheds captures until it clears", async () => {
-    let nowMs = 0;
-    const backoff = new AutoReportBackoff(() => nowMs);
-    const { fetchImpl, calls } = fakeFetch([
-      { ok: false, status: 429, headers: { "retry-after": "30" } },
-      { ok: true, status: 201 },
-    ]);
-    const transport = new Transport(baseConfig, { fetchImpl, backoff });
-
-    transport.enqueue({ errorSignature: "flood" });
-    await transport.flush(); // 429 → window opens, this batch is shed
-    expect(calls).toHaveLength(1);
-
-    // While the window is open, further captures are dropped without a request.
-    transport.enqueue({ errorSignature: "flood-2" });
-    await transport.flush();
-    expect(calls).toHaveLength(1);
-
-    // Once the window clears, capture resumes.
-    nowMs = 31_000;
-    transport.enqueue({ errorSignature: "after" });
-    await transport.flush();
-    expect(calls).toHaveLength(2);
-    expect(calls[1]!.body.errors[0]!.errorSignature).toBe("after");
-  });
-
-  it("fails quiet when fetch throws — flush never rejects and never throws to the caller", async () => {
-    const { fetchImpl } = fakeFetch([{ throw: true }]);
-    const transport = new Transport(baseConfig, { fetchImpl });
-    transport.enqueue({ errorSignature: "x" });
-    await expect(transport.flush()).resolves.toBeUndefined();
-  });
-
-  it("fails quiet when the endpoint refuses (non-2xx that is not 429)", async () => {
-    const { fetchImpl, calls } = fakeFetch([{ ok: false, status: 500 }]);
-    const transport = new Transport(baseConfig, { fetchImpl });
-    transport.enqueue({ errorSignature: "x" });
-    await expect(transport.flush()).resolves.toBeUndefined();
-    expect(calls).toHaveLength(1);
-  });
-
-  it("auto-flushes once the buffer reaches maxBatchSize", async () => {
-    const { fetchImpl, calls } = fakeFetch([{ ok: true, status: 201 }]);
-    const transport = new Transport({ ...baseConfig, maxBatchSize: 2 }, { fetchImpl });
-    transport.enqueue({ errorSignature: "a" });
-    transport.enqueue({ errorSignature: "b" }); // reaches the cap → auto-flush fires
-    await transport.flush(); // await the in-flight drain
-    expect(calls).toHaveLength(1);
-    expect(calls[0]!.body.errors).toHaveLength(2);
-  });
-
-  it("bounds the buffer at maxQueueSize under a sustained flood", async () => {
-    const { fetchImpl, calls } = fakeFetch([{ ok: true, status: 201 }]);
-    // flushIntervalMs 0 so nothing auto-sends; maxBatchSize high so the cap, not the
-    // batch trigger, is what bounds the buffer.
-    const transport = new Transport(
-      { ...baseConfig, maxQueueSize: 3, maxBatchSize: 1000 },
-      { fetchImpl },
-    );
-    for (let i = 0; i < 50; i++) transport.enqueue({ errorSignature: `fp-${i}` });
-    await transport.flush();
-    // At most maxQueueSize distinct items were retained.
-    expect(calls[0]!.body.errors.length).toBeLessThanOrEqual(3);
-  });
-
-  it("auto-flushes on the flush interval, on an unref'd timer", async () => {
-    vi.useFakeTimers();
-    const { fetchImpl, calls } = fakeFetch([{ ok: true, status: 201 }]);
-    const transport = new Transport({ ...baseConfig, flushIntervalMs: 5000 }, { fetchImpl });
-    transport.enqueue({ errorSignature: "timed" });
-    expect(calls).toHaveLength(0);
-    await vi.advanceTimersByTimeAsync(5000);
-    expect(calls).toHaveLength(1);
-    await transport.close();
-  });
-
-  it("close() drains the remaining buffer and stops the timer", async () => {
-    vi.useFakeTimers();
-    const { fetchImpl, calls } = fakeFetch([{ ok: true, status: 201 }]);
-    const transport = new Transport({ ...baseConfig, flushIntervalMs: 5000 }, { fetchImpl });
-    transport.enqueue({ errorSignature: "z" });
-    await transport.close();
-    expect(calls).toHaveLength(1);
-    // After close the timer no longer fires.
-    await vi.advanceTimersByTimeAsync(20_000);
-    expect(calls).toHaveLength(1);
-  });
-});