midline-agent 0.1.9 → 0.3.0

package/test/agent.test.js

@@ -0,0 +1,353 @@
+"use strict";
+
+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 certs = makeCerts();
+const needsOpenssl = certs ? {} : { skip: "openssl not available" };
+
+function agentFor(endpoint, extra = {}) {
+  return new MidlineAgent({
+    apiKey: "ak_test_key",
+    serviceName: "agent-test",
+    endpoint,
+    flushIntervalMs: 60_000,
+    timeoutMs: 2000,
+    connectTimeoutMs: 1000,
+    ...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");
+  assert.equal(
+    resolveIngestUrl("https://api.usemidline.com/api/api-monitor/events").href,
+    "https://api.usemidline.com/api/api-monitor/events",
+  );
+  assert.equal(
+    resolveIngestUrl("https://api.usemidline.com/api/api-monitor/events/batch").href,
+    "https://api.usemidline.com/api/api-monitor/events",
+  );
+  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");
+});
+
+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/);
+
+  const { messages, onError } = diagnostics();
+  const agent = new MidlineAgent({ apiKey: "ak_x", endpoint: "http://api.usemidline.com", onError });
+  assert.equal(agent.active, false);
+  assert.match(messages[0], /cleartext/);
+});
+
+test("agent without an API key stays off and says so once", () => {
+  const { messages, onError } = diagnostics();
+  const previous = process.env.MIDLINE_API_KEY;
+  delete process.env.MIDLINE_API_KEY;
+  const agent = new MidlineAgent({ onError });
+  assert.equal(agent.active, false);
+  agent.addEvent({ type: "request", path: "/" });
+  assert.equal(agent.queued, 0);
+  assert.equal(messages.length, 1);
+  if (previous !== undefined) process.env.MIDLINE_API_KEY = previous;
+});
+
+test("custom CA: appended to the default trust store, bad input fails loudly", needsOpenssl, () => {
+  const extra = loadCa(certs.ca, "ca");
+  const store = trustStore(extra);
+  assert.ok(store.length > tls.rootCertificates.length, "public roots are kept");
+  assert.equal(trustStore(undefined), undefined, "no CA means Node's defaults, untouched");
+  assert.deepEqual(loadCa(certs.caPath, "ca")[0].toString(), certs.ca, "a file path works");
+  assert.throws(() => loadCa("/nope/ca.pem", "ca"), /cannot read CA file/);
+  assert.throws(() => loadCa("-----BEGIN CERTIFICATE-----\ngarbage\n-----END CERTIFICATE-----", "ca"), /not a parseable/);
+});
+
+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 { messages, onError } = diagnostics();
+  const agent = agentFor(collector.url, { onError });
+  try {
+    agent.addEvent({ type: "request", path: "/hello", method: "GET", statusCode: 200 });
+    await agent.flush();
+
+    assert.equal(collector.requests.length, 0, "nothing was sent over an unverified connection");
+    assert.equal(agent.queued, 1, "the event is kept for retry");
+    assert.equal(agent.active, true, "a TLS fault does not permanently disable the agent");
+    assert.equal(messages.length, 1);
+    assert.match(messages[0], /DEPTH_ZERO_SELF_SIGNED_CERT/);
+    assert.match(messages[0], /verification stays on/);
+  } finally {
+    agent.close();
+    await collector.close();
+  }
+});
+
+test("TLS: a private CA passed via `ca` is trusted for the Midline server", needsOpenssl, async () => {
+  const collector = await startCollector({ 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 {
+    agent.close();
+    await collector.close();
+  }
+});
+
+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 { messages, onError } = diagnostics();
+  const agent = agentFor(collector.url, { ca: certs.ca, onError });
+  try {
+    agent.addEvent({ type: "request", path: "/hello" });
+    await agent.flush();
+    assert.equal(collector.requests.length, 0);
+    assert.match(messages[0], /ERR_TLS_CERT_ALTNAME_INVALID/);
+  } finally {
+    agent.close();
+    await collector.close();
+  }
+});
+
+test("MIDLINE_CUSTOM_CA (file path) is honoured", needsOpenssl, async () => {
+  const collector = await startCollector({ tls: certs.trusted });
+  process.env.MIDLINE_CUSTOM_CA = certs.caPath;
+  const agent = agentFor(collector.url);
+  try {
+    agent.addEvent({ type: "request", path: "/env-ca" });
+    await agent.flush();
+    assert.equal(collector.requests.length, 1);
+  } finally {
+    delete process.env.MIDLINE_CUSTOM_CA;
+    agent.close();
+    await collector.close();
+  }
+});
+
+test("wire format stays inside the long-standing ingest schema", async () => {
+  const collector = await startCollector();
+  const agent = agentFor(collector.url, { environment: "test", release: "v1" });
+  try {
+    agent.addEvent({
+      type: "error",
+      path: "/charges?token=abc123",
+      method: "post",
+      statusCode: 502,
+      message: "upstream said Bearer abcdefghijklmnop",
+      stack: "Error: boom\n    at x",
+      requestId: "req-1",
+      correlationId: "corr-1",
+    });
+    await agent.flush();
+
+    const [event] = collector.events();
+    const allowed = new Set([
+      "apiKey", "eventType", "severity", "category", "route", "method", "statusCode", "responseTime", "payload",
+      "timestamp", "ip", "userAgent", "metadata", "environment", "service", "host", "region", "traceId", "spanId",
+      "threatDetected", "ruleId", "release",
+    ]);
+    for (const key of Object.keys(event)) {
+      assert.ok(allowed.has(key), `unexpected top-level field ${key} would be rejected by older servers`);
+    }
+    assert.equal(event.route, "/charges", "query strings never go in the route");
+    assert.equal(event.method, "POST");
+    assert.equal(event.eventType, "error");
+    assert.equal(event.payload.error, "upstream said Bearer [REDACTED]");
+    assert.equal(event.metadata.requestId, "req-1");
+    assert.equal(event.metadata.correlationId, "corr-1");
+    assert.equal(event.environment, "test");
+  } finally {
+    agent.close();
+    await collector.close();
+  }
+});
+
+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" } }),
+  });
+  const { messages, onError } = diagnostics();
+  const agent = agentFor(collector.url, { onError });
+  try {
+    agent.addEvent({ type: "request", path: "/a" });
+    agent.addEvent({ type: "request", path: "/b" });
+    await agent.flush();
+    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 } }));
+    await agent.flush();
+    assert.equal(agent.queued, 0);
+    assert.match(messages.at(-1), /recovered/);
+  } finally {
+    agent.close();
+    await collector.close();
+  }
+});
+
+test("401 turns the agent off instead of retrying forever", async () => {
+  const collector = await startCollector({ respond: () => ({ status: 401, body: { message: "Invalid API key" } }) });
+  const { onError } = diagnostics();
+  const agent = agentFor(collector.url, { onError });
+  try {
+    agent.addEvent({ type: "request", path: "/a" });
+    await agent.flush();
+    assert.equal(agent.active, false);
+    agent.addEvent({ type: "request", path: "/b" });
+    assert.equal(agent.queued, 0);
+  } finally {
+    agent.close();
+    await collector.close();
+  }
+});
+
+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 } }) });
+  const { onError } = diagnostics();
+  const agent = agentFor(collector.url, { onError });
+  try {
+    agent.addEvent({ type: "request", path: "/a" });
+    await agent.flush();
+    assert.equal(agent.active, false);
+  } finally {
+    agent.close();
+    await collector.close();
+  }
+});
+
+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;
+      if (events.some((event) => event.route === "/bad")) {
+        return { status: 400, body: { message: ["route must be shorter"] } };
+      }
+      return { status: 201, body: { success: events.length, failed: 0 } };
+    },
+  });
+  const { messages, onError } = diagnostics();
+  const agent = agentFor(collector.url, { onError });
+  try {
+    agent.addEvent({ type: "request", path: "/ok-1" });
+    agent.addEvent({ type: "request", path: "/bad" });
+    agent.addEvent({ type: "request", path: "/ok-2" });
+    await agent.flush();
+
+    const accepted = collector.requests
+      .filter((request) => !request.body.events.some((event) => event.route === "/bad"))
+      .flatMap((request) => request.body.events.map((event) => event.route));
+    assert.deepEqual(accepted, ["/ok-1", "/ok-2"]);
+    assert.equal(agent.queued, 0);
+    assert.match(messages.join("\n"), /route must be shorter/);
+  } finally {
+    agent.close();
+    await collector.close();
+  }
+});
+
+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 } },
+  });
+  const agent = agentFor(collector.url, { onError: () => {} });
+  try {
+    for (let i = 0; i < 4; i++) agent.addEvent({ type: "request", path: `/e${i}` });
+    await agent.flush();
+    assert.equal(agent.queued, 0);
+    const accepted = collector.requests.filter((request) => request.body.events.length === 1);
+    assert.deepEqual(accepted.map((request) => request.body.events[0].route), ["/e0", "/e1", "/e2", "/e3"]);
+  } finally {
+    agent.close();
+    await collector.close();
+  }
+});
+
+test("unreachable Midline server: bounded queue, oldest dropped, nothing thrown", async () => {
+  const port = await closedPort();
+  const { messages, onError } = diagnostics();
+  const agent = agentFor(`http://127.0.0.1:${port}`, { onError, maxQueueSize: 3 });
+  try {
+    for (let i = 0; i < 10; i++) {
+      assert.doesNotThrow(() => agent.addEvent({ type: "request", path: `/e${i}` }));
+    }
+    assert.equal(agent.queued, 3);
+    await agent.flush();
+    await agent.flush();
+    assert.equal(agent.queued, 3);
+    assert.equal(messages.filter((message) => /ECONNREFUSED|refused/.test(message)).length, 1, "one line per distinct fault");
+  } finally {
+    agent.close();
+  }
+});
+
+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));
+  const { messages, onError } = diagnostics();
+  const agent = agentFor(`http://127.0.0.1:${server.address().port}`, { onError, timeoutMs: 200 });
+  try {
+    agent.addEvent({ type: "request", path: "/slow" });
+    const started = Date.now();
+    await agent.flush();
+    assert.ok(Date.now() - started < 1500);
+    assert.equal(agent.queued, 1);
+    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));
+  }
+});
+
+test("oversized events lose their captured bodies before they are dropped", async () => {
+  const collector = await startCollector();
+  const agent = agentFor(collector.url, { maxEventBytes: 2048 });
+  try {
+    agent.addEvent({
+      type: "request",
+      path: "/big",
+      response: { body: "x".repeat(10_000) },
+    });
+    await agent.flush();
+    const [event] = collector.events();
+    assert.ok(event, "event still delivered");
+    assert.equal(event.payload.response.body, undefined);
+    assert.equal(event.payload.response.omitted, "event size limit");
+  } finally {
+    agent.close();
+    await collector.close();
+  }
+});
+
+test("static facade keeps working for existing integrations", async () => {
+  const collector = await startCollector();
+  try {
+    const agent = MidlineAgent.init({ apiKey: "ak_static", endpoint: collector.url, flushIntervalMs: 60_000 });
+    assert.equal(MidlineAgent.current, agent);
+    MidlineAgent.addEvent({ type: "request", path: "/static" });
+    await MidlineAgent.flush();
+    assert.equal(collector.events()[0].route, "/static");
+    await MidlineAgent.shutdown(500);
+    assert.equal(agent.active, false);
+  } finally {
+    await collector.close();
+  }
+});

