@fixback/node 0.2.0

package/src/client.ts

@@ -0,0 +1,262 @@
+/**
+ * The `FixbackClient` and the module-level singleton API (`init`, `captureException`,
+ * `captureMessage`, `flush`, `close`) — the SDK's capture surface.
+ *
+ * A capture distils the error, fingerprints it with the **shared core**
+ * (`@fixback/sdk-core`, so the key matches the browser SDK — ADR-0028), attaches the
+ * in-flight request's {@link ServerContext} from AsyncLocalStorage, runs the scrub
+ * choke point and the project's `beforeSend`, then hands a {@link ServerErrorPayload}
+ * to the batched transport. Every step is wrapped so a capture **never throws into
+ * the host** (story 34): a misbehaving hook, an unserialisable error, or a transport
+ * hiccup is swallowed, and the server keeps running.
+ */
+
+import { computeFingerprint, scrubUrl } from "@fixback/sdk-core";
+
+import { type InitOptions, resolveConfig, type ResolvedConfig } from "./config";
+import { currentServerContext } from "./context";
+import { installProcessHandlers, type ProcessLike } from "./process";
+import { extractError, extractStructuredFrames } from "./stack";
+import { type CaptureTransport, Transport } from "./transport";
+import type { FixbackErrorEvent, ServerContext, ServerErrorPayload, Severity } from "./wire";
+
+export type { BeforeSend, FixbackErrorEvent, ServerContext, Severity } from "./wire";
+export type { InitOptions } from "./config";
+export type { CaptureTransport } from "./transport";
+
+/** Optional per-capture context — override `handled` or add/override server context. */
+export interface CaptureContext {
+  /** Override the handled flag (defaults to `true` for a manual/caught capture). */
+  readonly handled?: boolean;
+  /** Server context to merge over what the request scope provides (e.g. a filter's status). */
+  readonly server?: ServerContext;
+}
+
+/** The minimal capture surface the framework adapters file through (satisfied by {@link FixbackClient}). */
+export interface CaptureClient {
+  captureException(error: unknown, context?: CaptureContext): void;
+}
+
+/** Advanced/testing seam: supply a custom {@link CaptureTransport} or process. */
+export interface ClientDeps {
+  readonly transport?: CaptureTransport;
+  /** The process to attach handlers to (defaults to the real `process`). */
+  readonly process?: ProcessLike;
+  /** Override Node's default fatal behaviour after a sole-listener uncaught exception. */
+  readonly onFatalError?: (error: unknown) => void;
+}
+
+type MutablePayload = { -readonly [K in keyof ServerErrorPayload]: ServerErrorPayload[K] };
+
+/** Merge two server contexts, the override winning; `undefined` when both are empty. */
+function mergeServerContext(
+  base: ServerContext | undefined,
+  override: ServerContext | undefined,
+): ServerContext | undefined {
+  if (!base && !override) return undefined;
+  const merged: Record<string, unknown> = { ...(base ?? {}), ...(override ?? {}) };
+  for (const key of Object.keys(merged)) {
+    if (merged[key] === undefined) delete merged[key];
+  }
+  return Object.keys(merged).length > 0 ? (merged as ServerContext) : undefined;
+}
+
+export class FixbackClient {
+  private readonly config: ResolvedConfig;
+  private readonly transport: CaptureTransport | null;
+
+  constructor(config: ResolvedConfig, deps: ClientDeps = {}) {
+    this.config = config;
+    this.transport =
+      deps.transport ??
+      (config.enabled
+        ? new Transport({
+            endpoint: config.errorsEndpoint,
+            secretKey: config.secretKey,
+            maxBatchSize: config.maxBatchSize,
+            maxQueueSize: config.maxQueueSize,
+            flushIntervalMs: config.flushIntervalMs,
+            timeoutMs: config.timeoutMs,
+          })
+        : null);
+  }
+
+  /** Whether this client will capture (its secret key resolved and the gate is on). */
+  get enabled(): boolean {
+    return this.config.enabled;
+  }
+
+  /** The header the request-context middleware reads a correlation id from. */
+  get requestIdHeader(): string {
+    return this.config.requestIdHeader;
+  }
+
+  /**
+   * Report a caught or manually-observed error. `handled` defaults to `true`; the
+   * process handlers pass `handled: false` for an uncaught crash.
+   */
+  captureException(error: unknown, context: CaptureContext = {}): void {
+    const { type, value, stack } = extractError(error);
+    const frames = extractStructuredFrames(stack);
+    this.dispatch(
+      {
+        errorSignature: computeFingerprint(type, value, stack),
+        type,
+        value,
+        handled: context.handled ?? true,
+        errorFrames: frames.length > 0 ? frames : undefined,
+      },
+      context,
+    );
+  }
+
+  /** Report a noteworthy non-error condition, grouped by its message text. */
+  captureMessage(message: string, level: Severity = "info", context: CaptureContext = {}): void {
+    const value = typeof message === "string" ? message : String(message);
+    this.dispatch(
+      {
+        errorSignature: computeFingerprint("Message", value),
+        type: "Message",
+        value,
+        level,
+        handled: context.handled ?? true,
+      },
+      context,
+    );
+  }
+
+  /** Flush the transport's buffer now. Resolves even when the SDK is disabled. */
+  flush(): Promise<void> {
+    return this.transport?.flush() ?? Promise.resolve();
+  }
+
+  /** Stop the transport (its timer) and drain what remains. */
+  close(): Promise<void> {
+    return this.transport?.close() ?? Promise.resolve();
+  }
+
+  /** Assemble, scrub, run `beforeSend`, and enqueue — swallowing any failure. */
+  private dispatch(
+    partial: Pick<FixbackErrorEvent, "errorSignature" | "type" | "value" | "handled"> &
+      Partial<Pick<FixbackErrorEvent, "level" | "errorFrames">>,
+    context: CaptureContext,
+  ): void {
+    if (!this.config.enabled || !this.transport) return;
+    try {
+      const event: FixbackErrorEvent = {
+        errorSignature: partial.errorSignature,
+        type: partial.type,
+        value: partial.value,
+        handled: partial.handled,
+        level: partial.level,
+        environment: this.config.environment,
+        release: this.config.release,
+        errorFrames: partial.errorFrames,
+        server: mergeServerContext(currentServerContext(), context.server),
+      };
+      if (this.config.scrub) applyDefaultScrub(event);
+      const finalised = this.runBeforeSend(event);
+      if (!finalised) return; // dropped at the choke point — no transport
+      this.transport.enqueue(toPayload(finalised));
+    } catch {
+      // Capture must never throw into the host (story 34).
+    }
+  }
+
+  /** Run the project hook after the default scrubbers; a throwing hook is a no-op. */
+  private runBeforeSend(event: FixbackErrorEvent): FixbackErrorEvent | null {
+    const hook = this.config.beforeSend;
+    if (!hook) return event;
+    try {
+      return hook(event) ?? null;
+    } catch {
+      return event; // a buggy hook never breaks the report path nor leaks unscrubbed data
+    }
+  }
+}
+
+/** The built-in default scrub: re-sweep frame URLs through the shared-core scrubber. */
+function applyDefaultScrub(event: FixbackErrorEvent): void {
+  if (event.errorFrames && event.errorFrames.length > 0) {
+    event.errorFrames = event.errorFrames.map((frame) => ({
+      ...frame,
+      file: scrubUrl(frame.file),
+    }));
+  }
+}
+
+/** Project the event onto the wire payload, dropping the event-only fields. */
+function toPayload(event: FixbackErrorEvent): ServerErrorPayload {
+  const payload: MutablePayload = { errorSignature: event.errorSignature };
+  if (event.handled !== undefined) payload.handled = event.handled;
+  if (event.environment !== undefined) payload.environment = event.environment;
+  if (event.release !== undefined) payload.release = event.release;
+  if (event.occurrences !== undefined) payload.occurrences = event.occurrences;
+  if (event.errorFrames && event.errorFrames.length > 0) payload.errorFrames = event.errorFrames;
+  if (event.server) payload.server = event.server;
+  return payload;
+}
+
+// --- Module-level singleton API ----------------------------------------------
+
+let activeClient: FixbackClient | null = null;
+let activeUninstall: (() => void) | null = null;
+
+/**
+ * Initialise the SDK: resolve the config, replace any previous client (closing it and
+ * removing its process handlers), install the polite process handlers, and return the
+ * active {@link FixbackClient}. Fail-quiet — a missing secret key yields an inert
+ * client (no handlers, no transport) rather than throwing.
+ */
+export function init(options: InitOptions, deps?: ClientDeps): FixbackClient {
+  const previousClient = activeClient;
+  const previousUninstall = activeUninstall;
+  if (previousUninstall) previousUninstall();
+  if (previousClient) void previousClient.close();
+
+  const config = resolveConfig(options);
+  const client = new FixbackClient(config, deps);
+  activeClient = client;
+  activeUninstall =
+    config.enabled && (config.captureUncaughtException || config.captureUnhandledRejection)
+      ? installProcessHandlers(
+          client,
+          {
+            captureUncaughtException: config.captureUncaughtException,
+            captureUnhandledRejection: config.captureUnhandledRejection,
+          },
+          { process: deps?.process, onFatalError: deps?.onFatalError },
+        )
+      : null;
+  return client;
+}
+
+/** The active client set by {@link init}, or `null` before the first `init`. */
+export function getClient(): FixbackClient | null {
+  return activeClient;
+}
+
+/** Report a caught/manual error through the active client (no-op before `init`). */
+export function captureException(error: unknown, context?: CaptureContext): void {
+  activeClient?.captureException(error, context);
+}
+
+/** Report a message through the active client (no-op before `init`). */
+export function captureMessage(message: string, level?: Severity, context?: CaptureContext): void {
+  activeClient?.captureMessage(message, level, context);
+}
+
+/** Flush the active client's buffer (no-op before `init`). */
+export function flush(): Promise<void> {
+  return activeClient?.flush() ?? Promise.resolve();
+}
+
+/** Close and clear the active client, removing its process handlers (no-op before `init`). */
+export function close(): Promise<void> {
+  const current = activeClient;
+  const uninstall = activeUninstall;
+  activeClient = null;
+  activeUninstall = null;
+  if (uninstall) uninstall();
+  return current?.close() ?? Promise.resolve();
+}

