midline-agent 0.4.0 → 0.5.0

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);
+}

package/test/agent.test.js

@@ -4,8 +4,8 @@ const test = require("node:test");
 const assert = require("node:assert/strict");
 const tls = require("tls");
 const { MidlineAgent } = require("../dist");
-const { ConfigError, loadCa, resolveIngestUrl, trustStore } = require("../dist/config");
-const { makeCerts, startCollector, closedPort, diagnostics } = require("./helpers");
+const { ConfigError, loadCa, resolveEndpointOrigin, trustStore } = require("../dist/config");
+const { makeCerts, startSocketCollector, closedPort, diagnostics } = require("./helpers");
 
 const certs = makeCerts();
 const needsOpenssl = certs ? {} : { skip: "openssl not available" };
@@ -22,27 +22,27 @@ function agentFor(endpoint, extra = {}) {
   });
 }
 
-test("endpoint: a base URL gets the ingest path, a full URL is kept", () => {
-  assert.equal(resolveIngestUrl("https://api.usemidline.com").href, "https://api.usemidline.com/api/api-monitor/events");
-  assert.equal(resolveIngestUrl("https://api.usemidline.com/").href, "https://api.usemidline.com/api/api-monitor/events");
+test("endpoint: only the origin matters, an old-style ingest path is tolerated", () => {
+  assert.equal(resolveEndpointOrigin("https://api.usemidline.com").href, "https://api.usemidline.com/");
+  assert.equal(resolveEndpointOrigin("https://api.usemidline.com/").href, "https://api.usemidline.com/");
   assert.equal(
-    resolveIngestUrl("https://api.usemidline.com/api/api-monitor/events").href,
-    "https://api.usemidline.com/api/api-monitor/events",
+    resolveEndpointOrigin("https://api.usemidline.com/api/api-monitor/events").href,
+    "https://api.usemidline.com/",
   );
   assert.equal(
-    resolveIngestUrl("https://api.usemidline.com/api/api-monitor/events/batch").href,
-    "https://api.usemidline.com/api/api-monitor/events",
+    resolveEndpointOrigin("https://api.usemidline.com/api/api-monitor/events/batch").href,
+    "https://api.usemidline.com/",
   );
-  assert.equal(resolveIngestUrl("https://gw.internal/midline").href, "https://gw.internal/midline/api/api-monitor/events");
-  assert.equal(resolveIngestUrl("http://localhost:8000").href, "http://localhost:8000/api/api-monitor/events");
-  assert.equal(resolveIngestUrl("http://127.0.0.1:8000").href, "http://127.0.0.1:8000/api/api-monitor/events");
+  assert.equal(resolveEndpointOrigin("https://gw.internal/midline").href, "https://gw.internal/");
+  assert.equal(resolveEndpointOrigin("http://localhost:8000").href, "http://localhost:8000/");
+  assert.equal(resolveEndpointOrigin("http://127.0.0.1:8000").href, "http://127.0.0.1:8000/");
 });
 
 test("endpoint: plain http to a non-loopback host is refused, so the key never travels in cleartext", () => {
-  assert.throws(() => resolveIngestUrl("http://api.usemidline.com"), ConfigError);
-  assert.throws(() => resolveIngestUrl("http://10.0.0.5:8000"), /cleartext/);
-  assert.throws(() => resolveIngestUrl("ftp://api.usemidline.com"), ConfigError);
-  assert.throws(() => resolveIngestUrl("https://user:pass@api.usemidline.com"), /credentials/);
+  assert.throws(() => resolveEndpointOrigin("http://api.usemidline.com"), ConfigError);
+  assert.throws(() => resolveEndpointOrigin("http://10.0.0.5:8000"), /cleartext/);
+  assert.throws(() => resolveEndpointOrigin("ftp://api.usemidline.com"), ConfigError);
+  assert.throws(() => resolveEndpointOrigin("https://user:pass@api.usemidline.com"), /credentials/);
 
   const { messages, onError } = diagnostics();
   const agent = new MidlineAgent({ apiKey: "ak_x", endpoint: "http://api.usemidline.com", onError });
@@ -73,7 +73,7 @@ test("custom CA: appended to the default trust store, bad input fails loudly", n
 });
 
 test("TLS: a self-signed Midline server is refused, events stay buffered, the app is unaffected", needsOpenssl, async () => {
-  const collector = await startCollector({ tls: certs.selfSigned });
+  const collector = await startSocketCollector({ tls: certs.selfSigned });
   const { messages, onError } = diagnostics();
   const agent = agentFor(collector.url, { onError });
   try {
@@ -93,13 +93,12 @@ test("TLS: a self-signed Midline server is refused, events stay buffered, the ap
 });
 
 test("TLS: a private CA passed via `ca` is trusted for the Midline server", needsOpenssl, async () => {
-  const collector = await startCollector({ tls: certs.trusted });
+  const collector = await startSocketCollector({ tls: certs.trusted });
   const agent = agentFor(collector.url, { ca: certs.ca });
   try {
     agent.addEvent({ type: "request", path: "/hello", method: "GET", statusCode: 200 });
     await agent.flush();
     assert.equal(collector.requests.length, 1);
-    assert.equal(collector.requests[0].url, "/api/api-monitor/events/batch");
     assert.equal(collector.requests[0].headers["x-api-key"], "ak_test_key");
     assert.equal(agent.queued, 0);
   } finally {
@@ -109,7 +108,7 @@ test("TLS: a private CA passed via `ca` is trusted for the Midline server", need
 });
 
 test("TLS: a trusted CA still does not excuse a certificate for the wrong hostname", needsOpenssl, async () => {
-  const collector = await startCollector({ tls: certs.wrongHost });
+  const collector = await startSocketCollector({ tls: certs.wrongHost });
   const { messages, onError } = diagnostics();
   const agent = agentFor(collector.url, { ca: certs.ca, onError });
   try {
@@ -124,7 +123,7 @@ test("TLS: a trusted CA still does not excuse a certificate for the wrong hostna
 });
 
 test("MIDLINE_CUSTOM_CA (file path) is honoured", needsOpenssl, async () => {
-  const collector = await startCollector({ tls: certs.trusted });
+  const collector = await startSocketCollector({ tls: certs.trusted });
   process.env.MIDLINE_CUSTOM_CA = certs.caPath;
   const agent = agentFor(collector.url);
   try {
@@ -139,7 +138,7 @@ test("MIDLINE_CUSTOM_CA (file path) is honoured", needsOpenssl, async () => {
 });
 
 test("wire format stays inside the long-standing ingest schema", async () => {
-  const collector = await startCollector();
+  const collector = await startSocketCollector();
   const agent = agentFor(collector.url, { environment: "test", release: "v1" });
   try {
     agent.addEvent({
@@ -176,9 +175,9 @@ test("wire format stays inside the long-standing ingest schema", async () => {
   }
 });
 
-test("5xx and 429 are retried with backoff and keep the events", async () => {
-  const collector = await startCollector({
-    respond: () => ({ status: 503, body: { message: "down" }, headers: { "retry-after": "1" } }),
+test("rate-limited acks are retried with backoff and keep the events", async () => {
+  const collector = await startSocketCollector({
+    respond: () => ({ ok: false, code: "rate_limited", message: "rate limited", retryAfterMs: 1000 }),
   });
   const { messages, onError } = diagnostics();
   const agent = agentFor(collector.url, { onError });
@@ -189,7 +188,7 @@ test("5xx and 429 are retried with backoff and keep the events", async () => {
     assert.equal(agent.queued, 2);
     assert.equal(collector.requests.length, 1, "one attempt per drain, not one per event");
 
-    collector.setResponder(() => ({ status: 201, body: { success: 2, failed: 0 } }));
+    collector.setResponder(() => ({ ok: true, accepted: 2, rejected: 0 }));
     await agent.flush();
     assert.equal(agent.queued, 0);
     assert.match(messages.at(-1), /recovered/);
@@ -199,8 +198,8 @@ test("5xx and 429 are retried with backoff and keep the events", async () => {
   }
 });
 
-test("401 turns the agent off instead of retrying forever", async () => {
-  const collector = await startCollector({ respond: () => ({ status: 401, body: { message: "Invalid API key" } }) });
+test("unauthorized turns the agent off instead of retrying forever", async () => {
+  const collector = await startSocketCollector({ respond: () => ({ ok: false, code: "unauthorized", message: "Invalid API key" }) });
   const { onError } = diagnostics();
   const agent = agentFor(collector.url, { onError });
   try {
@@ -215,8 +214,10 @@ test("401 turns the agent off instead of retrying forever", async () => {
   }
 });
 
-test("an older server's 201 with every event failed is treated as a rejected key", async () => {
-  const collector = await startCollector({ respond: (req) => ({ status: 201, body: { success: 0, failed: req.body.events.length } }) });
+test("an ack with every event rejected is treated as a rejected key", async () => {
+  const collector = await startSocketCollector({
+    respond: (record) => ({ ok: true, accepted: 0, rejected: record.body.events.length }),
+  });
   const { onError } = diagnostics();
   const agent = agentFor(collector.url, { onError });
   try {
@@ -229,14 +230,14 @@ test("an older server's 201 with every event failed is treated as a rejected key
   }
 });
 
-test("one malformed event costs only itself: a 400 batch is re-sent one by one", async () => {
-  const collector = await startCollector({
-    respond: (req) => {
-      const events = req.body.events;
+test("one malformed event costs only itself: a bad_request batch is re-sent one by one", async () => {
+  const collector = await startSocketCollector({
+    respond: (record) => {
+      const events = record.body.events;
       if (events.some((event) => event.route === "/bad")) {
-        return { status: 400, body: { message: ["route must be shorter"] } };
+        return { ok: false, code: "bad_request", message: "route must be shorter" };
       }
-      return { status: 201, body: { success: events.length, failed: 0 } };
+      return { ok: true, accepted: events.length, rejected: 0 };
     },
   });
   const { messages, onError } = diagnostics();
@@ -259,10 +260,10 @@ test("one malformed event costs only itself: a 400 batch is re-sent one by one",
   }
 });
 
-test("413 halves the batch instead of dropping it", async () => {
-  const collector = await startCollector({
-    respond: (req) =>
-      req.body.events.length > 1 ? { status: 413, body: {} } : { status: 201, body: { success: 1, failed: 0 } },
+test("too_large halves the batch instead of dropping it", async () => {
+  const collector = await startSocketCollector({
+    respond: (record) =>
+      record.body.events.length > 1 ? { ok: false, code: "too_large", message: "too large" } : { ok: true, accepted: 1, rejected: 0 },
   });
   const agent = agentFor(collector.url, { onError: () => {} });
   try {
@@ -295,14 +296,10 @@ test("unreachable Midline server: bounded queue, oldest dropped, nothing thrown"
   }
 });
 
-test("timeouts: a server that never answers does not stall delivery", async () => {
-  const http = require("http");
-  const sockets = new Set();
-  const server = http.createServer(() => {});
-  server.on("connection", (socket) => sockets.add(socket));
-  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+test("timeouts: a server that connects but never acks does not stall delivery", async () => {
+  const collector = await startSocketCollector({ noAck: true });
   const { messages, onError } = diagnostics();
-  const agent = agentFor(`http://127.0.0.1:${server.address().port}`, { onError, timeoutMs: 200 });
+  const agent = agentFor(collector.url, { onError, timeoutMs: 200 });
   try {
     agent.addEvent({ type: "request", path: "/slow" });
     const started = Date.now();
@@ -312,13 +309,12 @@ test("timeouts: a server that never answers does not stall delivery", async () =
     assert.match(messages[0], /did not answer within 200ms/);
   } finally {
     agent.close();
-    for (const socket of sockets) socket.destroy();
-    await new Promise((resolve) => server.close(resolve));
+    await collector.close();
   }
 });
 
 test("oversized events lose their captured bodies before they are dropped", async () => {
-  const collector = await startCollector();
+  const collector = await startSocketCollector();
   const agent = agentFor(collector.url, { maxEventBytes: 2048 });
   try {
     agent.addEvent({
@@ -338,7 +334,7 @@ test("oversized events lose their captured bodies before they are dropped", asyn
 });
 
 test("static facade keeps working for existing integrations", async () => {
-  const collector = await startCollector();
+  const collector = await startSocketCollector();
   try {
     const agent = MidlineAgent.init({ apiKey: "ak_static", endpoint: collector.url, flushIntervalMs: 60_000 });
     assert.equal(MidlineAgent.current, agent);

package/test/browser.test.js

@@ -75,7 +75,7 @@ function uncaught(win, error, extra = {}) {
 
 async function withSdk(config, run, windowOptions) {
   const env = fakeWindow(windowOptions);
-  Midline.init({ apiKey: KEY, flushIntervalMs: 60_000, captureWebVitals: false, ...config });
+  Midline.init({ apiKey: KEY, flushIntervalMs: 60_000, captureWebVitals: false, capturePageviews: false, ...config });
   try {
     await run(env);
   } finally {
@@ -298,7 +298,7 @@ test("browser: navigation starts a new trace; close restores everything it wrapp
   const originalPush = win.history.pushState;
   const originalError = win.console.error;
 
-  Midline.init({ apiKey: KEY, flushIntervalMs: 60_000, captureWebVitals: false, captureConsole: true });
+  Midline.init({ apiKey: KEY, flushIntervalMs: 60_000, captureWebVitals: false, capturePageviews: false, captureConsole: true });
   assert.notEqual(win.fetch, originalFetch);
 
   Midline.captureMessage("before");
@@ -316,6 +316,52 @@ test("browser: navigation starts a new trace; close restores everything it wrapp
   delete globalThis.window;
 });
 
+test("browser: pageviews fire on load and on SPA navigation, sharing one sessionId", async () => {
+  const env = fakeWindow();
+  const { win } = env;
+  win.document.referrer = "https://google.com/search";
+
+  Midline.init({ apiKey: KEY, flushIntervalMs: 60_000, captureWebVitals: false });
+  win.history.pushState({}, "", "/pricing");
+  win.history.replaceState({}, "", "/pricing/annual");
+  await Midline.flush();
+
+  const [initial, pushed, replaced] = env.sent();
+  assert.equal(env.sent().length, 3);
+  assert.equal(initial.eventType, "pageview");
+  assert.equal(initial.route, "/checkout");
+  assert.equal(initial.payload.referrer, "https://google.com/search");
+  assert.equal(pushed.eventType, "pageview");
+  assert.equal(pushed.route, "/pricing");
+  assert.equal(pushed.payload, undefined); // only the initial load carries a referrer
+  assert.equal(replaced.eventType, "pageview");
+  assert.equal(replaced.route, "/pricing/annual");
+
+  // One session for the whole tab, and every event — not just pageviews — carries it.
+  assert.match(initial.sessionId, /^[a-f0-9]{16,64}$/);
+  assert.ok([initial, pushed, replaced].every((event) => event.sessionId === initial.sessionId));
+
+  await Midline.close();
+  delete globalThis.window;
+});
+
+test("browser: capturePageviews: false suppresses pageviews without disabling other capture", async () => {
+  const env = fakeWindow();
+  const { win } = env;
+  Midline.init({ apiKey: KEY, flushIntervalMs: 60_000, captureWebVitals: false, capturePageviews: false });
+  win.history.pushState({}, "", "/pricing");
+  Midline.captureMessage("still works");
+  await Midline.flush();
+
+  const events = env.sent();
+  assert.ok(events.every((event) => event.eventType !== "pageview"));
+  assert.equal(events.length, 1);
+  assert.equal(events[0].payload.message, "still works");
+
+  await Midline.close();
+  delete globalThis.window;
+});
+
 test("browser: pending events go out with keepalive when the page is hidden", async () => {
   await withSdk({}, async ({ win, calls }) => {
     Midline.captureMessage("leaving");

package/test/console.test.js

@@ -3,7 +3,7 @@
 const test = require("node:test");
 const assert = require("node:assert/strict");
 const { MidlineAgent } = require("../dist");
-const { startCollector, diagnostics } = require("./helpers");
+const { startSocketCollector, diagnostics } = require("./helpers");
 
 function agentFor(endpoint, extra = {}) {
   return new MidlineAgent({
@@ -47,7 +47,7 @@ const consoleEvents = (collector) => collector.events().filter((event) => event.
 
 test("console capture: printed lines become console events and the output itself is untouched", async () => {
   const streams = recordStreams();
-  const collector = await startCollector();
+  const collector = await startSocketCollector();
   const agent = agentFor(collector.url);
   try {
     const coloured = "\x1b[32m[Nest] 4242  - LOG [NestApplication] Nest application successfully started\x1b[39m\n";
@@ -95,7 +95,7 @@ test("console capture: printed lines become console events and the output itself
 
 test("console capture: the agent's own warnings are not captured, and close() puts the streams back", async () => {
   const streams = recordStreams();
-  const collector = await startCollector({ respond: () => ({ status: 503, body: { message: "down" } }) });
+  const collector = await startSocketCollector({ respond: () => ({ ok: false, code: "rate_limited", message: "down" }) });
   // No onError: the agent's diagnostics go to the console, where capture could see them.
   const agent = agentFor(collector.url);
   try {
@@ -104,7 +104,7 @@ test("console capture: the agent's own warnings are not captured, and close() pu
     await agent.flush();
     assert.ok(streams.written.stderr.some((chunk) => chunk.includes("midline:")), "the warning was printed");
 
-    collector.setResponder((req) => ({ status: 201, body: { success: req.body.events.length, failed: 0 } }));
+    collector.setResponder((record) => ({ ok: true, accepted: record.body.events.length, rejected: 0 }));
     await agent.flush();
     const messages = consoleEvents(collector).map((event) => event.payload.message);
     assert.ok(messages.includes("before the outage"));
@@ -122,16 +122,17 @@ test("console capture: the agent's own warnings are not captured, and close() pu
 
 test("console capture: a server without console events turns capture off and requests keep flowing", async () => {
   const streams = recordStreams();
-  const collector = await startCollector({
-    respond: (req) => {
-      const events = req.body.events;
+  const collector = await startSocketCollector({
+    respond: (record) => {
+      const events = record.body.events;
       if (events.some((event) => event.eventType === "console")) {
         return {
-          status: 400,
-          body: { message: ["events.1.eventType must be one of the following values: request, error, security, performance, custom"] },
+          ok: false,
+          code: "bad_request",
+          message: "events.1.eventType must be one of the following values: request, error, security, performance, custom",
         };
       }
-      return { status: 201, body: { success: events.length, failed: 0 } };
+      return { ok: true, accepted: events.length, rejected: 0 };
     },
   });
   const { messages, onError } = diagnostics();

package/test/helpers.js

@@ -90,6 +90,59 @@ async function startCollector({ tls, respond } = {}) {
   };
 }
 
+/**
+ * A fake ingest gateway: a real socket.io server on the `/ingest` namespace,
+ * recording what it receives and acking with whatever `respond` returns
+ * (defaulting to "everything accepted"). Shaped like `startCollector` so most
+ * assertions port over unchanged: `requests`, `events()`, `setResponder()`, `close()`.
+ */
+async function startSocketCollector({ tls, respond, noAck } = {}) {
+  const { Server } = require("socket.io");
+  const requests = [];
+  let responder =
+    respond ||
+    ((record) => ({ ok: true, accepted: (record.body?.events || []).length, rejected: 0 }));
+
+  const httpServer = tls ? https.createServer(tls) : http.createServer();
+  await new Promise((resolve) => httpServer.listen(0, "127.0.0.1", resolve));
+  const { port } = httpServer.address();
+
+  const io = new Server(httpServer, { cors: { origin: "*" } });
+  const nsp = io.of("/ingest");
+  nsp.on("connection", (socket) => {
+    socket.on("ingest", (payload, ack) => {
+      const record = {
+        // Old HTTP-era assertions read the key off a header; a synthesized one
+        // keeps those checks meaningful without rewriting every one of them.
+        headers: { ...socket.handshake.headers, "x-api-key": socket.handshake.auth?.apiKey },
+        auth: socket.handshake.auth,
+        body: payload,
+      };
+      requests.push(record);
+      // Simulates a connected server that never answers, so callers can exercise
+      // the SDK's per-emit ack timeout rather than its connect timeout.
+      if (noAck) return;
+      ack(responder(record, requests.length));
+    });
+  });
+
+  return {
+    url: `${tls ? "https" : "http"}://${tls ? "localhost" : "127.0.0.1"}:${port}`,
+    port,
+    requests,
+    events: () => requests.flatMap((request) => (request.body && request.body.events) || []),
+    setResponder: (fn) => {
+      responder = fn;
+    },
+    close: () =>
+      new Promise((resolve) => {
+        io.close();
+        httpServer.closeAllConnections?.();
+        httpServer.close(() => resolve());
+      }),
+  };
+}
+
 /** Starts any request listener on an ephemeral loopback port. */
 async function listen(listener, tls) {
   const server = tls ? https.createServer(tls, listener) : http.createServer(listener);
@@ -148,4 +201,4 @@ async function waitFor(predicate, timeoutMs = 3000) {
   return false;
 }
 
-module.exports = { makeCerts, startCollector, listen, request, closedPort, diagnostics, waitFor };
+module.exports = { makeCerts, startCollector, startSocketCollector, listen, request, closedPort, diagnostics, waitFor };

package/test/middleware.test.js

@@ -5,10 +5,10 @@ const assert = require("node:assert/strict");
 const express = require("express");
 const { MidlineAgent, midlineMiddleware, midlineErrorHandler, getRequestContext } = require("../dist");
 const { REDACTED } = require("../dist/redact");
-const { startCollector, listen, request, closedPort, waitFor } = require("./helpers");
+const { startSocketCollector, listen, request, closedPort, waitFor } = require("./helpers");
 
 test("express: captured headers, query and bodies are redacted before they leave the process", async () => {
-  const collector = await startCollector();
+  const collector = await startSocketCollector();
   const agent = new MidlineAgent({
     apiKey: "ak_mw",
     endpoint: collector.url,
@@ -74,7 +74,7 @@ test("express: captured headers, query and bodies are redacted before they leave
 });
 
 test("express: nothing is captured beyond method/path/status unless asked", async () => {
-  const collector = await startCollector();
+  const collector = await startSocketCollector();
   const agent = new MidlineAgent({ apiKey: "ak_mw", endpoint: collector.url, flushIntervalMs: 60_000 });
   const app = express();
   app.use(midlineMiddleware({ agent }));
@@ -100,7 +100,7 @@ test("express: nothing is captured beyond method/path/status unless asked", asyn
 });
 
 test("express: errors are recorded and still reach the app's own handler", async () => {
-  const collector = await startCollector();
+  const collector = await startSocketCollector();
   const agent = new MidlineAgent({ apiKey: "ak_mw", endpoint: collector.url, flushIntervalMs: 60_000 });
   const app = express();
   app.use(midlineMiddleware({ agent }));
@@ -154,7 +154,7 @@ test("the host app is unaffected when the Midline server is unreachable or the a
 });
 
 test("plain node http servers work with the same middleware", async () => {
-  const collector = await startCollector();
+  const collector = await startSocketCollector();
   const agent = new MidlineAgent({ apiKey: "ak_mw", endpoint: collector.url, flushIntervalMs: 60_000 });
   const middleware = midlineMiddleware({ agent });
   const server = await listen((req, res) => {