midline-agent 0.2.0 → 0.4.0

package/src/browser/vitals.ts

@@ -0,0 +1,149 @@
+export type VitalName = "LCP" | "INP" | "CLS" | "FCP" | "TTFB";
+export type VitalRating = "good" | "needs-improvement" | "poor";
+
+export interface VitalsReport {
+  vitals: Partial<Record<VitalName, { value: number; rating: VitalRating }>>;
+  navigationType?: string;
+}
+
+/** web.dev thresholds: at or under the first is good, over the second is poor. */
+const THRESHOLDS: Record<VitalName, [number, number]> = {
+  LCP: [2500, 4000],
+  INP: [200, 500],
+  CLS: [0.1, 0.25],
+  FCP: [1800, 3000],
+  TTFB: [800, 1800],
+};
+
+const rate = (name: VitalName, value: number): VitalRating =>
+  value <= THRESHOLDS[name][0] ? "good" : value <= THRESHOLDS[name][1] ? "needs-improvement" : "poor";
+
+type Entry = PerformanceEntry & {
+  value?: number;
+  hadRecentInput?: boolean;
+  interactionId?: number;
+  activationStart?: number;
+  responseStart?: number;
+  type?: string;
+};
+
+/**
+ * Core Web Vitals without a dependency, measured the way the web-vitals library
+ * does and reported once, when the page is first hidden (the last moment a
+ * report reliably gets out). Browsers that don't expose an entry type simply
+ * omit that metric: Safari has no LCP, INP or CLS.
+ */
+export function observeVitals(win: Window, onReport: (report: VitalsReport) => void): () => void {
+  const Observer = (win as Window & { PerformanceObserver?: typeof PerformanceObserver }).PerformanceObserver;
+  const supported: readonly string[] = Observer?.supportedEntryTypes ?? [];
+  const perf = win.performance;
+  const doc = win.document;
+
+  const values: Partial<Record<VitalName, number>> = {};
+  const observers: Array<{ observer: PerformanceObserver; handle: (entries: Entry[]) => void }> = [];
+
+  let activationStart = 0;
+  let navigationType: string | undefined;
+  try {
+    const navigation = perf?.getEntriesByType?.("navigation")?.[0] as Entry | undefined;
+    if (navigation) {
+      activationStart = navigation.activationStart ?? 0;
+      navigationType = navigation.type;
+      if (typeof navigation.responseStart === "number" && navigation.responseStart > 0) {
+        values.TTFB = Math.max(0, navigation.responseStart - activationStart);
+      }
+    }
+  } catch {
+    // no navigation timing
+  }
+
+  const observe = (type: string, handle: (entries: Entry[]) => void, extra: Record<string, unknown> = {}) => {
+    if (!Observer || !supported.includes(type)) return;
+    try {
+      const observer = new Observer((list) => handle(list.getEntries() as Entry[]));
+      observer.observe({ type, buffered: true, ...extra } as PerformanceObserverInit);
+      observers.push({ observer, handle });
+    } catch {
+      // unsupported option in this browser
+    }
+  };
+
+  observe("paint", (entries) => {
+    for (const entry of entries) {
+      if (entry.name === "first-contentful-paint") values.FCP = Math.max(0, entry.startTime - activationStart);
+    }
+  });
+
+  observe("largest-contentful-paint", (entries) => {
+    const last = entries[entries.length - 1];
+    if (last) values.LCP = Math.max(0, last.startTime - activationStart);
+  });
+
+  // CLS is the largest session window: shifts less than 1s apart, at most 5s long.
+  let windowValue = 0;
+  let windowStart = 0;
+  let windowLast = 0;
+  observe("layout-shift", (entries) => {
+    for (const entry of entries) {
+      if (entry.hadRecentInput || typeof entry.value !== "number") continue;
+      if (windowValue && entry.startTime - windowLast < 1000 && entry.startTime - windowStart < 5000) {
+        windowValue += entry.value;
+      } else {
+        windowValue = entry.value;
+        windowStart = entry.startTime;
+      }
+      windowLast = entry.startTime;
+      values.CLS = Math.max(values.CLS ?? 0, windowValue);
+    }
+  });
+
+  // INP: the slowest interaction, or near the 98th percentile on busy pages.
+  const interactions = new Map<number, number>();
+  const recordInteractions = (entries: Entry[]) => {
+    for (const entry of entries) {
+      if (!entry.interactionId) continue;
+      interactions.set(entry.interactionId, Math.max(interactions.get(entry.interactionId) ?? 0, entry.duration));
+    }
+  };
+  observe("event", recordInteractions, { durationThreshold: 40 });
+  observe("first-input", recordInteractions);
+
+  let reported = false;
+  const report = () => {
+    if (reported) return;
+    reported = true;
+    for (const { observer, handle } of observers) {
+      try {
+        handle(observer.takeRecords() as Entry[]);
+        observer.disconnect();
+      } catch {
+        // already disconnected
+      }
+    }
+    if (interactions.size) {
+      const durations = [...interactions.values()].sort((a, b) => b - a);
+      values.INP = durations[Math.min(durations.length - 1, Math.floor(durations.length / 50))];
+    }
+
+    const vitals: VitalsReport["vitals"] = {};
+    for (const name of Object.keys(values) as VitalName[]) {
+      const raw = values[name];
+      if (typeof raw !== "number" || !Number.isFinite(raw)) continue;
+      const value = name === "CLS" ? Math.round(raw * 10_000) / 10_000 : Math.round(raw);
+      vitals[name] = { value, rating: rate(name, value) };
+    }
+    if (Object.keys(vitals).length) onReport({ vitals, navigationType });
+  };
+
+  const onVisibility = () => {
+    if (doc?.visibilityState === "hidden") report();
+  };
+  doc?.addEventListener("visibilitychange", onVisibility, true);
+  win.addEventListener("pagehide", report, true);
+
+  return () => {
+    doc?.removeEventListener("visibilitychange", onVisibility, true);
+    win.removeEventListener("pagehide", report, true);
+    for (const { observer } of observers) observer.disconnect();
+  };
+}

