midline-agent 0.1.8 → 0.2.0

package/src/agent.ts

@@ -1,125 +1,757 @@
-import fetch from "cross-fetch";
-import { MidlineConfig, MidlineEvent } from "./types";
+import { ConfigError, ResolvedCapture, ResolvedConfig, envFlag, resolveConfig } from "./config";
+import type { RequestContext } from "./context";
+import { Redactor } from "./redact";
+import { Transport } from "./transport";
+import { CapturedMessage, EventCategory, EventSeverity, MidlineConfig, MidlineEvent } from "./types";
 
+export const SDK_VERSION: string = (() => {
+  try {
+    return require("../package.json").version;
+  } catch {
+    return "unknown";
+  }
+})();
+
+const MAX_REQUEST_BYTES = 512 * 1024;
+const MIN_REQUEST_BYTES = 16 * 1024;
+const MAX_QUEUE_BYTES = 16 * 1024 * 1024;
+
+/** Verification failures. Retrying is still right: they clear once the server is fixed. */
+const TLS_ERROR_REASONS: Record<string, string> = {
+  DEPTH_ZERO_SELF_SIGNED_CERT: "presented a self-signed certificate",
+  SELF_SIGNED_CERT_IN_CHAIN: "presented a chain that ends in an untrusted self-signed CA",
+  UNABLE_TO_VERIFY_LEAF_SIGNATURE: "presented a certificate whose issuer could not be verified (missing intermediate, or a private CA)",
+  UNABLE_TO_GET_ISSUER_CERT: "presented a certificate whose issuer could not be found",
+  UNABLE_TO_GET_ISSUER_CERT_LOCALLY: "presented a certificate whose issuer is not in the trust store (missing intermediate, or a private CA)",
+  CERT_HAS_EXPIRED: "presented an expired certificate",
+  CERT_NOT_YET_VALID: "presented a certificate that is not valid yet (check this machine's clock)",
+  CERT_REVOKED: "presented a revoked certificate",
+  CERT_UNTRUSTED: "presented an untrusted certificate",
+  CERT_REJECTED: "presented a rejected certificate",
+  ERR_TLS_CERT_ALTNAME_INVALID: "presented a certificate issued for a different hostname",
+  HOSTNAME_MISMATCH: "presented a certificate issued for a different hostname",
+};
+
+interface QueuedEvent {
+  wire: Record<string, unknown>;
+  bytes: number;
+}
+
+type Outcome =
+  | { kind: "ok" }
+  | { kind: "retry"; retryAfterMs?: number }
+  | { kind: "stop" }
+  | { kind: "tooLarge" }
+  | { kind: "rejected"; detail: string };
+
+/** Raw material for a request event, handed over by the middleware or the proxy. */
+export interface HttpExchange {
+  integration: NonNullable<MidlineEvent["integration"]>;
+  context: RequestContext;
+  method?: string;
+  /** Path plus query string, as received. */
+  url: string;
+  statusCode?: number;
+  durationMs: number;
+  ip?: string;
+  userAgent?: string;
+  routeTemplate?: string;
+  request?: ExchangeMessage;
+  response?: ExchangeMessage;
+  destination?: { url: string };
+  errorCode?: string;
+  errorMessage?: string;
+  aborted?: boolean;
+  capture?: ResolvedCapture;
+}
+
+export interface ExchangeMessage {
+  headers?: Record<string, unknown>;
+  contentType?: string;
+  /** Only present when body capture is on. Parsed object or raw bytes. */
+  body?: unknown;
+  bodyBytes?: number;
+  /** The tap stopped reading before the end of the body. */
+  truncated?: boolean;
+}
+
+/**
+ * Ships request/error events to the Midline server.
+ *
+ * The contract with the host application is that the agent is never allowed to
+ * affect it: an unreachable, untrusted, slow or misconfigured Midline server costs a
+ * single explanatory log line and bounded buffered memory — never a crash, never a
+ * stalled request, never a disabled certificate check.
+ */
 export class MidlineAgent {
-  private static config: MidlineConfig;
-  private static queue: MidlineEvent[] = [];
-  private static timer: NodeJS.Timeout;
-
-  static init(config: MidlineConfig) {
-    this.config = {
-      endpoint: "https://api.usemidline.com/api/api-monitor/events",
-      ...config,
-      // Deliberately after the spread. `password` and `token` are always
-      // masked; a caller-supplied list extends that set rather than replacing
-      // it, which is what happened while this sat above `...config`.
-      maskFields: [...new Set(["password", "token", ...(config.maskFields || [])])],
-    };
+  private static defaultAgent: MidlineAgent | null = null;
+
+  /** Creates the process-wide agent used by `midlineMiddleware()` and the static helpers. */
+  static init(config: MidlineConfig = {}): MidlineAgent {
+    MidlineAgent.defaultAgent?.close();
+    MidlineAgent.defaultAgent = new MidlineAgent(config);
+    return MidlineAgent.defaultAgent;
+  }
+
+  static get current(): MidlineAgent | null {
+    return MidlineAgent.defaultAgent;
+  }
 
-    this.startQueue();
+  static addEvent(event: MidlineEvent): void {
+    MidlineAgent.defaultAgent?.addEvent(event);
   }
 
-  static addEvent(event: MidlineEvent) {
-    if (!this.config) {
+  static flush(): Promise<void> {
+    return MidlineAgent.defaultAgent?.flush() ?? Promise.resolve();
+  }
+
+  static shutdown(timeoutMs?: number): Promise<void> {
+    return MidlineAgent.defaultAgent?.shutdown(timeoutMs) ?? Promise.resolve();
+  }
+
+  private readonly config: ResolvedConfig | null = null;
+  private readonly redactor: Redactor;
+  private readonly transport: Transport | null = null;
+  private readonly onErrorHook?: (message: string) => void;
+  private readonly debugLogs: boolean;
+
+  private queue: QueuedEvent[] = [];
+  private queueBytes = 0;
+  private timer: NodeJS.Timeout | null = null;
+  private drainPromise: Promise<void> | null = null;
+  private failures = 0;
+  private retryAfter = 0;
+  private stopped = false;
+  private lastNotice = "";
+  private dropped = 0;
+  private maxRequestBytes = MAX_REQUEST_BYTES;
+  private batchLimit = Number.MAX_SAFE_INTEGER;
+
+  constructor(config: MidlineConfig = {}) {
+    this.onErrorHook = config.onError;
+    this.debugLogs = config.debug ?? envFlag("MIDLINE_DEBUG") ?? false;
+    this.redactor = new Redactor([...(config.redactFields ?? []), ...(config.maskFields ?? [])], config.redactHeaders);
+
+    if ((config.enabled ?? envFlag("MIDLINE_ENABLED")) === false) {
+      this.stopped = true;
       return;
     }
-    this.queue.push(event);
-  }
-
-  private static transformEvent(event: MidlineEvent): any {
-    const isError = event.type === "error";
-
-    // Build the payload structure matching the expected API format
-    const transformed: any = {
-      apiKey: this.config.apiKey,
-      eventType: event.type,
-      route: event.path,
-      method: event.method || "GET",
-      statusCode: event.statusCode || (isError ? 500 : 200),
-      responseTime: event.duration || 0,
-      timestamp: event.timestamp,
-      ip: event.ip,
-      userAgent: event.userAgent,
-      service: this.config.serviceName,
-      metadata: {
-        source: "sdk",
-        version: "0.1.3",
-        integrationType: "express"
-      }
+
+    let resolved: ResolvedConfig;
+    try {
+      resolved = resolveConfig(config);
+    } catch (err) {
+      this.stopped = true;
+      const detail = err instanceof ConfigError ? err.message : String((err as Error)?.message ?? err);
+      this.log("error", `midline: ${detail} — monitoring is off.`);
+      return;
+    }
+
+    if (!resolved.apiKey) {
+      this.stopped = true;
+      this.log("warn", "midline: no apiKey (or MIDLINE_API_KEY) — monitoring is off.");
+      return;
+    }
+
+    this.config = resolved;
+    this.transport = new Transport(resolved.ingestUrl, {
+      ca: resolved.ca,
+      connectTimeoutMs: resolved.connectTimeoutMs,
+      timeoutMs: resolved.timeoutMs,
+      userAgent: `midline-agent/${SDK_VERSION} node/${process.version}`,
+    });
+
+    this.timer = setInterval(() => {
+      void this.drain(false);
+    }, resolved.flushIntervalMs);
+    // Telemetry must never be the reason a process refuses to exit.
+    this.timer.unref?.();
+  }
+
+  /** False when the agent is off: no key, bad config, disabled, rejected key, or closed. */
+  get active(): boolean {
+    return !this.stopped && this.config !== null;
+  }
+
+  get capture(): ResolvedCapture | null {
+    return this.config?.capture ?? null;
+  }
+
+  get queued(): number {
+    return this.queue.length;
+  }
+
+  addEvent(event: MidlineEvent): void {
+    if (!this.active) return;
+    try {
+      this.enqueue(this.toWire(event, false));
+    } catch (err) {
+      this.report("event-build", `midline: could not build an event (${(err as Error)?.message}); skipped it.`);
+    }
+  }
+
+  /** Records one HTTP exchange. Captured parts are redacted here, before queueing. */
+  recordHttp(exchange: HttpExchange): void {
+    if (!this.active) return;
+    try {
+      const capture = exchange.capture ?? this.config!.capture;
+      const queryIndex = exchange.url.indexOf("?");
+      const path = queryIndex === -1 ? exchange.url : exchange.url.slice(0, queryIndex);
+      const search = queryIndex === -1 ? "" : exchange.url.slice(queryIndex + 1);
+      const failed = Boolean(exchange.errorCode);
+
+      const event: MidlineEvent = {
+        type: failed ? "error" : "request",
+        path: path || "/",
+        method: exchange.method,
+        statusCode: exchange.statusCode,
+        duration: exchange.durationMs,
+        ip: exchange.ip,
+        userAgent: exchange.userAgent,
+        requestId: exchange.context.requestId,
+        correlationId: exchange.context.correlationId,
+        traceId: exchange.context.traceId,
+        spanId: exchange.context.spanId,
+        routeTemplate: exchange.routeTemplate,
+        integration: exchange.integration,
+        destination: exchange.destination,
+        errorCode: exchange.errorCode,
+        message: exchange.errorMessage,
+        aborted: exchange.aborted || undefined,
+        severity: failed ? "high" : undefined,
+        category: failed && exchange.integration === "proxy" ? "infrastructure" : undefined,
+        request: this.captureMessage(capture, exchange.request, search),
+        response: this.captureMessage(capture, exchange.response),
+      };
+      this.enqueue(this.toWire(event, true));
+    } catch (err) {
+      this.report("event-build", `midline: could not record a request (${(err as Error)?.message}); skipped it.`);
+    }
+  }
+
+  /** Sends whatever is buffered now, ignoring backoff, and keeps the process alive until done. */
+  async flush(): Promise<void> {
+    if (!this.active) return;
+    this.retryAfter = 0;
+    if (this.drainPromise) {
+      await this.drainPromise;
+    }
+    await this.drain(true);
+  }
+
+  /** Flushes with a deadline, then closes. For graceful shutdown. */
+  async shutdown(timeoutMs = 5000): Promise<void> {
+    if (this.active) {
+      let timeout: NodeJS.Timeout | undefined;
+      await Promise.race([
+        this.flush().catch(() => undefined),
+        new Promise<void>((resolve) => {
+          timeout = setTimeout(resolve, timeoutMs);
+        }),
+      ]);
+      if (timeout) clearTimeout(timeout);
+    }
+    this.close();
+  }
+
+  /** Stops the timer, drops the buffer and releases sockets. Safe to call more than once. */
+  close(): void {
+    this.stopped = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.queue = [];
+    this.queueBytes = 0;
+    this.transport?.destroy();
+  }
+
+  private captureMessage(capture: ResolvedCapture, message: ExchangeMessage | undefined, search?: string): CapturedMessage | undefined {
+    if (!message && !search) return undefined;
+    const out: CapturedMessage = {};
+
+    if (capture.headers && message?.headers) {
+      out.headers = this.redactor.headers(message.headers);
+    }
+    if (capture.query && search) {
+      out.query = this.redactor.query(search);
+    }
+    if (message && message.body !== undefined) {
+      Object.assign(out, this.redactor.body(message.body, message.contentType, capture.maxBodyBytes));
+      if (message.truncated) out.truncated = true;
+    }
+    if (message?.bodyBytes !== undefined && (out.body !== undefined || out.omitted)) {
+      out.bodyBytes = message.bodyBytes;
+    }
+    return Object.keys(out).length ? out : undefined;
+  }
+
+  private redactManualMessage(message: CapturedMessage | undefined): CapturedMessage | undefined {
+    if (!message) return undefined;
+    const maxBodyBytes = this.config!.capture.maxBodyBytes || 4096;
+    return {
+      ...message,
+      headers: this.redactor.headers(message.headers),
+      query: message.query ? (this.redactor.value(message.query) as CapturedMessage["query"]) : undefined,
+      ...(message.body !== undefined ? this.redactor.body(message.body, undefined, maxBodyBytes) : {}),
     };
+  }
 
-    // Add environment, host, region if configured
-    if (this.config.environment) {
-      transformed.environment = this.config.environment;
+  /**
+   * Maps an event onto the ingest schema. Everything beyond the long-standing
+   * top-level fields travels in `metadata` and `payload`, which every Midline
+   * server version accepts — so upgrading the agent never gets events rejected by a
+   * server that hasn't been upgraded yet.
+   */
+  private toWire(event: MidlineEvent, preRedacted: boolean): Record<string, unknown> {
+    const config = this.config!;
+    const type = event.type;
+    const statusCode = Number.isInteger(event.statusCode) && event.statusCode! >= 100 && event.statusCode! <= 599
+      ? event.statusCode
+      : type === "error" ? 500 : undefined;
+    const { severity, category } = classify(event, statusCode);
+    const route = this.redactor.string(stripQuery(event.path) || "/", 2048);
+
+    const payload: Record<string, unknown> = {};
+    if (type === "error" || event.message) {
+      payload.error = event.message ? this.redactor.string(event.message, 1024) : type === "error" ? "Unknown error" : undefined;
+    }
+    if (event.stack) payload.stack = this.redactor.string(event.stack, 16 * 1024);
+    if (event.breadcrumbs?.length) {
+      payload.breadcrumbs = event.breadcrumbs.slice(-20).map((crumb) => ({
+        type: String(crumb.type).slice(0, 32),
+        message: this.redactor.string(String(crumb.message), 256),
+        timestamp: crumb.timestamp,
+      }));
     }
-    if (this.config.host) {
-      transformed.host = this.config.host;
+    if (type === "error") {
+      payload.context = { route, method: event.method };
+    }
+    const request = preRedacted ? event.request : this.redactManualMessage(event.request);
+    const response = preRedacted ? event.response : this.redactManualMessage(event.response);
+    if (request) payload.request = request;
+    if (response) payload.response = response;
+    if (event.destination) payload.destination = { url: this.redactor.string(event.destination.url, 2048) };
+    if (event.errorCode) payload.code = String(event.errorCode).slice(0, 64);
+
+    const metadata: Record<string, unknown> = {
+      source: "sdk",
+      sdk: "midline-agent",
+      version: SDK_VERSION,
+      integrationType: event.integration ?? "manual",
+    };
+    if (event.requestId) metadata.requestId = event.requestId;
+    if (event.correlationId) metadata.correlationId = event.correlationId;
+    if (event.routeTemplate) metadata.routeTemplate = event.routeTemplate.slice(0, 512);
+    if (event.aborted) metadata.aborted = true;
+
+    const wire: Record<string, unknown> = {
+      apiKey: config.apiKey,
+      eventType: type,
+      route,
+      method: (event.method || "GET").toUpperCase().slice(0, 16),
+      statusCode,
+      responseTime: Math.min(Math.max(0, Math.round(Number(event.duration) || 0)), 86_400_000),
+      timestamp: validTimestamp(event.timestamp),
+      // Clamped to the server's validation limits: one over-long field would
+      // otherwise get every event rejected.
+      ip: clamp(event.ip, 64),
+      userAgent: clamp(event.userAgent, 512),
+      service: clamp(config.serviceName, 128),
+      environment: clamp(config.environment, 128),
+      host: clamp(config.host, 256),
+      region: clamp(config.region, 64),
+      release: clamp(config.release, 128),
+      severity,
+      category,
+      traceId: clamp(event.traceId, 128),
+      spanId: clamp(event.spanId, 128),
+      ruleId: clamp(event.ruleId, 128),
+      threatDetected: typeof event.threatDetected === "boolean" ? event.threatDetected : undefined,
+      metadata,
+      payload: Object.keys(payload).length ? payload : undefined,
+    };
+
+    for (const key of Object.keys(wire)) {
+      if (wire[key] === undefined) delete wire[key];
     }
-    if (this.config.region) {
-      transformed.region = this.config.region;
+    return wire;
+  }
+
+  private enqueue(wire: Record<string, unknown>): void {
+    const config = this.config!;
+    let bytes = Buffer.byteLength(JSON.stringify(wire));
+
+    if (bytes > config.maxEventBytes) {
+      bytes = shrink(wire, config.maxEventBytes);
+      if (bytes > config.maxEventBytes) {
+        this.dropped += 1;
+        this.report("event-too-large", `midline: an event was larger than maxEventBytes (${config.maxEventBytes}) even without bodies; dropped it.`);
+        return;
+      }
     }
-    if (this.config.release) {
-      transformed.release = this.config.release;
+
+    this.queue.push({ wire, bytes });
+    this.queueBytes += bytes;
+    this.trimQueue();
+  }
+
+  /** Oldest events go first — during an outage the most recent minute is worth more than the first. */
+  private trimQueue(): void {
+    const config = this.config!;
+    while (this.queue.length > config.maxQueueSize || (this.queueBytes > MAX_QUEUE_BYTES && this.queue.length > 1)) {
+      const removed = this.queue.shift()!;
+      this.queueBytes -= removed.bytes;
+      this.dropped += 1;
     }
+  }
 
-    // For errors, add error-specific fields
-    if (isError) {
-      transformed.severity = "critical";
-      transformed.category = "application";
-      transformed.payload = {
-        error: event.message || "Unknown error",
-        stack: event.stack,
-        context: {
-          route: event.path,
-          method: event.method
-        },
-        breadcrumbs: event.breadcrumbs
-      };
-    } else {
-      // For requests, use appropriate category and severity
-      transformed.category = "performance";
-
-      // Map status codes to valid severity levels: low, medium, high, critical
-      if (event.statusCode) {
-        if (event.statusCode >= 500) {
-          transformed.severity = "high";
-          transformed.category = "application"; // Server errors are application issues
-        } else if (event.statusCode >= 400) {
-          transformed.severity = "medium";
-          transformed.category = "application"; // Client errors are application issues
+  private requeue(batch: QueuedEvent[]): void {
+    this.queue.unshift(...batch);
+    this.queueBytes += batch.reduce((sum, item) => sum + item.bytes, 0);
+    this.trimQueue();
+  }
+
+  private takeBatch(): QueuedEvent[] {
+    const config = this.config!;
+    const batch: QueuedEvent[] = [];
+    let bytes = 0;
+    const limit = Math.min(config.maxBatchSize, this.batchLimit);
+    while (this.queue.length && batch.length < limit) {
+      const next = this.queue[0];
+      if (batch.length > 0 && bytes + next.bytes > this.maxRequestBytes) break;
+      batch.push(this.queue.shift()!);
+      bytes += next.bytes;
+      this.queueBytes -= next.bytes;
+    }
+    return batch;
+  }
+
+  private drain(keepProcessAlive: boolean): Promise<void> {
+    if (this.drainPromise) return this.drainPromise;
+    if (!this.active || !this.queue.length || Date.now() < this.retryAfter) {
+      return Promise.resolve();
+    }
+    this.drainPromise = this.runDrain(keepProcessAlive).finally(() => {
+      this.drainPromise = null;
+    });
+    return this.drainPromise;
+  }
+
+  private async runDrain(keepProcessAlive: boolean): Promise<void> {
+    while (this.queue.length && this.active) {
+      // Taken off the queue while in flight, so overflow trimming can't remove
+      // events that are mid-send and then be confused about what was accepted.
+      const batch = this.takeBatch();
+      const outcome = await this.send(batch, keepProcessAlive);
+
+      if (outcome.kind === "ok") {
+        this.onSuccess();
+        continue;
+      }
+      if (outcome.kind === "stop") {
+        this.disable();
+        return;
+      }
+      if (outcome.kind === "tooLarge") {
+        if (batch.length > 1) {
+          // Halve by count as well as bytes: a byte floor alone would resend the
+          // same batch of small events forever. The server's limit doesn't move,
+          // so the smaller size sticks.
+          const batchBytes = batch.reduce((sum, item) => sum + item.bytes, 0);
+          this.batchLimit = Math.max(1, Math.floor(batch.length / 2));
+          this.maxRequestBytes = Math.max(MIN_REQUEST_BYTES, Math.min(this.maxRequestBytes, Math.floor(batchBytes / 2)));
+          this.requeue(batch);
         } else {
-          transformed.severity = "low";
+          this.dropped += 1;
+          this.report("http-413", "midline: the Midline server rejected an event as too large (HTTP 413); dropped it.");
         }
+        continue;
+      }
+      if (outcome.kind === "rejected") {
+        if (batch.length === 1) {
+          this.dropped += 1;
+          this.report(`rejected:${outcome.detail}`, `midline: the Midline server rejected an event (${outcome.detail}); dropped it.`);
+          continue;
+        }
+        // One malformed event fails validation for the whole batch. Send them one
+        // at a time so it only costs that event.
+        const isolated = await this.sendIndividually(batch, keepProcessAlive);
+        if (!isolated) return;
+        continue;
+      }
+
+      this.requeue(batch);
+      this.onFailure(outcome.retryAfterMs);
+      return;
+    }
+  }
+
+  /** Returns false if delivery should stop for this drain. */
+  private async sendIndividually(batch: QueuedEvent[], keepProcessAlive: boolean): Promise<boolean> {
+    for (let index = 0; index < batch.length; index++) {
+      const outcome = await this.send([batch[index]], keepProcessAlive);
+      if (outcome.kind === "ok") {
+        this.onSuccess();
+      } else if (outcome.kind === "rejected" || outcome.kind === "tooLarge") {
+        this.dropped += 1;
+        const detail = outcome.kind === "rejected" ? outcome.detail : "HTTP 413";
+        this.report(`rejected:${detail}`, `midline: the Midline server rejected an event (${detail}); dropped it.`);
+      } else if (outcome.kind === "stop") {
+        this.disable();
+        return false;
       } else {
-        transformed.severity = "low";
+        this.requeue(batch.slice(index));
+        this.onFailure(outcome.retryAfterMs);
+        return false;
       }
     }
+    return true;
+  }
 
-    return transformed;
-  }
-
-  private static startQueue() {
-    this.timer = setInterval(async () => {
-      if (!this.queue.length) return;
-      const batch = [...this.queue];
-      this.queue = [];
-
-      // Transform events to match the expected API format
-      const transformedBatch = batch.map(event => this.transformEvent(event));
-      // Send each event individually (or as a batch if API supports it)
-      for (const event of transformedBatch) {
-        try {
-          const response = await fetch(this.config.endpoint!, {
-            method: "POST",
-            headers: {
-              "Content-Type": "application/json"
-            },
-            body: JSON.stringify(event)
-          });
-        } catch (err) {
-          console.error("MidlineAgent send error:", err);
-        }
+  private async send(batch: QueuedEvent[], keepProcessAlive: boolean): Promise<Outcome> {
+    const config = this.config!;
+    const body = JSON.stringify({ events: batch.map((item) => item.wire) });
+
+    let result;
+    try {
+      result = await this.transport!.post(config.batchUrl, body, { "x-api-key": config.apiKey }, keepProcessAlive);
+    } catch (err) {
+      this.report(`transport:${errorCode(err)}`, this.describe(err, batch.length));
+      return { kind: "retry" };
+    }
+
+    const { status } = result;
+    if (status >= 200 && status < 300) {
+      // Servers that predate 401-on-bad-key answer 201 and count the rejects.
+      const summary = parseJson(result.body);
+      const failed = typeof summary?.failed === "number" ? summary.failed : 0;
+      if (failed >= batch.length && batch.length > 0) {
+        this.log("error", "midline: the Midline server did not accept this API key. Monitoring is now off — retrying wouldn't help. Check apiKey / MIDLINE_API_KEY.");
+        return { kind: "stop" };
+      }
+      if (failed > 0) {
+        this.dropped += failed;
+        this.report("partial", `midline: the Midline server rejected ${failed} of ${batch.length} events.`);
+      }
+      return { kind: "ok" };
+    }
+    if (status === 401 || status === 403) {
+      this.log(
+        "error",
+        `midline: the Midline server rejected the API key (HTTP ${status}). ` +
+          "Monitoring is now off — retrying wouldn't help. Check apiKey / MIDLINE_API_KEY.",
+      );
+      return { kind: "stop" };
+    }
+    if (status === 413) {
+      return { kind: "tooLarge" };
+    }
+    if (status === 408 || status === 429 || status >= 500) {
+      const retryAfterMs = parseRetryAfter(result.headers["retry-after"]);
+      this.report(`http-${status}`, `midline: the Midline server returned HTTP ${status}; events are buffered and will be retried.`);
+      return { kind: "retry", retryAfterMs };
+    }
+    if (status >= 300 && status < 400) {
+      // Never followed: that would hand the API key to wherever the redirect points.
+      const location = String(result.headers.location ?? "").slice(0, 200);
+      this.report(
+        `http-${status}`,
+        `midline: the Midline endpoint redirected (HTTP ${status}${location ? ` to ${location}` : ""}). ` +
+          "Redirects are not followed; set MIDLINE_ENDPOINT to the final URL.",
+      );
+      return { kind: "retry" };
+    }
+    return { kind: "rejected", detail: `HTTP ${status}${serverMessage(result.body)}` };
+  }
+
+  /** One line per distinct fault, not one per failed event. */
+  private report(signature: string, message: string): void {
+    if (this.lastNotice === signature && !this.debugLogs) {
+      return;
+    }
+    this.lastNotice = signature;
+    this.log("warn", message);
+  }
+
+  private describe(err: unknown, inFlight: number): string {
+    const config = this.config!;
+    const origin = config.ingestUrl.origin;
+    const code = errorCode(err);
+    const buffered = ` ${this.queue.length + inFlight} event(s) buffered; your application is unaffected.`;
+
+    if (TLS_ERROR_REASONS[code] || code.startsWith("ERR_SSL") || code === "EPROTO") {
+      const reason = TLS_ERROR_REASONS[code] ?? "failed the TLS handshake";
+      return (
+        `midline: ${origin} ${reason} (${code}), so the connection was refused. Certificate verification stays on. ` +
+        (config.hasCustomCa
+          ? "The configured ca / MIDLINE_CUSTOM_CA did not validate it either. "
+          : "If this is the Midline server, its HTTPS certificate needs fixing on the server; for a self-hosted server behind a private CA, set ca / MIDLINE_CUSTOM_CA. ") +
+        `Delivery resumes on its own once a trusted certificate is served.${buffered}`
+      );
+    }
+    if (code === "ETIMEDOUT") {
+      return `midline: ${origin} did not answer within ${config.timeoutMs}ms; retrying with backoff.${buffered}`;
+    }
+    if (code === "ECONNECT_TIMEOUT") {
+      return `midline: could not connect to ${origin} within ${config.connectTimeoutMs}ms; retrying with backoff.${buffered}`;
+    }
+    if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
+      return `midline: cannot resolve ${config.ingestUrl.hostname} (${code}) — check MIDLINE_ENDPOINT and DNS; retrying with backoff.${buffered}`;
+    }
+    if (code === "ECONNREFUSED") {
+      return `midline: ${origin} refused the connection; retrying with backoff.${buffered}`;
+    }
+    if (code === "ECONNRESET" || code === "EPIPE") {
+      return `midline: the connection to ${origin} was reset; retrying with backoff.${buffered}`;
+    }
+    return `midline: could not reach ${origin} (${code || (err as Error)?.message || "unknown error"}); retrying with backoff.${buffered}`;
+  }
+
+  private onSuccess(): void {
+    if (this.failures > 0) {
+      const lost = this.dropped;
+      this.log("info", `midline: delivery to the Midline server recovered${lost ? `; ${lost} event(s) were dropped meanwhile` : ""}.`);
+      this.dropped = 0;
+      // Only a recovered outage resets de-duplication; a stream of individually
+      // rejected events between successes should still log once.
+      this.lastNotice = "";
+    }
+    this.failures = 0;
+    this.retryAfter = 0;
+  }
+
+  private onFailure(retryAfterMs?: number): void {
+    const config = this.config!;
+    this.failures += 1;
+    // Exponential backoff, capped, with jitter so a fleet of instances doesn't
+    // retry in lockstep against a server that is coming back up.
+    const ceiling = Math.min(config.flushIntervalMs * 2 ** Math.min(this.failures, 12), config.maxRetryDelayMs);
+    const backoff = Math.round(ceiling * (0.5 + Math.random() * 0.5));
+    const wait = retryAfterMs !== undefined ? Math.min(Math.max(retryAfterMs, backoff), config.maxRetryDelayMs) : backoff;
+    this.retryAfter = Date.now() + wait;
+  }
+
+  /** Unrecoverable configuration problem: go quiet instead of looping forever. */
+  private disable(): void {
+    this.close();
+  }
+
+  private log(level: "info" | "warn" | "error", message: string): void {
+    if (this.onErrorHook) {
+      try {
+        this.onErrorHook(message);
+      } catch {
+        // A broken logging hook must not become the host application's problem.
       }
-    }, 1500);
+      if (!this.debugLogs) return;
+    }
+    if (level === "error") console.error(message);
+    else if (level === "warn") console.warn(message);
+    else console.info(message);
+  }
+}
+
+function classify(event: MidlineEvent, statusCode: number | undefined): { severity: EventSeverity; category: EventCategory } {
+  if (event.severity && event.category) {
+    return { severity: event.severity, category: event.category };
   }
+  let severity: EventSeverity = "low";
+  let category: EventCategory = "performance";
+
+  if (event.type === "error") {
+    severity = "critical";
+    category = "application";
+  } else if (event.type === "security") {
+    severity = "high";
+    category = "security";
+  } else if (event.type === "custom") {
+    category = "business";
+  } else if (statusCode && statusCode >= 500) {
+    severity = "high";
+    category = "application";
+  } else if (statusCode && statusCode >= 400) {
+    severity = "medium";
+    category = "application";
+  }
+  return { severity: event.severity ?? severity, category: event.category ?? category };
+}
+
+/** Drops the heaviest optional parts until the event fits. Returns the new size. */
+function shrink(wire: Record<string, unknown>, maxBytes: number): number {
+  const payload = wire.payload as Record<string, any> | undefined;
+  const size = () => Buffer.byteLength(JSON.stringify(wire));
+  if (!payload) return size();
+
+  const steps: Array<() => void> = [
+    () => markOmitted(payload.response, "body"),
+    () => markOmitted(payload.request, "body"),
+    () => {
+      if (typeof payload.stack === "string") payload.stack = payload.stack.slice(0, 2048);
+    },
+    () => delete payload.breadcrumbs,
+    () => markOmitted(payload.response, "headers"),
+    () => markOmitted(payload.request, "headers"),
+    () => markOmitted(payload.request, "query"),
+  ];
+  let bytes = size();
+  for (const step of steps) {
+    if (bytes <= maxBytes) break;
+    step();
+    bytes = size();
+  }
+  return bytes;
+}
+
+function markOmitted(message: Record<string, any> | undefined, field: string): void {
+  if (message && message[field] !== undefined) {
+    delete message[field];
+    message.omitted = "event size limit";
+  }
+}
+
+function clamp(value: unknown, max: number): string | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  return String(value).slice(0, max);
+}
+
+function stripQuery(path: string): string {
+  const index = path.search(/[?#]/);
+  return index === -1 ? path : path.slice(0, index);
+}
+
+function validTimestamp(value: string | undefined): string {
+  if (value) {
+    const parsed = Date.parse(value);
+    if (Number.isFinite(parsed)) return new Date(parsed).toISOString();
+  }
+  return new Date().toISOString();
+}
+
+function errorCode(err: unknown): string {
+  const e = err as any;
+  return String(e?.code ?? e?.cause?.code ?? e?.errno ?? e?.name ?? "");
+}
+
+function parseJson(text: string): any {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+function serverMessage(body: string): string {
+  const message = parseJson(body)?.message;
+  const text = Array.isArray(message) ? message.join("; ") : typeof message === "string" ? message : "";
+  return text ? `: ${text.slice(0, 300)}` : "";
+}
+
+function parseRetryAfter(header: string | string[] | undefined): number | undefined {
+  const value = Array.isArray(header) ? header[0] : header;
+  if (!value) return undefined;
+  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()) : undefined;
 }