midline-agent 0.2.0 → 0.4.0

package/src/browser/index.ts

@@ -0,0 +1,74 @@
+/**
+ * midline-agent/browser — error, network and Web Vitals monitoring for web apps.
+ *
+ *   import * as Midline from "midline-agent/browser";
+ *   Midline.init({ apiKey: "pk_…", service: "checkout-web" });
+ *
+ * Framework-agnostic: it instruments the page (window errors, fetch, XHR,
+ * history), not React, Vue or Angular, so it works under all of them. Call
+ * `captureException` from a framework's own error hook for errors it swallows.
+ */
+import { BrowserClient } from "./client.js";
+import type { CaptureContext, MidlineBrowserConfig, MidlineUser } from "./types.js";
+import type { EventSeverity } from "../types.js";
+
+let client: BrowserClient | undefined;
+
+/**
+ * Starts monitoring. Safe to call during server-side rendering (it does nothing
+ * without a window) and safe to call twice (the first instance is closed).
+ * A bad config logs one console warning and leaves the page untouched.
+ */
+export function init(config: MidlineBrowserConfig): void {
+  if (client) void client.close();
+  client = BrowserClient.create(config);
+}
+
+/** Reports an error your code caught, e.g. from a React error boundary. */
+export function captureException(error: unknown, context?: CaptureContext): void {
+  client?.captureException(error, context);
+}
+
+export function captureMessage(message: string, severity?: EventSeverity, context?: CaptureContext): void {
+  client?.captureMessage(message, severity, context);
+}
+
+/** Attaches a user id to later events. Pass null on sign-out. */
+export function setUser(user: MidlineUser | null): void {
+  client?.setUser(user);
+}
+
+export function setTag(key: string, value: string): void {
+  client?.setTag(key, value);
+}
+
+export function addBreadcrumb(message: string, type?: string): void {
+  client?.addBreadcrumb(message, type);
+}
+
+/** Sends anything queued now. */
+export function flush(): Promise<void> {
+  return client ? client.flush() : Promise.resolve();
+}
+
+/** Restores everything the SDK wrapped and sends what's queued. */
+export async function close(): Promise<void> {
+  const closing = client;
+  client = undefined;
+  await closing?.close();
+}
+
+export const Midline = { init, captureException, captureMessage, setUser, setTag, addBreadcrumb, flush, close };
+
+export { resolveBatchUrl } from "./client.js";
+export { BROWSER_SDK_VERSION } from "./version.js";
+export type {
+  BrowserEvent,
+  CaptureContext,
+  ConsoleLevel,
+  MidlineBrowserConfig,
+  MidlineUser,
+  RequestCapture,
+} from "./types.js";
+export type { VitalName, VitalRating, VitalsReport } from "./vitals.js";
+export type { EventSeverity } from "../types.js";

package/src/browser/instrument.ts