package/test/console.test.js

@@ -0,0 +1,182 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const { MidlineAgent } = require("../dist");
+const { startCollector, diagnostics } = require("./helpers");
+
+function agentFor(endpoint, extra = {}) {
+  return new MidlineAgent({
+    apiKey: "ak_test_key",
+    serviceName: "console-test",
+    endpoint,
+    flushIntervalMs: 60_000,
+    timeoutMs: 2000,
+    connectTimeoutMs: 1000,
+    captureConsole: true,
+    ...extra,
+  });
+}
+
+/**
+ * Records every chunk that reaches the streams, then passes it on. Installed before
+ * the agent, so it sits underneath the agent's wrapper where the terminal would be.
+ */
+function recordStreams() {
+  const originals = { stdout: process.stdout.write, stderr: process.stderr.write };
+  const written = { stdout: [], stderr: [] };
+  const recorders = {};
+  for (const name of ["stdout", "stderr"]) {
+    recorders[name] = function (chunk, ...rest) {
+      written[name].push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+      return originals[name].call(this, chunk, ...rest);
+    };
+    process[name].write = recorders[name];
+  }
+  return {
+    written,
+    recorders,
+    restore: () => {
+      process.stdout.write = originals.stdout;
+      process.stderr.write = originals.stderr;
+    },
+  };
+}
+
+const consoleEvents = (collector) => collector.events().filter((event) => event.eventType === "console");
+
+test("console capture: printed lines become console events and the output itself is untouched", async () => {
+  const streams = recordStreams();
+  const collector = await startCollector();
+  const agent = agentFor(collector.url);
+  try {
+    const coloured = "\x1b[32m[Nest] 4242  - LOG [NestApplication] Nest application successfully started\x1b[39m\n";
+    process.stdout.write(coloured);
+    console.log("hello world");
+    process.stdout.write("written in ");
+    process.stdout.write("two pieces\n");
+    process.stderr.write("[Nest] 4242  - ERROR [ExceptionHandler] database unreachable\n");
+    console.log("connecting with password=hunter2");
+    process.stdout.write("\n   \n");
+    await agent.flush();
+
+    const events = consoleEvents(collector);
+    const byMessage = new Map(events.map((event) => [event.payload.message, event]));
+
+    const started = byMessage.get("[Nest] 4242  - LOG [NestApplication] Nest application successfully started");
+    assert.ok(started, "colour codes are stripped");
+    assert.equal(started.route, "stdout");
+    assert.equal(started.severity, "low");
+    assert.equal(started.method, undefined, "a printed line is not dressed up as a request");
+    assert.equal(started.statusCode, undefined);
+    assert.equal(started.responseTime, undefined);
+    assert.equal(started.metadata.integrationType, "console");
+
+    assert.ok(byMessage.has("hello world"));
+    assert.ok(byMessage.has("written in two pieces"), "a line written in chunks is one event");
+
+    const failure = byMessage.get("[Nest] 4242  - ERROR [ExceptionHandler] database unreachable");
+    assert.ok(failure);
+    assert.equal(failure.route, "stderr");
+    assert.equal(failure.severity, "high");
+
+    assert.ok(byMessage.has("connecting with password=[REDACTED]"));
+    assert.ok(!events.some((event) => event.payload.message.includes("hunter2")));
+    assert.ok(!events.some((event) => !event.payload.message.trim()), "blank lines are skipped");
+
+    assert.ok(streams.written.stdout.includes(coloured), "the terminal still gets the original bytes");
+    assert.ok(streams.written.stdout.includes("connecting with password=hunter2\n"), "redaction applies to what's sent, not what's printed");
+  } finally {
+    agent.close();
+    streams.restore();
+    await collector.close();
+  }
+});
+
+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" } }) });
+  // No onError: the agent's diagnostics go to the console, where capture could see them.
+  const agent = agentFor(collector.url);
+  try {
+    assert.notEqual(process.stdout.write, streams.recorders.stdout, "capture wraps stdout");
+    console.log("before the outage");
+    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 } }));
+    await agent.flush();
+    const messages = consoleEvents(collector).map((event) => event.payload.message);
+    assert.ok(messages.includes("before the outage"));
+    assert.ok(!messages.some((message) => message.includes("midline:")), "diagnostics never become events");
+
+    agent.close();
+    assert.equal(process.stdout.write, streams.recorders.stdout);
+    assert.equal(process.stderr.write, streams.recorders.stderr);
+  } finally {
+    agent.close();
+    streams.restore();
+    await collector.close();
+  }
+});
+
+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;
+      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"] },
+        };
+      }
+      return { status: 201, body: { success: events.length, failed: 0 } };
+    },
+  });
+  const { messages, onError } = diagnostics();
+  const agent = agentFor(collector.url, { onError });
+  try {
+    agent.addEvent({ type: "request", path: "/orders" });
+    console.log("server started");
+    console.log("second line");
+    await agent.flush();
+
+    const accepted = collector.requests
+      .filter((request) => !request.body.events.some((event) => event.eventType === "console"))
+      .flatMap((request) => request.body.events.map((event) => event.route));
+    assert.deepEqual(accepted, ["/orders"]);
+    assert.equal(agent.queued, 0);
+    assert.equal(agent.active, true, "only console capture stops");
+    assert.match(messages.join("\n"), /console capture is off/);
+    assert.equal(process.stdout.write, streams.recorders.stdout, "the stream wrapper is gone");
+
+    const refused = collector.requests.filter((request) => request.body.events.some((event) => event.eventType === "console"));
+    assert.equal(refused.length, 2, "the batch, then one console line on its own; the rest are not sent");
+  } finally {
+    agent.close();
+    streams.restore();
+    await collector.close();
+  }
+});
+
+test("console capture is off unless asked for, and MIDLINE_CAPTURE_CONSOLE turns it on", () => {
+  const before = process.stdout.write;
+  const settings = { apiKey: "ak_test_key", endpoint: "http://127.0.0.1:9", flushIntervalMs: 60_000 };
+
+  const off = new MidlineAgent(settings);
+  assert.equal(process.stdout.write, before);
+  off.close();
+
+  const previous = process.env.MIDLINE_CAPTURE_CONSOLE;
+  process.env.MIDLINE_CAPTURE_CONSOLE = "true";
+  const on = new MidlineAgent(settings);
+  try {
+    assert.notEqual(process.stdout.write, before);
+  } finally {
+    on.close();
+    if (previous === undefined) delete process.env.MIDLINE_CAPTURE_CONSOLE;
+    else process.env.MIDLINE_CAPTURE_CONSOLE = previous;
+  }
+  assert.equal(process.stdout.write, before);
+});