package/src/config.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+
+import { DEFAULT_API_URL, resolveConfig } from "./config";
+
+describe("resolveConfig", () => {
+  it("enables capture and derives the ingest endpoint from a secret key", () => {
+    const config = resolveConfig({ secretKey: "sk_live_abc" });
+    expect(config.enabled).toBe(true);
+    expect(config.secretKey).toBe("sk_live_abc");
+    expect(config.apiUrl).toBe(DEFAULT_API_URL);
+    expect(config.errorsEndpoint).toBe(`${DEFAULT_API_URL}/api/errors`);
+  });
+
+  it("stays disabled (fail-quiet) when no secret key is given", () => {
+    // Misconfiguration must never throw — the host server keeps running (story 34).
+    expect(() => resolveConfig({ secretKey: "" })).not.toThrow();
+    expect(resolveConfig({ secretKey: "" }).enabled).toBe(false);
+    expect(resolveConfig({ secretKey: "   " }).enabled).toBe(false);
+    // @ts-expect-error — a caller may omit the key entirely at runtime.
+    expect(resolveConfig({}).enabled).toBe(false);
+  });
+
+  it("honours an explicit enabled:false gate even with a valid key (story 35)", () => {
+    const config = resolveConfig({ secretKey: "sk_live_abc", enabled: false });
+    expect(config.enabled).toBe(false);
+  });
+
+  it("normalises the api url (trailing slashes stripped) before building the endpoint", () => {
+    const config = resolveConfig({
+      secretKey: "sk_live_abc",
+      apiUrl: "https://fixback.acme.dev/",
+    });
+    expect(config.apiUrl).toBe("https://fixback.acme.dev");
+    expect(config.errorsEndpoint).toBe("https://fixback.acme.dev/api/errors");
+  });
+
+  it("carries environment and release through, dropping blank strings", () => {
+    const config = resolveConfig({
+      secretKey: "sk_live_abc",
+      environment: "production",
+      release: "  1.4.2  ",
+    });
+    expect(config.environment).toBe("production");
+    expect(config.release).toBe("1.4.2");
+    expect(resolveConfig({ secretKey: "sk", environment: "  " }).environment).toBeUndefined();
+  });
+
+  it("defaults the batching knobs and clamps the batch to the server maximum", () => {
+    const config = resolveConfig({ secretKey: "sk_live_abc" });
+    expect(config.maxBatchSize).toBe(100);
+    expect(config.flushIntervalMs).toBeGreaterThan(0);
+    expect(config.maxQueueSize).toBeGreaterThan(0);
+
+    // The server rejects batches over 500; a larger request is clamped, not sent oversized.
+    expect(resolveConfig({ secretKey: "sk", maxBatchSize: 5000 }).maxBatchSize).toBe(500);
+    expect(resolveConfig({ secretKey: "sk", maxBatchSize: 0 }).maxBatchSize).toBe(1);
+  });
+
+  it("defaults the process-handler gates on and honours explicit opt-outs", () => {
+    const on = resolveConfig({ secretKey: "sk" });
+    expect(on.captureUncaughtException).toBe(true);
+    expect(on.captureUnhandledRejection).toBe(true);
+
+    const off = resolveConfig({
+      secretKey: "sk",
+      captureUncaughtException: false,
+      captureUnhandledRejection: false,
+    });
+    expect(off.captureUncaughtException).toBe(false);
+    expect(off.captureUnhandledRejection).toBe(false);
+  });
+
+  it("lower-cases the correlation-id header name", () => {
+    expect(resolveConfig({ secretKey: "sk", requestIdHeader: "X-Trace-Id" }).requestIdHeader).toBe(
+      "x-trace-id",
+    );
+    expect(resolveConfig({ secretKey: "sk" }).requestIdHeader).toBe("x-request-id");
+  });
+});