@@ -0,0 +1,275 @@
+import type { ConsoleLevel } from "./types.js";
+
+/** A finished fetch or XHR call. `status` is absent when no response arrived. */
+export interface RequestRecord {
+  kind: "fetch" | "xhr";
+  method: string;
+  url: URL;
+  status?: number;
+  durationMs: number;
+  aborted?: boolean;
+  spanId?: string;
+}
+
+export interface Propagation {
+  headers: Record<string, string>;
+  spanId: string;
+}
+
+export interface InstrumentHooks {
+  onError(error: unknown, mechanism: "onerror" | "unhandledrejection", location?: ErrorLocation): void;
+  onRequest(record: RequestRecord): void;
+  onConsole(level: ConsoleLevel, args: unknown[]): void;
+  onNavigation(from: string, to: string): void;
+  /** Headers to add to a request, or undefined to leave it untouched. */
+  propagation(url: URL): Propagation | undefined;
+  /** Midline's own delivery requests, which are never recorded. */
+  isOwnRequest(url: URL): boolean;
+}
+
+export interface ErrorLocation {
+  message?: string;
+  filename?: string;
+  lineno?: number;
+  colno?: number;
+}
+
+type Teardown = () => void;
+
+const noop: Teardown = () => {};
+
+/** Instrumentation runs inside the page's own calls; a bug here must never become the page's bug. */
+function safely(fn: () => void): void {
+  try {
+    fn();
+  } catch {
+    // swallowed on purpose
+  }
+}
+
+const now = (): number =>
+  typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+
+export function instrumentErrors(win: Window, hooks: InstrumentHooks): Teardown {
+  // Registered in the bubble phase: resource load failures (img, script) don't
+  // bubble to window, so only script errors arrive here.
+  const onError = (event: Event) =>
+    safely(() => {
+      const e = event as ErrorEvent;
+      hooks.onError(e.error ?? e.message, "onerror", {
+        message: e.message,
+        filename: e.filename,
+        lineno: e.lineno,
+        colno: e.colno,
+      });
+    });
+  const onRejection = (event: Event) =>
+    safely(() => hooks.onError((event as PromiseRejectionEvent).reason, "unhandledrejection"));
+
+  win.addEventListener("error", onError);
+  win.addEventListener("unhandledrejection", onRejection);
+  return () => {
+    win.removeEventListener("error", onError);
+    win.removeEventListener("unhandledrejection", onRejection);
+  };
+}
+
+export function instrumentFetch(win: Window, original: typeof fetch, hooks: InstrumentHooks): Teardown {
+  if (typeof original !== "function") return noop;
+  const RequestCtor = typeof Request === "function" ? Request : undefined;
+
+  const wrapped = function fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+    let url: URL | undefined;
+    let method = "GET";
+    let nextInit = init;
+    let spanId: string | undefined;
+
+    try {
+      const isRequest = RequestCtor !== undefined && input instanceof RequestCtor;
+      url = new URL(isRequest ? (input as Request).url : String(input), win.location.href);
+      method = String(init?.method ?? (isRequest ? (input as Request).method : "GET")).toUpperCase();
+
+      if (hooks.isOwnRequest(url)) {
+        url = undefined;
+      } else {
+        const propagation = hooks.propagation(url);
+        if (propagation) {
+          // fetch(request, init) replaces the request's headers with init's, so
+          // start from whichever the caller actually supplied.
+          const headers = new Headers(init?.headers ?? (isRequest ? (input as Request).headers : undefined));
+          for (const [name, value] of Object.entries(propagation.headers)) {
+            if (!headers.has(name)) headers.set(name, value);
+          }
+          nextInit = { ...init, headers };
+          spanId = propagation.spanId;
+        }
+      }
+    } catch {
+      url = undefined;
+      nextInit = init;
+    }
+
+    const startedAt = now();
+    const promise = original.call(win, input, nextInit);
+    if (url) {
+      const target = url;
+      promise.then(
+        (response) =>
+          safely(() =>
+            hooks.onRequest({ kind: "fetch", method, url: target, status: response.status || undefined, durationMs: now() - startedAt, spanId }),
+          ),
+        (error) =>
+          safely(() =>
+            hooks.onRequest({
+              kind: "fetch",
+              method,
+              url: target,
+              durationMs: now() - startedAt,
+              aborted: (error as Error | undefined)?.name === "AbortError",
+              spanId,
+            }),
+          ),
+      );
+    }
+    return promise;
+  };
+
+  win.fetch = wrapped as typeof fetch;
+  return () => {
+    if (win.fetch === wrapped) win.fetch = original;
+  };
+}
+
+interface XhrState {
+  method: string;
+  url?: URL;
+  headerNames: Set<string>;
+}
+
+export function instrumentXhr(win: Window, hooks: InstrumentHooks): Teardown {
+  const Xhr = (win as Window & { XMLHttpRequest?: typeof XMLHttpRequest }).XMLHttpRequest;
+  if (typeof Xhr !== "function") return noop;
+
+  const proto = Xhr.prototype;
+  const originalOpen = proto.open;
+  const originalSend = proto.send;
+  const originalSetRequestHeader = proto.setRequestHeader;
+  const states = new WeakMap<XMLHttpRequest, XhrState>();
+
+  const open = function (this: XMLHttpRequest, method: string, url: string | URL, ...rest: unknown[]) {
+    safely(() => {
+      states.set(this, {
+        method: String(method || "GET").toUpperCase(),
+        url: new URL(String(url), win.location.href),
+        headerNames: new Set(),
+      });
+    });
+    return (originalOpen as (...args: unknown[]) => void).apply(this, [method, url, ...rest]);
+  };
+
+  const setRequestHeader = function (this: XMLHttpRequest, name: string, value: string) {
+    safely(() => states.get(this)?.headerNames.add(String(name).toLowerCase()));
+    return originalSetRequestHeader.call(this, name, value);
+  };
+
+  const send = function (this: XMLHttpRequest, body?: Document | XMLHttpRequestBodyInit | null) {
+    const state = states.get(this);
+    if (state?.url && !hooks.isOwnRequest(state.url)) {
+      const url = state.url;
+      let spanId: string | undefined;
+      safely(() => {
+        const propagation = hooks.propagation(url);
+        if (!propagation) return;
+        for (const [name, value] of Object.entries(propagation.headers)) {
+          // setRequestHeader appends, so a caller's own traceparent would become "a, b".
+          if (!state.headerNames.has(name)) originalSetRequestHeader.call(this, name, value);
+        }
+        spanId = propagation.spanId;
+      });
+
+      const startedAt = now();
+      let aborted = false;
+      this.addEventListener("abort", () => {
+        aborted = true;
+      });
+      this.addEventListener("loadend", () =>
+        safely(() =>
+          hooks.onRequest({
+            kind: "xhr",
+            method: state.method,
+            url,
+            status: this.status || undefined,
+            durationMs: now() - startedAt,
+            aborted,
+            spanId,
+          }),
+        ),
+      );
+    }
+    return originalSend.call(this, body);
+  };
+
+  proto.open = open as typeof proto.open;
+  proto.setRequestHeader = setRequestHeader;
+  proto.send = send;
+  return () => {
+    if (proto.open === open) proto.open = originalOpen;
+    if (proto.setRequestHeader === setRequestHeader) proto.setRequestHeader = originalSetRequestHeader;
+    if (proto.send === send) proto.send = originalSend;
+  };
+}
+
+export function instrumentConsole(target: Console, levels: ConsoleLevel[], hooks: InstrumentHooks): Teardown {
+  const restores: Teardown[] = [];
+  for (const level of levels) {
+    const original = target[level];
+    if (typeof original !== "function") continue;
+    const wrapped = function (...args: unknown[]) {
+      safely(() => hooks.onConsole(level, args));
+      return original.apply(target, args);
+    };
+    target[level] = wrapped;
+    restores.push(() => {
+      if (target[level] === wrapped) target[level] = original;
+    });
+  }
+  return () => restores.forEach((restore) => restore());
+}
+
+/** Single-page-app route changes, for breadcrumbs and to start a fresh trace per view. */
+export function instrumentHistory(win: Window, hooks: InstrumentHooks): Teardown {
+  const history = win.history;
+  if (!history || typeof history.pushState !== "function") return noop;
+
+  let last = win.location.href;
+  const changed = () =>
+    safely(() => {
+      const next = win.location.href;
+      if (next === last) return;
+      const previous = last;
+      last = next;
+      hooks.onNavigation(previous, next);
+    });
+
+  const originalPush = history.pushState;
+  const originalReplace = history.replaceState;
+  const push = function (this: History, ...args: Parameters<History["pushState"]>) {
+    const result = originalPush.apply(this, args);
+    changed();
+    return result;
+  };
+  const replace = function (this: History, ...args: Parameters<History["replaceState"]>) {
+    const result = originalReplace.apply(this, args);
+    changed();
+    return result;
+  };
+
+  history.pushState = push;
+  history.replaceState = replace;
+  win.addEventListener("popstate", changed);
+  return () => {
+    if (history.pushState === push) history.pushState = originalPush;
+    if (history.replaceState === replace) history.replaceState = originalReplace;
+    win.removeEventListener("popstate", changed);
+  };
+}