package/test/helpers.js

@@ -0,0 +1,151 @@
+"use strict";
+
+const { execFileSync } = require("child_process");
+const fs = require("fs");
+const http = require("http");
+const https = require("https");
+const os = require("os");
+const path = require("path");
+
+/**
+ * Mints a throwaway CA, a leaf signed by it for localhost/127.0.0.1, a leaf signed
+ * by it for the wrong hostname, and a self-signed leaf. Nothing is committed to the
+ * repo; the directory is removed when the process exits.
+ */
+function makeCerts() {
+  try {
+    execFileSync("openssl", ["version"], { stdio: "ignore" });
+  } catch {
+    return null;
+  }
+
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "midline-agent-test-"));
+  process.on("exit", () => fs.rmSync(dir, { recursive: true, force: true }));
+  const run = (args) => execFileSync("openssl", args, { cwd: dir, stdio: "pipe" });
+  const read = (name) => fs.readFileSync(path.join(dir, name), "utf8");
+
+  run(["req", "-x509", "-newkey", "rsa:2048", "-nodes", "-keyout", "ca.key", "-out", "ca.pem", "-days", "2", "-subj", "/CN=Midline Test CA"]);
+
+  const leaf = (name, san) => {
+    fs.writeFileSync(path.join(dir, `${name}.ext`), `subjectAltName=${san}\n`);
+    run(["req", "-newkey", "rsa:2048", "-nodes", "-keyout", `${name}.key`, "-out", `${name}.csr`, "-subj", `/CN=${name}`]);
+    run(["x509", "-req", "-in", `${name}.csr`, "-CA", "ca.pem", "-CAkey", "ca.key", "-CAcreateserial", "-out", `${name}.pem`, "-days", "2", "-extfile", `${name}.ext`]);
+    return { key: read(`${name}.key`), cert: read(`${name}.pem`) };
+  };
+
+  run(["req", "-x509", "-newkey", "rsa:2048", "-nodes", "-keyout", "self.key", "-out", "self.pem", "-days", "2", "-subj", "/CN=localhost"]);
+
+  return {
+    dir,
+    ca: read("ca.pem"),
+    caPath: path.join(dir, "ca.pem"),
+    trusted: leaf("localhost", "DNS:localhost,IP:127.0.0.1"),
+    wrongHost: leaf("wrong", "DNS:wrong.example"),
+    selfSigned: { key: read("self.key"), cert: read("self.pem") },
+  };
+}
+
+/** A fake Midline server that records what it receives and answers with `respond`. */
+async function startCollector({ tls, respond } = {}) {
+  const requests = [];
+  let responder = respond || (() => ({ status: 201, body: { success: 1, failed: 0 } }));
+
+  const handler = (req, res) => {
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => {
+      const raw = Buffer.concat(chunks).toString("utf8");
+      let body;
+      try {
+        body = JSON.parse(raw);
+      } catch {
+        body = raw;
+      }
+      const record = { method: req.method, url: req.url, headers: req.headers, body };
+      requests.push(record);
+      const { status, body: responseBody, headers } = responder(record, requests.length);
+      res.writeHead(status, { "content-type": "application/json", ...(headers || {}) });
+      res.end(responseBody === undefined ? "" : JSON.stringify(responseBody));
+    });
+  };
+
+  const server = tls ? https.createServer(tls, handler) : http.createServer(handler);
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address();
+
+  return {
+    url: `${tls ? "https" : "http"}://${tls ? "localhost" : "127.0.0.1"}:${port}`,
+    ipUrl: `${tls ? "https" : "http"}://127.0.0.1:${port}`,
+    port,
+    requests,
+    events: () => requests.flatMap((request) => (request.body && request.body.events) || []),
+    setResponder: (fn) => {
+      responder = fn;
+    },
+    close: () =>
+      new Promise((resolve) => {
+        server.closeAllConnections?.();
+        server.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);
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  return {
+    server,
+    port: server.address().port,
+    close: () =>
+      new Promise((resolve) => {
+        server.closeAllConnections?.();
+        server.close(() => resolve());
+      }),
+  };
+}
+
+function request(url, { method = "GET", headers = {}, body } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(url, { method, headers, agent: false }, (res) => {
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => {
+        const text = Buffer.concat(chunks).toString("utf8");
+        let json;
+        try {
+          json = JSON.parse(text);
+        } catch {
+          json = undefined;
+        }
+        resolve({ status: res.statusCode, headers: res.headers, text, json });
+      });
+    });
+    req.on("error", reject);
+    if (body !== undefined) req.write(body);
+    req.end();
+  });
+}
+
+/** A port that was free a moment ago and has nothing listening on it now. */
+async function closedPort() {
+  const { port, close } = await listen(() => {});
+  await close();
+  return port;
+}
+
+function diagnostics() {
+  const messages = [];
+  return { messages, onError: (message) => messages.push(message) };
+}
+
+async function waitFor(predicate, timeoutMs = 3000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await predicate()) return true;
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+  return false;
+}
+
+module.exports = { makeCerts, startCollector, listen, request, closedPort, diagnostics, waitFor };