package/src/config.ts

@@ -37,6 +37,7 @@ export interface ResolvedConfig {
   redactFields: string[];
   redactHeaders: string[];
   capture: ResolvedCapture;
+  captureConsole: boolean;
   onError?: (message: string) => void;
   debug: boolean;
   flushIntervalMs: number;
@@ -218,6 +219,7 @@ export function resolveConfig(config: MidlineConfig): ResolvedConfig {
     redactFields: [...(config.redactFields ?? []), ...(config.maskFields ?? [])],
     redactHeaders: config.redactHeaders ?? [],
     capture: resolveCapture(config.capture),
+    captureConsole: config.captureConsole ?? envFlag("MIDLINE_CAPTURE_CONSOLE") ?? false,
     onError: config.onError,
     debug: config.debug ?? envFlag("MIDLINE_DEBUG") ?? false,
     flushIntervalMs: positiveInt(config.flushIntervalMs, 1500, 50, 60_000),

package/src/console.ts

@@ -0,0 +1,182 @@
+/**
+ * Console capture: what the host process prints — `console.log`, Nest's logger,
+ * pino, anything that reaches stdout or stderr — copied into Midline line by line.
+ *
+ * The streams are never changed. The original `write` runs first with the
+ * caller's own arguments and its return value is handed straight back, so
+ * back-pressure, callbacks and the terminal output are exactly what they were.
+ */
+
+export type ConsoleStream = "stdout" | "stderr";
+export type ConsoleLevel = "info" | "warn" | "error";
+
+export interface ConsoleLine {
+  stream: ConsoleStream;
+  text: string;
+  level: ConsoleLevel;
+  /** When the line's first chunk was written, not when it was sent. */
+  timestamp: string;
+}
+
+/** Longest line kept. A log line past this is almost always a dumped payload. */
+export const MAX_LINE_CHARS = 4096;
+
+const STREAMS: ConsoleStream[] = ["stdout", "stderr"];
+
+/** CSI (colours, cursor moves), OSC (titles, hyperlinks) and the remaining two-byte escapes. */
+const ANSI_ESCAPE = /\x1B\[[0-?]*[ -\/]*[@-~]|\x1B\][^\x07\x1B]*(?:\x07|\x1B\\)|\x1B[@-Z\\-_]/g;
+
+// Level words are matched in capitals only: lower-case "error" turns up in plenty of harmless lines.
+const ERROR_MARKERS = [/\b(?:ERROR|FATAL|CRITICAL)\b/, /"level"\s*:\s*"?(?:error|fatal|critical|50|60)\b/i];
+const WARN_MARKERS = [/\bWARN(?:ING)?\b/, /"level"\s*:\s*"?(?:warn|warning|40)\b/i];
+
+type WriteFn = (...args: any[]) => boolean;
+
+let suppressed = 0;
+
+/**
+ * Runs `fn` with capture paused. The agent writes its own diagnostics through
+ * this, so a warning about delivery can't become an event that needs delivering.
+ */
+export function withoutConsoleCapture<T>(fn: () => T): T {
+  suppressed += 1;
+  try {
+    return fn();
+  } finally {
+    suppressed -= 1;
+  }
+}
+
+interface Pending {
+  text: string;
+  at: string;
+  /** Already unfinished at the previous flush. */
+  stale: boolean;
+}
+
+export class ConsoleCapture {
+  private readonly originals = new Map<ConsoleStream, WriteFn>();
+  private readonly wrappers = new Map<ConsoleStream, WriteFn>();
+  private readonly pending: Record<ConsoleStream, Pending> = {
+    stdout: { text: "", at: "", stale: false },
+    stderr: { text: "", at: "", stale: false },
+  };
+  private busy = false;
+  private stopped = false;
+
+  constructor(private readonly onLine: (line: ConsoleLine) => void) {}
+
+  install(): void {
+    for (const stream of STREAMS) {
+      const target = process[stream];
+      const original = target.write as WriteFn;
+      const capture = this;
+      const wrapper: WriteFn = function (this: unknown, ...args: any[]) {
+        const result = original.apply(this, args);
+        capture.take(stream, args[0], args[1]);
+        return result;
+      };
+      this.originals.set(stream, original);
+      this.wrappers.set(stream, wrapper);
+      target.write = wrapper as NodeJS.WriteStream["write"];
+    }
+  }
+
+  /** Restores the streams. A wrapper installed on top of ours is left alone — ours just goes quiet underneath it. */
+  uninstall(): void {
+    this.stopped = true;
+    for (const stream of STREAMS) {
+      const wrapper = this.wrappers.get(stream);
+      if (wrapper && process[stream].write === wrapper) {
+        process[stream].write = this.originals.get(stream) as NodeJS.WriteStream["write"];
+      }
+    }
+    this.wrappers.clear();
+    this.originals.clear();
+  }
+
+  /**
+   * Emits lines still waiting for a newline. Without `force`, only the ones that
+   * were already unfinished at the previous call, so a line being written in
+   * pieces isn't cut in half by a timer tick.
+   */
+  flushPending(force = false): void {
+    if (this.stopped || this.busy) return;
+    this.busy = true;
+    try {
+      for (const stream of STREAMS) {
+        const pending = this.pending[stream];
+        if (!pending.text) continue;
+        if (force || pending.stale) {
+          this.pending[stream] = { text: "", at: "", stale: false };
+          this.emit(stream, pending.text, pending.at);
+        } else {
+          pending.stale = true;
+        }
+      }
+    } catch {
+      // Best-effort, like the rest of capture.
+    } finally {
+      this.busy = false;
+    }
+  }
+
+  private take(stream: ConsoleStream, chunk: unknown, encoding: unknown): void {
+    // `busy` also stops a loop if whatever handles a line prints something itself.
+    if (this.stopped || this.busy || suppressed > 0) return;
+    this.busy = true;
+    try {
+      const text = decode(chunk, encoding);
+      if (!text) return;
+
+      const now = new Date().toISOString();
+      const pending = this.pending[stream];
+      const lines = (pending.text + text).split("\n");
+      let rest = lines.pop() ?? "";
+      let at = pending.text ? pending.at : now;
+
+      for (const line of lines) {
+        this.emit(stream, line, at);
+        at = now;
+      }
+      if (rest.length > MAX_LINE_CHARS) {
+        this.emit(stream, rest, at);
+        rest = "";
+      }
+      this.pending[stream] = { text: rest, at: rest ? at : "", stale: false };
+    } catch {
+      // The write itself already happened; a line we couldn't read is just not sent.
+    } finally {
+      this.busy = false;
+    }
+  }
+
+  private emit(stream: ConsoleStream, raw: string, at: string): void {
+    let text = raw.replace(ANSI_ESCAPE, "").replace(/\r$/, "");
+    // A carriage return redraws the line; what's left after the last one is what the terminal shows.
+    text = text.slice(text.lastIndexOf("\r") + 1);
+    if (!text.trim()) return;
+    if (text.length > MAX_LINE_CHARS) text = text.slice(0, MAX_LINE_CHARS);
+    this.onLine({ stream, text, level: levelOf(stream, text), timestamp: at });
+  }
+}
+
+/** Nest, most JSON loggers and console.warn/error leave enough behind to tell a failure from chatter. */
+export function levelOf(stream: ConsoleStream, text: string): ConsoleLevel {
+  const head = text.slice(0, 256);
+  if (ERROR_MARKERS.some((pattern) => pattern.test(head))) return "error";
+  if (WARN_MARKERS.some((pattern) => pattern.test(head))) return "warn";
+  return stream === "stderr" ? "warn" : "info";
+}
+
+function decode(chunk: unknown, encoding: unknown): string {
+  if (typeof chunk === "string") {
+    return typeof encoding === "string" && !/^utf-?8$/i.test(encoding) && Buffer.isEncoding(encoding)
+      ? Buffer.from(chunk, encoding).toString("utf8")
+      : chunk;
+  }
+  if (chunk instanceof Uint8Array) {
+    return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength).toString("utf8");
+  }
+  return "";
+}

package/src/redact.ts

@@ -1,4 +1,7 @@
 /**
+ * Shared by the Node agent and the browser SDK, so nothing here may touch a
+ * Node-only global (Buffer, process) — TextEncoder and URLSearchParams exist in both.
+ *
  * Redaction happens in the host process, before an event is queued. Whatever is
  * removed here never reaches a socket, a log line or the Midline server.
  *
@@ -124,7 +127,8 @@ export class Redactor {
     if (typeof input === "bigint") return input.toString();
     if (typeof input === "function" || typeof input === "symbol") return undefined;
     if (input instanceof Date) return Number.isNaN(input.getTime()) ? null : input.toISOString();
-    if (Buffer.isBuffer(input) || ArrayBuffer.isView(input)) {
+    // Buffer is a Uint8Array, so this also covers it without naming a Node-only global.
+    if (ArrayBuffer.isView(input)) {
       return `[Binary ${(input as ArrayBufferView).byteLength} bytes]`;
     }
     if (typeof input !== "object") return undefined;
@@ -190,11 +194,13 @@ export class Redactor {
 
     const type = (contentType || "").toLowerCase();
 
-    if (typeof raw === "object" && !Buffer.isBuffer(raw)) {
+    if (typeof raw === "object" && !ArrayBuffer.isView(raw)) {
       return this.fit(this.value(raw), maxBytes);
     }
 
-    const text = Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw);
+    const text = ArrayBuffer.isView(raw)
+      ? new TextDecoder().decode(raw as ArrayBufferView)
+      : String(raw);
 
     if (type.includes("json")) {
       try {
@@ -214,18 +220,18 @@ export class Redactor {
 
   private fit(value: unknown, maxBytes: number): { body?: unknown; truncated?: boolean } {
     const serialized = JSON.stringify(value) ?? "";
-    if (Buffer.byteLength(serialized) <= maxBytes) {
+    if (new TextEncoder().encode(serialized).length <= maxBytes) {
       return { body: value };
     }
     return this.cut(serialized, maxBytes);
   }
 
   private cut(text: string, maxBytes: number): { body?: unknown; truncated?: boolean } {
-    const bytes = Buffer.from(text);
+    const bytes = new TextEncoder().encode(text);
     if (bytes.length <= maxBytes) {
       return { body: text };
     }
     // Slicing bytes can split a multi-byte character; the replacement char is harmless here.
-    return { body: bytes.subarray(0, maxBytes).toString("utf8"), truncated: true };
+    return { body: new TextDecoder().decode(bytes.subarray(0, maxBytes)), truncated: true };
   }
 }

package/src/types.ts

@@ -1,7 +1,7 @@
 /** A PEM string, PEM bytes, a path to a PEM file, or several of those. */
 export type CaInput = string | Buffer | Array<string | Buffer>;
 
-export type EventType = "request" | "error" | "security" | "performance" | "custom";
+export type EventType = "request" | "error" | "security" | "performance" | "custom" | "console";
 export type EventSeverity = "low" | "medium" | "high" | "critical";
 export type EventCategory = "application" | "infrastructure" | "security" | "performance" | "business";
 
@@ -62,6 +62,13 @@ export interface MidlineConfig {
   redactHeaders?: string[];
   /** What to capture beyond method/path/status/timing. Defaults to nothing. */
   capture?: CaptureOptions;
+  /**
+   * Also send what the process prints — `console.log`, Nest's logger, anything
+   * written to stdout or stderr — as `console` events, one per line, redacted like
+   * any other text. Initialise the agent before creating the app to include its
+   * startup lines. Off by default. Env fallback: `MIDLINE_CAPTURE_CONSOLE`.
+   */
+  captureConsole?: boolean;
 
   /** Set to false to keep the agent inert. Env fallback: `MIDLINE_ENABLED`. */
   enabled?: boolean;
@@ -141,5 +148,5 @@ export interface MidlineEvent {
   errorCode?: string;
   /** Set when the client disconnected before the response finished. */
   aborted?: boolean;
-  integration?: "express" | "node-http" | "proxy" | "manual";
+  integration?: "express" | "node-http" | "proxy" | "console" | "manual";
 }