package/src/browser/transport.ts

@@ -0,0 +1,184 @@
+import type { BrowserEvent } from "./types.js";
+
+/** Browsers cap the combined body of in-flight keepalive requests at 64 KiB. */
+const KEEPALIVE_BYTES = 60_000;
+const MAX_RETRY_DELAY_MS = 300_000;
+
+type Outcome = "ok" | "retry" | "drop" | "stop";
+
+export interface TransportOptions {
+  batchUrl: string;
+  apiKey: string;
+  /** The page's fetch as it was before instrumentation, so delivery is never recorded as traffic. */
+  fetch: typeof fetch;
+  flushIntervalMs: number;
+  maxBatchSize: number;
+  maxQueueSize: number;
+  debug: (message: string) => void;
+  /** Called once when the server refuses the key; retrying could not help. */
+  onStop: (message: string) => void;
+}
+
+/**
+ * Batches events and posts them to the ingest API. It never throws into the page
+ * and never blocks it: a Midline outage costs queued telemetry, not the app.
+ */
+export class BrowserTransport {
+  private queue: BrowserEvent[] = [];
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private sending = false;
+  private stopped = false;
+  private retryAt = 0;
+  private backoffMs = 0;
+  dropped = 0;
+
+  constructor(private readonly options: TransportOptions) {}
+
+  start(): void {
+    if (this.timer || this.stopped) return;
+    this.timer = setInterval(() => void this.flush(), this.options.flushIntervalMs);
+  }
+
+  enqueue(event: BrowserEvent): void {
+    if (this.stopped) return;
+    this.queue.push(event);
+    this.trim();
+    if (this.queue.length >= this.options.maxBatchSize && Date.now() >= this.retryAt) {
+      void this.flush();
+    }
+  }
+
+  get size(): number {
+    return this.queue.length;
+  }
+
+  /** Sends everything queued, one batch at a time, unless Midline asked us to back off. */
+  async flush(): Promise<void> {
+    if (this.stopped || this.sending || !this.queue.length || Date.now() < this.retryAt) return;
+    this.sending = true;
+    try {
+      while (this.queue.length && !this.stopped) {
+        const batch = this.queue.splice(0, this.options.maxBatchSize);
+        const outcome = await this.send(batch, false);
+        if (outcome === "retry") {
+          this.queue.unshift(...batch);
+          this.trim();
+          return;
+        }
+        if (outcome === "stop") return;
+      }
+    } finally {
+      this.sending = false;
+    }
+  }
+
+  /**
+   * The page is being hidden and may never come back. Hands whatever is queued to
+   * keepalive requests without waiting on them; an in-flight regular flush is left
+   * alone, since its batch already left the queue.
+   */
+  flushOnHide(): void {
+    if (this.stopped || !this.queue.length) return;
+    let budget = KEEPALIVE_BYTES;
+    while (this.queue.length) {
+      const batch: BrowserEvent[] = [];
+      let bytes = 12;
+      while (this.queue.length && batch.length < this.options.maxBatchSize) {
+        const size = JSON.stringify(this.queue[0]).length + 1;
+        if (batch.length && bytes + size > budget) break;
+        batch.push(this.queue.shift()!);
+        bytes += size;
+      }
+      budget -= bytes;
+      void this.send(batch, budget > 0);
+      if (budget <= 0) break;
+    }
+  }
+
+  stop(): void {
+    this.stopped = true;
+    this.queue = [];
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+  }
+
+  private trim(): void {
+    const excess = this.queue.length - this.options.maxQueueSize;
+    if (excess > 0) {
+      this.queue.splice(0, excess);
+      this.dropped += excess;
+    }
+  }
+
+  private async send(batch: BrowserEvent[], keepalive: boolean): Promise<Outcome> {
+    let response: Response;
+    try {
+      response = await this.options.fetch(this.options.batchUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "X-API-Key": this.options.apiKey },
+        body: JSON.stringify({ events: batch }),
+        keepalive,
+        credentials: "omit",
+        mode: "cors",
+      });
+    } catch (error) {
+      // Offline, blocked by an extension, or a server that doesn't answer CORS.
+      this.options.debug(`midline: could not reach Midline (${describe(error)}); will retry.`);
+      this.backOff();
+      return "retry";
+    }
+
+    const { status } = response;
+    if (status >= 200 && status < 300) {
+      this.backoffMs = 0;
+      this.retryAt = 0;
+      return "ok";
+    }
+    if (status === 401 || status === 403) {
+      const detail = await serverMessage(response);
+      this.stop();
+      this.options.onStop(
+        `midline: the Midline server refused this key (HTTP ${status}${detail ? `: ${detail}` : ""}). ` +
+          "Browser monitoring is now off.",
+      );
+      return "stop";
+    }
+    if (status === 408 || status === 429 || status >= 500) {
+      this.backOff(parseRetryAfter(response.headers.get("retry-after")));
+      this.options.debug(`midline: Midline answered HTTP ${status}; events are kept and retried.`);
+      return "retry";
+    }
+    this.dropped += batch.length;
+    const detail = await serverMessage(response);
+    this.options.debug(`midline: Midline rejected ${batch.length} events (HTTP ${status}${detail ? `: ${detail}` : ""}).`);
+    return "drop";
+  }
+
+  private backOff(retryAfterMs = 0): void {
+    this.backoffMs = Math.min(Math.max(this.backoffMs * 2, 1000), MAX_RETRY_DELAY_MS);
+    this.retryAt = Date.now() + Math.max(this.backoffMs, Math.min(retryAfterMs, MAX_RETRY_DELAY_MS));
+  }
+}
+
+function parseRetryAfter(value: string | null): number {
+  if (!value) return 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+  const date = Date.parse(value);
+  return Number.isFinite(date) ? Math.max(0, date - Date.now()) : 0;
+}
+
+async function serverMessage(response: Response): Promise<string> {
+  try {
+    const text = await response.text();
+    const parsed = JSON.parse(text);
+    const message = Array.isArray(parsed?.message) ? parsed.message.join("; ") : parsed?.message;
+    return typeof message === "string" ? message.slice(0, 300) : "";
+  } catch {
+    return "";
+  }
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/browser/types.ts

@@ -0,0 +1,105 @@
+import type { EventCategory, EventSeverity } from "../types.js";
+
+/** Which fetch/XHR calls become events. Every call is a breadcrumb regardless. */
+export type RequestCapture = "failed" | "all" | false;
+
+export type ConsoleLevel = "error" | "warn" | "info" | "log" | "debug";
+
+/** Kept deliberately small: an id is enough to find a user's sessions, and anything more is personal data. */
+export interface MidlineUser {
+  id?: string;
+  username?: string;
+}
+
+export interface MidlineBrowserConfig {
+  /**
+   * A **browser key** (`pk_…`) from the Midline dashboard. Browser keys are public
+   * and only accepted from the origins listed on the key. Server keys (`ak_…`) are
+   * secrets; the SDK refuses to start with one, and the server refuses them from
+   * browsers anyway.
+   */
+  apiKey: string;
+  /** The Midline server. Default `https://api.usemidline.com`. `http://` only for localhost. */
+  endpoint?: string;
+
+  /** Name for this app, e.g. `checkout-web`. */
+  service?: string;
+  environment?: string;
+  /** Build or version tag, so an error can be tied to the deploy that introduced it. */
+  release?: string;
+  /** Set to false to keep the SDK inert (e.g. in local development). */
+  enabled?: boolean;
+
+  /** Uncaught errors and unhandled promise rejections. Default true. */
+  captureErrors?: boolean;
+  /** fetch and XMLHttpRequest calls. Default `"failed"`: 4xx, 5xx and network errors. */
+  captureRequests?: RequestCapture;
+  /**
+   * Also send console output as `console` events. `true` means `["error", "warn"]`.
+   * Default false. Wrapping console makes devtools attribute log lines to the SDK,
+   * which is why it is opt-in.
+   */
+  captureConsole?: boolean | ConsoleLevel[];
+  /** LCP, INP, CLS, FCP and TTFB, reported once when the page is first hidden. Default true. */
+  captureWebVitals?: boolean;
+
+  /**
+   * Requests that get a W3C `traceparent` header, so the backend's midline-agent
+   * links its request to this page. Strings match as URL prefixes (or path prefixes
+   * when they start with `/`), RegExps against the full URL. Default: same-origin
+   * requests only, because a new header on a cross-origin call makes that API
+   * answer a CORS preflight.
+   */
+  tracePropagationTargets?: Array<string | RegExp>;
+  /** Error messages to drop. Strings match as substrings. */
+  ignoreErrors?: Array<string | RegExp>;
+  /** Request URLs never recorded, e.g. analytics beacons. Strings match as substrings. */
+  ignoreUrls?: Array<string | RegExp>;
+
+  /** Fraction of events sent, 0–1. Default 1. */
+  sampleRate?: number;
+  /** Ceiling on events per minute, so an error in a render loop can't flood the project. Default 120. */
+  maxEventsPerMinute?: number;
+  /** Extra field names to redact, on top of the built-in list. */
+  redactFields?: string[];
+  /**
+   * Last look at every event. Return null to drop it. Change `payload` and
+   * `metadata` freely; other unknown top-level fields are removed, because the
+   * server rejects them.
+   */
+  beforeSend?: (event: BrowserEvent) => BrowserEvent | null | undefined;
+
+  /** Log the SDK's own diagnostics to the console. */
+  debug?: boolean;
+  /** How often queued events are sent, in ms. Default 5000. */
+  flushIntervalMs?: number;
+  /** Events per request. Default 20. */
+  maxBatchSize?: number;
+  /** Events held while Midline is unreachable; oldest dropped past this. Default 200. */
+  maxQueueSize?: number;
+}
+
+/** An event as it is sent to the ingest API. */
+export interface BrowserEvent {
+  eventType: "error" | "request" | "console" | "performance" | "custom";
+  route: string;
+  method?: string;
+  statusCode?: number;
+  responseTime?: number;
+  severity: EventSeverity;
+  category?: EventCategory;
+  timestamp: string;
+  service?: string;
+  environment?: string;
+  release?: string;
+  userAgent?: string;
+  traceId?: string;
+  spanId?: string;
+  payload?: Record<string, unknown>;
+  metadata: Record<string, unknown>;
+}
+
+export interface CaptureContext {
+  tags?: Record<string, string>;
+  extra?: Record<string, unknown>;
+}

package/src/browser/version.ts

@@ -0,0 +1,2 @@
+/** Kept in step with package.json by test/browser.test.js; a browser bundle can't read package.json. */
+export const BROWSER_SDK_VERSION = "0.4.0";