midline-agent 0.3.0 → 0.4.1

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

@@ -4,7 +4,6 @@ import * as tls from "tls";
 import { CaInput, CaptureOptions, MidlineConfig } from "./types";
 
 export const DEFAULT_ENDPOINT = "https://api.usemidline.com";
-export const INGEST_PATH = "/api/api-monitor/events";
 
 /** A setting that cannot work as given. Thrown at construction, never while serving traffic. */
 export class ConfigError extends Error {
@@ -25,8 +24,8 @@ export interface ResolvedCapture {
 export interface ResolvedConfig {
   apiKey: string;
   serviceName?: string;
-  ingestUrl: URL;
-  batchUrl: URL;
+  /** The Midline server's origin; the ingest gateway lives at `${socketOrigin}/ingest`. */
+  socketOrigin: URL;
   /** Full trust store for the Midline endpoint, or undefined for Node's default. */
   ca?: Array<string | Buffer>;
   hasCustomCa: boolean;
@@ -83,12 +82,14 @@ export function isLoopback(hostname: string): boolean {
 }
 
 /**
- * Turns whatever the user configured into the ingest URL.
- *
+ * Turns whatever the user configured into the Midline server's origin — the
+ * agent connects to `${origin}/ingest` over socket.io, so only the origin
+ * matters now. Tolerates an old-style full ingest URL some existing
+ * `MIDLINE_ENDPOINT` values still carry (from before the socket.io transport):
  * `https://api.usemidline.com`, `https://api.usemidline.com/api/api-monitor/events`
- * and `https://gateway.internal/midline` all work; the last is treated as a prefix.
+ * and `https://gateway.internal/midline` all resolve to the same origin.
  */
-export function resolveIngestUrl(endpoint: string): URL {
+export function resolveEndpointOrigin(endpoint: string): URL {
   let url: URL;
   try {
     url = new URL(endpoint);
@@ -109,18 +110,7 @@ export function resolveIngestUrl(endpoint: string): URL {
     throw new ConfigError("endpoint must not contain credentials; pass the key as apiKey");
   }
 
-  url.search = "";
-  url.hash = "";
-
-  const path = url.pathname.replace(/\/+$/, "");
-  if (path.endsWith(`${INGEST_PATH}/batch`)) {
-    url.pathname = path.slice(0, -"/batch".length);
-  } else if (path.endsWith(INGEST_PATH)) {
-    url.pathname = path;
-  } else {
-    url.pathname = `${path}${INGEST_PATH}`;
-  }
-  return url;
+  return new URL(url.origin);
 }
 
 /**
@@ -198,18 +188,17 @@ export function resolveCapture(capture: CaptureOptions | undefined): ResolvedCap
 
 export function resolveConfig(config: MidlineConfig): ResolvedConfig {
   const apiKey = (config.apiKey ?? env("MIDLINE_API_KEY") ?? "").trim();
-  const ingestUrl = resolveIngestUrl(config.endpoint || env("MIDLINE_ENDPOINT") || DEFAULT_ENDPOINT);
+  const socketOrigin = resolveEndpointOrigin(config.endpoint || env("MIDLINE_ENDPOINT") || DEFAULT_ENDPOINT);
   const extraCa = loadCa(config.ca ?? env("MIDLINE_CUSTOM_CA"), "ca / MIDLINE_CUSTOM_CA");
 
-  if (extraCa && ingestUrl.protocol !== "https:") {
+  if (extraCa && socketOrigin.protocol !== "https:") {
     throw new ConfigError("ca / MIDLINE_CUSTOM_CA is set but the endpoint is not https://");
   }
 
   return {
     apiKey,
     serviceName: config.serviceName ?? env("MIDLINE_SERVICE_NAME"),
-    ingestUrl,
-    batchUrl: new URL(`${ingestUrl.pathname}/batch`, ingestUrl),
+    socketOrigin,
     ca: trustStore(extraCa),
     hasCustomCa: Boolean(extraCa),
     environment: config.environment ?? env("MIDLINE_ENVIRONMENT"),

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/socket-transport.ts

@@ -0,0 +1,188 @@
+import { io, Socket } from "socket.io-client";
+
+/** Mirrors midline-core-api/src/realtime/ingest-protocol.ts's IngestAck. Duplicated,
+ * not shared: the two are separate packages, kept in sync by wire convention. */
+export type IngestAckErrorCode = "unauthorized" | "forbidden" | "rate_limited" | "bad_request" | "too_large" | "internal_error";
+export interface IngestAckOk {
+  ok: true;
+  accepted: number;
+  rejected: number;
+}
+export interface IngestAckError {
+  ok: false;
+  code: IngestAckErrorCode;
+  message: string;
+  retryAfterMs?: number;
+}
+export type IngestAck = IngestAckOk | IngestAckError;
+
+const INGEST_NAMESPACE = "/ingest";
+const INGEST_EVENT = "ingest";
+
+export interface SocketTransportOptions {
+  apiKey: string;
+  /** Full trust store for the Midline endpoint, or undefined for Node's default. */
+  ca?: Array<string | Buffer>;
+  connectTimeoutMs: number;
+  /** Per-emit ack timeout. */
+  timeoutMs: number;
+  /** Reconnection backoff bounds, derived from the agent's own flush/backoff config (see agent.ts). */
+  reconnectionDelayMs: number;
+  reconnectionDelayMaxMs: number;
+  /** Nothing queued for this long -> disconnect; reconnects lazily on the next send(). */
+  idleDisconnectMs: number;
+  userAgent: string;
+}
+
+/** A transport failure with a stable `code`, matching what agent.ts's errorCode()/describe() expect. */
+export class TransportError extends Error {
+  constructor(message: string, readonly code: string) {
+    super(message);
+    this.name = "TransportError";
+  }
+}
+
+/**
+ * Owns one socket.io-client connection to the ingest gateway: connects lazily on
+ * first send, lets socket.io-client's own reconnection/backoff handle transport
+ * drops, and disconnects after a sustained idle period (autoUnref also unrefs the
+ * underlying socket, so — as with the old HTTP transport — telemetry alone never
+ * keeps the process alive; the idle disconnect is extra hygiene on top of that,
+ * not the only thing standing between this and a hung process).
+ */
+export class SocketTransport {
+  private socket: Socket | null = null;
+  private connecting: Promise<void> | null = null;
+  private idleTimer: NodeJS.Timeout | null = null;
+
+  constructor(private readonly origin: URL, private readonly options: SocketTransportOptions) {}
+
+  /** Sends one batch, connecting first if needed. Resolves with the server's ack or throws. */
+  async send(events: Array<Record<string, unknown>>): Promise<IngestAck> {
+    this.clearIdleTimer();
+    try {
+      await this.ensureConnected();
+      return await this.emit(events);
+    } finally {
+      this.scheduleIdleDisconnect();
+    }
+  }
+
+  destroy(): void {
+    this.clearIdleTimer();
+    this.socket?.removeAllListeners();
+    this.socket?.disconnect();
+    this.socket = null;
+  }
+
+  private ensureConnected(): Promise<void> {
+    if (this.socket?.connected) return Promise.resolve();
+    if (this.connecting) return this.connecting;
+
+    if (!this.socket) {
+      this.socket = this.createSocket();
+    } else if (!this.socket.active) {
+      // Cleanly disconnected earlier (our own idle timeout, or the server closed
+      // it): socket.io-client won't retry on its own, so ask it to.
+      this.socket.connect();
+    }
+    // Otherwise the existing socket is already reconnecting on its own; just wait below.
+
+    const socket = this.socket;
+    this.connecting = new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new TransportError(`connection not established within ${this.options.connectTimeoutMs}ms`, "ECONNECT_TIMEOUT"));
+      }, this.options.connectTimeoutMs);
+      const onConnect = () => {
+        cleanup();
+        resolve();
+      };
+      const onError = (err: unknown) => {
+        cleanup();
+        reject(classifyConnectError(err));
+      };
+      const cleanup = () => {
+        clearTimeout(timer);
+        socket.off("connect", onConnect);
+        socket.off("connect_error", onError);
+      };
+      socket.once("connect", onConnect);
+      socket.once("connect_error", onError);
+    }).finally(() => {
+      this.connecting = null;
+    });
+    return this.connecting;
+  }
+
+  private createSocket(): Socket {
+    const socket = io(`${this.origin.origin}${INGEST_NAMESPACE}`, {
+      auth: { apiKey: this.options.apiKey },
+      transports: ["websocket"],
+      reconnection: true,
+      reconnectionAttempts: Infinity,
+      reconnectionDelay: this.options.reconnectionDelayMs,
+      reconnectionDelayMax: this.options.reconnectionDelayMaxMs,
+      randomizationFactor: 0.5,
+      timeout: this.options.connectTimeoutMs,
+      // Never the reason the process stays alive — same property the old HTTP
+      // transport's unref'd keep-alive sockets had.
+      autoUnref: true,
+      forceNew: true,
+      ca: this.options.ca,
+      extraHeaders: { "user-agent": this.options.userAgent },
+    } as Record<string, unknown>);
+    return socket;
+  }
+
+  private emit(events: Array<Record<string, unknown>>): Promise<IngestAck> {
+    const socket = this.socket;
+    if (!socket) {
+      return Promise.reject(new TransportError("not connected", "ENOTCONNECTED"));
+    }
+    return new Promise<IngestAck>((resolve, reject) => {
+      socket.timeout(this.options.timeoutMs).emit(INGEST_EVENT, { events }, (err: Error | null, ack: IngestAck) => {
+        if (err) {
+          reject(new TransportError(`no response within ${this.options.timeoutMs}ms`, "ETIMEDOUT"));
+        } else {
+          resolve(ack);
+        }
+      });
+    });
+  }
+
+  private scheduleIdleDisconnect(): void {
+    this.idleTimer = setTimeout(() => {
+      this.idleTimer = null;
+      this.socket?.disconnect();
+    }, this.options.idleDisconnectMs);
+    this.idleTimer.unref?.();
+  }
+
+  private clearIdleTimer(): void {
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+  }
+}
+
+/**
+ * `connect_error` from a plain `io()` connect-timeout has message "timeout" and
+ * no further detail. Anything else wraps the real Node error (ECONNREFUSED,
+ * ENOTFOUND, a TLS failure, ...) inside engine.io-client's TransportError, whose
+ * `.description` — for the websocket transport — is a `ws` ErrorEvent exposing
+ * the underlying error via its public `.error` getter (mirrors the DOM
+ * ErrorEvent.error field; see ws/lib/event-target.js). Verified empirically
+ * against the installed socket.io-client/ws versions, not assumed.
+ */
+function classifyConnectError(err: unknown): TransportError {
+  const anyErr = err as { message?: string; description?: { error?: { code?: string; message?: string } } };
+  if (anyErr?.message === "timeout") {
+    return new TransportError("connection timed out", "ECONNECT_TIMEOUT");
+  }
+  const inner = anyErr?.description?.error;
+  const code = inner?.code ?? "";
+  const message = inner?.message ?? anyErr?.message ?? "connection failed";
+  return new TransportError(message, code);
+}