midline-agent 0.1.9 → 0.3.0

package/dist/agent.d.ts

@@ -1,10 +1,122 @@
+import { ResolvedCapture } from "./config";
+import type { RequestContext } from "./context";
 import { MidlineConfig, MidlineEvent } from "./types";
+export declare const SDK_VERSION: 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 and console 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 declare class MidlineAgent {
-    private static config;
-    private static queue;
-    private static timer;
-    static init(config: MidlineConfig): void;
+    private static defaultAgent;
+    /** Creates the process-wide agent used by `midlineMiddleware()` and the static helpers. */
+    static init(config?: MidlineConfig): MidlineAgent;
+    static get current(): MidlineAgent | null;
     static addEvent(event: MidlineEvent): void;
-    private static transformEvent;
-    private static startQueue;
+    static flush(): Promise<void>;
+    static shutdown(timeoutMs?: number): Promise<void>;
+    private readonly config;
+    private readonly redactor;
+    private readonly transport;
+    private readonly onErrorHook?;
+    private readonly debugLogs;
+    private queue;
+    private queueBytes;
+    private timer;
+    private drainPromise;
+    private failures;
+    private retryAfter;
+    private stopped;
+    private lastNotice;
+    private dropped;
+    private maxRequestBytes;
+    private batchLimit;
+    private consoleCapture;
+    private consoleTokens;
+    private consoleRefilledAt;
+    /** The server refused a console event: it predates them, so no more are sent. */
+    private consoleUnsupported;
+    constructor(config?: MidlineConfig);
+    /** False when the agent is off: no key, bad config, disabled, rejected key, or closed. */
+    get active(): boolean;
+    get capture(): ResolvedCapture | null;
+    get queued(): number;
+    addEvent(event: MidlineEvent): void;
+    /** Records one HTTP exchange. Captured parts are redacted here, before queueing. */
+    recordHttp(exchange: HttpExchange): void;
+    private recordConsole;
+    private takeConsoleToken;
+    /** Sends whatever is buffered now, ignoring backoff, and keeps the process alive until done. */
+    flush(): Promise<void>;
+    /** Flushes with a deadline, then closes. For graceful shutdown. */
+    shutdown(timeoutMs?: number): Promise<void>;
+    /** Stops the timer, drops the buffer and releases sockets. Safe to call more than once. */
+    close(): void;
+    private captureMessage;
+    private redactManualMessage;
+    /**
+     * 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;
+    private enqueue;
+    /** Oldest events go first — during an outage the most recent minute is worth more than the first. */
+    private trimQueue;
+    private requeue;
+    private takeBatch;
+    private drain;
+    private runDrain;
+    /** Returns false if delivery should stop for this drain. */
+    private sendIndividually;
+    private send;
+    /**
+     * True when a rejected event is a console line the server has no event type for,
+     * i.e. the server predates console capture. Capture switches itself off rather
+     * than paying a refused request for every line printed from then on.
+     */
+    private refusedConsole;
+    /** One line per distinct fault, not one per failed event. */
+    private report;
+    private describe;
+    private onSuccess;
+    private onFailure;
+    /** Unrecoverable configuration problem: go quiet instead of looping forever. */
+    private disable;
+    private log;
 }