midline-agent 0.3.0 → 0.4.1

package/src/agent.ts

@@ -2,7 +2,7 @@ import { ConfigError, ResolvedCapture, ResolvedConfig, envFlag, resolveConfig }
 import { ConsoleCapture, ConsoleLevel, ConsoleLine, MAX_LINE_CHARS, withoutConsoleCapture } from "./console";
 import type { RequestContext } from "./context";
 import { Redactor } from "./redact";
-import { Transport } from "./transport";
+import { IngestAck, SocketTransport } from "./socket-transport";
 import { CapturedMessage, EventCategory, EventSeverity, MidlineConfig, MidlineEvent } from "./types";
 
 export const SDK_VERSION: string = (() => {
@@ -117,7 +117,7 @@ export class MidlineAgent {
 
   private readonly config: ResolvedConfig | null = null;
   private readonly redactor: Redactor;
-  private readonly transport: Transport | null = null;
+  private readonly transport: SocketTransport | null = null;
   private readonly onErrorHook?: (message: string) => void;
   private readonly debugLogs: boolean;
 
@@ -165,16 +165,20 @@ export class MidlineAgent {
     }
 
     this.config = resolved;
-    this.transport = new Transport(resolved.ingestUrl, {
+    this.transport = new SocketTransport(resolved.socketOrigin, {
+      apiKey: resolved.apiKey,
       ca: resolved.ca,
       connectTimeoutMs: resolved.connectTimeoutMs,
       timeoutMs: resolved.timeoutMs,
+      reconnectionDelayMs: resolved.flushIntervalMs,
+      reconnectionDelayMaxMs: resolved.maxRetryDelayMs,
+      idleDisconnectMs: Math.max(5 * resolved.flushIntervalMs, 30_000),
       userAgent: `midline-agent/${SDK_VERSION} node/${process.version}`,
     });
 
     this.timer = setInterval(() => {
       this.consoleCapture?.flushPending();
-      void this.drain(false);
+      void this.drain();
     }, resolved.flushIntervalMs);
     // Telemetry must never be the reason a process refuses to exit.
     this.timer.unref?.();
@@ -288,7 +292,15 @@ export class MidlineAgent {
     return true;
   }
 
-  /** Sends whatever is buffered now, ignoring backoff, and keeps the process alive until done. */
+  /**
+   * Sends whatever is buffered now, ignoring backoff.
+   *
+   * The transport's connection is always unref'd (telemetry alone must never
+   * keep an otherwise-idle process alive), so this relies on something else in
+   * the process keeping the event loop open until the await resolves — true for
+   * the overwhelmingly common case (a running server), not guaranteed for a
+   * bare script whose last statement is `await agent.flush()`.
+   */
   async flush(): Promise<void> {
     if (!this.active) return;
     this.consoleCapture?.flushPending(true);
@@ -296,7 +308,7 @@ export class MidlineAgent {
     if (this.drainPromise) {
       await this.drainPromise;
     }
-    await this.drain(true);
+    await this.drain();
   }
 
   /** Flushes with a deadline, then closes. For graceful shutdown. */
@@ -493,23 +505,23 @@ export class MidlineAgent {
     return batch;
   }
 
-  private drain(keepProcessAlive: boolean): Promise<void> {
+  private drain(): 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 = this.runDrain().finally(() => {
       this.drainPromise = null;
     });
     return this.drainPromise;
   }
 
-  private async runDrain(keepProcessAlive: boolean): Promise<void> {
+  private async runDrain(): 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);
+      const outcome = await this.send(batch);
 
       if (outcome.kind === "ok") {
         this.onSuccess();
@@ -530,7 +542,7 @@ export class MidlineAgent {
           this.requeue(batch);
         } else {
           this.dropped += 1;
-          this.report("http-413", "midline: the Midline server rejected an event as too large (HTTP 413); dropped it.");
+          this.report("too-large", "midline: the Midline server rejected an event as too large; dropped it.");
         }
         continue;
       }
@@ -543,7 +555,7 @@ export class MidlineAgent {
         }
         // 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);
+        const isolated = await this.sendIndividually(batch);
         if (!isolated) return;
         continue;
       }
@@ -555,14 +567,14 @@ export class MidlineAgent {
   }
 
   /** Returns false if delivery should stop for this drain. */
-  private async sendIndividually(batch: QueuedEvent[], keepProcessAlive: boolean): Promise<boolean> {
+  private async sendIndividually(batch: QueuedEvent[]): Promise<boolean> {
     for (let index = 0; index < batch.length; index++) {
       if (this.consoleUnsupported && batch[index].wire.eventType === "console") continue;
-      const outcome = await this.send([batch[index]], keepProcessAlive);
+      const outcome = await this.send([batch[index]]);
       if (outcome.kind === "ok") {
         this.onSuccess();
       } else if (outcome.kind === "rejected" || outcome.kind === "tooLarge") {
-        const detail = outcome.kind === "rejected" ? outcome.detail : "HTTP 413";
+        const detail = outcome.kind === "rejected" ? outcome.detail : "too_large";
         if (outcome.kind === "rejected" && this.refusedConsole(batch[index], detail)) continue;
         this.dropped += 1;
         this.report(`rejected:${detail}`, `midline: the Midline server rejected an event (${detail}); dropped it.`);
@@ -578,60 +590,44 @@ export class MidlineAgent {
     return true;
   }
 
-  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;
+  private async send(batch: QueuedEvent[]): Promise<Outcome> {
+    let ack: IngestAck;
     try {
-      result = await this.transport!.post(config.batchUrl, body, { "x-api-key": config.apiKey }, keepProcessAlive);
+      ack = await this.transport!.send(batch.map((item) => item.wire));
     } 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) {
+    if (ack.ok) {
+      // Servers that predate 401-on-bad-key ack ok and count the rejects.
+      if (ack.rejected >= 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.`);
+      if (ack.rejected > 0) {
+        this.dropped += ack.rejected;
+        this.report("partial", `midline: the Midline server rejected ${ack.rejected} of ${batch.length} events.`);
       }
       return { kind: "ok" };
     }
-    if (status === 401 || status === 403) {
+
+    if (ack.code === "unauthorized" || ack.code === "forbidden") {
       this.log(
         "error",
-        `midline: the Midline server rejected the API key (HTTP ${status}). ` +
+        `midline: the Midline server rejected the API key (${ack.code}). ` +
           "Monitoring is now off — retrying wouldn't help. Check apiKey / MIDLINE_API_KEY.",
       );
       return { kind: "stop" };
     }
-    if (status === 413) {
+    if (ack.code === "too_large") {
       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" };
+    if (ack.code === "rate_limited") {
+      this.report("rate_limited", `midline: the Midline server is rate-limiting this project; events are buffered and will be retried.`);
+      return { kind: "retry", retryAfterMs: ack.retryAfterMs };
     }
-    return { kind: "rejected", detail: `HTTP ${status}${serverMessage(result.body)}` };
+    return { kind: "rejected", detail: `${ack.code}: ${ack.message}` };
   }
 
   /**
@@ -666,7 +662,7 @@ export class MidlineAgent {
 
   private describe(err: unknown, inFlight: number): string {
     const config = this.config!;
-    const origin = config.ingestUrl.origin;
+    const origin = config.socketOrigin.origin;
     const code = errorCode(err);
     const buffered = ` ${this.queue.length + inFlight} event(s) buffered; your application is unaffected.`;
 
@@ -687,7 +683,7 @@ export class MidlineAgent {
       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}`;
+      return `midline: cannot resolve ${config.socketOrigin.hostname} (${code}) — check MIDLINE_ENDPOINT and DNS; retrying with backoff.${buffered}`;
     }
     if (code === "ECONNREFUSED") {
       return `midline: ${origin} refused the connection; retrying with backoff.${buffered}`;
@@ -828,26 +824,3 @@ 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;
-}