package/src/config.ts

@@ -0,0 +1,131 @@
+/**
+ * The `init` options and their resolution into a validated {@link ResolvedConfig}.
+ *
+ * Resolution is **fail-quiet** (spec #224, story 34): it never throws. A missing
+ * secret key or an explicit `enabled: false` leaves the SDK inert (`enabled: false`)
+ * rather than raising — a Fixback misconfiguration must never break the host server.
+ * Numeric knobs are clamped to safe bounds (the batch to the server's 500-item cap)
+ * instead of rejected.
+ */
+
+import type { BeforeSend } from "./wire";
+
+/** The default Fixback ingest origin, shared with the browser and Expo SDKs. */
+export const DEFAULT_API_URL = "https://api.fixback.dev";
+
+/** The largest batch the server-error endpoint accepts (`MAX_SERVER_ERROR_BATCH`). */
+const SERVER_MAX_BATCH = 500;
+
+const DEFAULT_MAX_BATCH_SIZE = 100;
+const DEFAULT_FLUSH_INTERVAL_MS = 5_000;
+const DEFAULT_MAX_QUEUE_SIZE = 1_024;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_REQUEST_ID_HEADER = "x-request-id";
+
+/** Options for {@link init} — the one call that wires backend capture. */
+export interface InitOptions {
+  /**
+   * The Project **secret key** (`sk_…`) the backend authenticates with — the same
+   * key `npx fixback sourcemaps upload` uses (never the publishable key). Without it
+   * the SDK stays inert.
+   */
+  readonly secretKey: string;
+  /** The Fixback ingest origin. Defaults to {@link DEFAULT_API_URL}. */
+  readonly apiUrl?: string;
+  /** The deploy environment (`production` / `staging` / …) stamped on every error. */
+  readonly environment?: string;
+  /** The build **Release** the captured stacks symbolicate against. */
+  readonly release?: string;
+  /** A hook to redact or drop an event before it leaves the process (return `null` to drop). */
+  readonly beforeSend?: BeforeSend;
+  /** Run the built-in default scrubbers before `beforeSend`. Defaults to `true`. */
+  readonly scrub?: boolean;
+  /** Master gate — set `false` to disable all capture (e.g. in local dev). Defaults to `true`. */
+  readonly enabled?: boolean;
+  /** Install the polite `uncaughtException` handler. Defaults to `true`. */
+  readonly captureUncaughtException?: boolean;
+  /** Install the polite `unhandledRejection` handler. Defaults to `true`. */
+  readonly captureUnhandledRejection?: boolean;
+  /** Flush the buffer once it reaches this many errors. Defaults to `100`; capped at `500`. */
+  readonly maxBatchSize?: number;
+  /** Flush a non-empty buffer at least this often, in ms. Defaults to `5000`. */
+  readonly flushIntervalMs?: number;
+  /** Cap the in-memory buffer so a flood can't grow it without bound. Defaults to `1024`. */
+  readonly maxQueueSize?: number;
+  /** Overall per-request transport timeout in ms; `0` disables. Defaults to `30000`. */
+  readonly timeoutMs?: number;
+  /** The header a correlation id is read from. Defaults to `x-request-id`. */
+  readonly requestIdHeader?: string;
+}
+
+/** The validated, defaulted configuration a {@link FixbackClient} runs on. */
+export interface ResolvedConfig {
+  readonly enabled: boolean;
+  readonly secretKey: string;
+  readonly apiUrl: string;
+  readonly errorsEndpoint: string;
+  readonly environment?: string;
+  readonly release?: string;
+  readonly beforeSend?: BeforeSend;
+  readonly scrub: boolean;
+  readonly captureUncaughtException: boolean;
+  readonly captureUnhandledRejection: boolean;
+  readonly maxBatchSize: number;
+  readonly flushIntervalMs: number;
+  readonly maxQueueSize: number;
+  readonly timeoutMs: number;
+  readonly requestIdHeader: string;
+}
+
+/** Trim a string option, returning `undefined` for a blank or non-string value. */
+function trimmed(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const out = value.trim();
+  return out.length > 0 ? out : undefined;
+}
+
+/** Normalise an api base URL: trim and strip trailing slashes. */
+function normalizeApiUrl(value: string | undefined): string {
+  const base = trimmed(value) ?? DEFAULT_API_URL;
+  return base.replace(/\/+$/, "") || DEFAULT_API_URL;
+}
+
+/** Clamp a positive-integer option to `[min, max]`, falling back to `fallback`. */
+function clampInt(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(value)));
+}
+
+/**
+ * Resolve raw {@link InitOptions} into a validated {@link ResolvedConfig}. Never
+ * throws: without a usable secret key (or with `enabled: false`) the result is
+ * inert (`enabled: false`), so an inert client can no-op every capture.
+ */
+export function resolveConfig(options: InitOptions): ResolvedConfig {
+  const secretKey = trimmed(options.secretKey) ?? "";
+  const apiUrl = normalizeApiUrl(options.apiUrl);
+  const enabled = options.enabled !== false && secretKey.length > 0;
+
+  return {
+    enabled,
+    secretKey,
+    apiUrl,
+    errorsEndpoint: `${apiUrl}/api/errors`,
+    environment: trimmed(options.environment),
+    release: trimmed(options.release),
+    beforeSend: typeof options.beforeSend === "function" ? options.beforeSend : undefined,
+    scrub: options.scrub !== false,
+    captureUncaughtException: options.captureUncaughtException !== false,
+    captureUnhandledRejection: options.captureUnhandledRejection !== false,
+    maxBatchSize: clampInt(options.maxBatchSize, DEFAULT_MAX_BATCH_SIZE, 1, SERVER_MAX_BATCH),
+    flushIntervalMs: clampInt(
+      options.flushIntervalMs,
+      DEFAULT_FLUSH_INTERVAL_MS,
+      0,
+      Number.MAX_SAFE_INTEGER,
+    ),
+    maxQueueSize: clampInt(options.maxQueueSize, DEFAULT_MAX_QUEUE_SIZE, 1, Number.MAX_SAFE_INTEGER),
+    timeoutMs: clampInt(options.timeoutMs, DEFAULT_TIMEOUT_MS, 0, Number.MAX_SAFE_INTEGER),
+    requestIdHeader: (trimmed(options.requestIdHeader) ?? DEFAULT_REQUEST_ID_HEADER).toLowerCase(),
+  };
+}

package/src/context.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createRequestContextMiddleware,
+  currentServerContext,
+  deriveServerContext,
+  getRequestStore,
+  runWithRequestStore,
+  setRequestUser,
+} from "./context";
+import { routePatternOf } from "./http";
+
+describe("request store (AsyncLocalStorage)", () => {
+  it("exposes the active store inside the scope and nothing outside it", () => {
+    expect(getRequestStore()).toBeUndefined();
+    runWithRequestStore({ req: { method: "GET" } }, () => {
+      expect(getRequestStore()?.req.method).toBe("GET");
+    });
+    expect(getRequestStore()).toBeUndefined();
+  });
+
+  it("setRequestUser writes onto the active store and is a no-op outside a request", () => {
+    expect(() => setRequestUser("u-1")).not.toThrow();
+    runWithRequestStore({ req: {} }, () => {
+      setRequestUser("user-42");
+      expect(getRequestStore()?.user).toBe("user-42");
+    });
+  });
+});
+
+describe("deriveServerContext", () => {
+  it("derives method, route pattern, status, requestId and user — never the concrete path", () => {
+    const ctx = deriveServerContext({
+      req: { method: "POST", route: { path: "/users/:id" }, path: "/users/42" },
+      res: { statusCode: 500 },
+      requestId: "corr-9",
+      user: "user-42",
+    });
+    expect(ctx).toEqual({
+      method: "POST",
+      route: "/users/:id",
+      statusCode: 500,
+      requestId: "corr-9",
+      user: "user-42",
+    });
+    // The concrete path (with the value 42) is never carried.
+    expect(JSON.stringify(ctx)).not.toContain("/users/42");
+  });
+
+  it("returns undefined for no store and omits fields it can't resolve", () => {
+    expect(deriveServerContext(undefined)).toBeUndefined();
+    // No route matched yet, no status, no id → an empty context collapses to undefined.
+    expect(deriveServerContext({ req: {} })).toBeUndefined();
+    expect(deriveServerContext({ req: { method: "GET" } })).toEqual({ method: "GET" });
+  });
+});
+
+describe("createRequestContextMiddleware", () => {
+  it("opens a store carrying a generated correlation id and propagates across awaits", async () => {
+    const middleware = createRequestContextMiddleware();
+    const req = { method: "GET", route: { path: "/health" } };
+    const res = { statusCode: 200 };
+
+    const store = await new Promise<ReturnType<typeof getRequestStore>>((resolve) => {
+      middleware(req, res, async () => {
+        await Promise.resolve();
+        resolve(getRequestStore());
+      });
+    });
+
+    expect(store?.req).toBe(req);
+    expect(store?.res).toBe(res);
+    expect(typeof store?.requestId).toBe("string");
+    expect(store?.requestId?.length).toBeGreaterThan(0);
+  });
+
+  it("adopts an inbound correlation-id header when present", () => {
+    const middleware = createRequestContextMiddleware({ requestIdHeader: "x-request-id" });
+    const req = { method: "GET", headers: { "x-request-id": "trace-abc" }, route: { path: "/x" } };
+    let seen: string | undefined;
+    middleware(req, { statusCode: 200 }, () => {
+      seen = currentServerContext()?.requestId;
+    });
+    expect(seen).toBe("trace-abc");
+  });
+});
+
+describe("routePatternOf", () => {
+  it("joins a mounted router's base with the route pattern", () => {
+    expect(routePatternOf({ baseUrl: "/api", route: { path: "/users/:id" } })).toBe(
+      "/api/users/:id",
+    );
+    expect(routePatternOf({ route: { path: "/health" } })).toBe("/health");
+  });
+
+  it("omits the route entirely when none matched (never leaks the concrete path)", () => {
+    expect(routePatternOf({ path: "/users/42" })).toBeUndefined();
+  });
+});