midline-agent 0.1.9 → 0.3.0

package/dist/errorHandler.js

@@ -3,18 +3,38 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.midlineErrorHandler = midlineErrorHandler;
 const agent_1 = require("./agent");
 const breadcrumbs_1 = require("./breadcrumbs");
-function midlineErrorHandler() {
-    return (err, req, res, next) => {
-        agent_1.MidlineAgent.addEvent({
-            type: "error",
-            timestamp: new Date().toISOString(),
-            path: req.path,
-            method: req.method,
-            statusCode: err.status || 500,
-            message: err.message,
-            stack: err.stack,
-            breadcrumbs: (0, breadcrumbs_1.getBreadcrumbs)(),
-        });
+const context_1 = require("./context");
+/**
+ * Express error middleware. Records the error, then passes it on unchanged — it
+ * never sends a response itself. Register it after your routes.
+ */
+function midlineErrorHandler(options = {}) {
+    // Four named parameters: Express recognises error middleware by arity.
+    return function midlineError(err, req, _res, next) {
+        try {
+            const agent = options.agent ?? agent_1.MidlineAgent.current;
+            if (agent?.active) {
+                const context = (0, context_1.getRequestContext)(req);
+                const status = Number(err?.status ?? err?.statusCode);
+                agent.addEvent({
+                    type: "error",
+                    path: req.originalUrl ?? req.url ?? "/",
+                    method: req.method,
+                    statusCode: Number.isInteger(status) && status >= 400 && status <= 599 ? status : 500,
+                    message: typeof err?.message === "string" ? err.message : String(err),
+                    stack: typeof err?.stack === "string" ? err.stack : undefined,
+                    breadcrumbs: (0, breadcrumbs_1.getBreadcrumbs)(),
+                    requestId: context?.requestId,
+                    correlationId: context?.correlationId,
+                    traceId: context?.traceId,
+                    spanId: context?.spanId,
+                    integration: "express",
+                });
+            }
+        }
+        catch {
+            // Reporting must not replace the application's own error handling.
+        }
         next(err);
     };
 }

package/dist/index.d.ts

@@ -1,5 +1,12 @@
-export { MidlineAgent } from "./agent";
+export { MidlineAgent, SDK_VERSION } from "./agent";
 export { midlineMiddleware } from "./middleware";
+export type { MidlineMiddlewareOptions } from "./middleware";
 export { midlineErrorHandler } from "./errorHandler";
+export type { MidlineErrorHandlerOptions } from "./errorHandler";
+export { createMidlineProxy, startMidlineProxy } from "./proxy";
+export type { MidlineProxy, MidlineProxyOptions, StartProxyOptions } from "./proxy";
 export { addBreadcrumb } from "./breadcrumbs";
-export type { Breadcrumb, MidlineConfig, MidlineEvent } from "./types";
+export { getRequestContext } from "./context";
+export type { RequestContext } from "./context";
+export { ConfigError } from "./config";
+export type { Breadcrumb, CaInput, CapturedMessage, CaptureOptions, EventCategory, EventSeverity, EventType, MidlineConfig, MidlineEvent, } from "./types";

package/dist/index.js

@@ -1,11 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.addBreadcrumb = exports.midlineErrorHandler = exports.midlineMiddleware = exports.MidlineAgent = void 0;
+exports.ConfigError = exports.getRequestContext = exports.addBreadcrumb = exports.startMidlineProxy = exports.createMidlineProxy = exports.midlineErrorHandler = exports.midlineMiddleware = exports.SDK_VERSION = exports.MidlineAgent = void 0;
 var agent_1 = require("./agent");
 Object.defineProperty(exports, "MidlineAgent", { enumerable: true, get: function () { return agent_1.MidlineAgent; } });
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return agent_1.SDK_VERSION; } });
 var middleware_1 = require("./middleware");
 Object.defineProperty(exports, "midlineMiddleware", { enumerable: true, get: function () { return middleware_1.midlineMiddleware; } });
 var errorHandler_1 = require("./errorHandler");
 Object.defineProperty(exports, "midlineErrorHandler", { enumerable: true, get: function () { return errorHandler_1.midlineErrorHandler; } });
+var proxy_1 = require("./proxy");
+Object.defineProperty(exports, "createMidlineProxy", { enumerable: true, get: function () { return proxy_1.createMidlineProxy; } });
+Object.defineProperty(exports, "startMidlineProxy", { enumerable: true, get: function () { return proxy_1.startMidlineProxy; } });
 var breadcrumbs_1 = require("./breadcrumbs");
 Object.defineProperty(exports, "addBreadcrumb", { enumerable: true, get: function () { return breadcrumbs_1.addBreadcrumb; } });
+var context_1 = require("./context");
+Object.defineProperty(exports, "getRequestContext", { enumerable: true, get: function () { return context_1.getRequestContext; } });
+var config_1 = require("./config");
+Object.defineProperty(exports, "ConfigError", { enumerable: true, get: function () { return config_1.ConfigError; } });

package/dist/middleware.d.ts

@@ -1,2 +1,19 @@
-import { Request, Response, NextFunction } from "express";
-export declare function midlineMiddleware(): (req: Request, res: Response, next: NextFunction) => void;
+import type { IncomingMessage, ServerResponse } from "http";
+import { MidlineAgent } from "./agent";
+import { CaptureOptions } from "./types";
+export interface MidlineMiddlewareOptions {
+    /** Defaults to the agent created by `MidlineAgent.init()`, looked up per request. */
+    agent?: MidlineAgent;
+    /** Overrides the agent's `capture` settings for requests seen by this middleware. */
+    capture?: CaptureOptions;
+    /** Return true to leave a request out, e.g. health checks. */
+    ignore?: (req: IncomingMessage) => boolean;
+}
+/**
+ * Records every request that passes through. Mount it before your routes.
+ *
+ * It only listens: nothing here reads the request stream, delays `next()`, or
+ * changes the response. Recording happens on `finish`/`close`, after the response
+ * has been handed to the socket.
+ */
+export declare function midlineMiddleware(options?: MidlineMiddlewareOptions): (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;

package/dist/middleware.js

@@ -3,52 +3,103 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.midlineMiddleware = midlineMiddleware;
 const agent_1 = require("./agent");
 const breadcrumbs_1 = require("./breadcrumbs");
-function midlineMiddleware() {
-    return (req, res, next) => {
-        const start = Date.now();
-        let logged = false;
-        const logRequest = () => {
-            if (logged)
-                return;
-            logged = true;
-            const duration = Date.now() - start;
-            const statusCode = res.statusCode || 200;
+const config_1 = require("./config");
+const context_1 = require("./context");
+const tap_1 = require("./tap");
+/**
+ * Records every request that passes through. Mount it before your routes.
+ *
+ * It only listens: nothing here reads the request stream, delays `next()`, or
+ * changes the response. Recording happens on `finish`/`close`, after the response
+ * has been handed to the socket.
+ */
+function midlineMiddleware(options = {}) {
+    const captureOverride = options.capture ? (0, config_1.resolveCapture)(options.capture) : undefined;
+    return function midline(req, res, next) {
+        try {
+            observe(req, res, options, captureOverride);
+        }
+        catch {
+            // Monitoring must never be the reason a request fails.
+        }
+        next();
+    };
+}
+function observe(req, res, options, captureOverride) {
+    const agent = options.agent ?? agent_1.MidlineAgent.current;
+    if (!agent || !agent.active || options.ignore?.(req)) {
+        return;
+    }
+    const capture = captureOverride ?? agent.capture;
+    const context = (0, context_1.createRequestContext)(req.headers);
+    (0, context_1.setRequestContext)(req, context);
+    const started = process.hrtime.bigint();
+    // originalUrl survives router rewrites of req.url; read it now, not at finish.
+    const url = req.originalUrl ?? req.url ?? "/";
+    const responseTap = capture.responseBody ? tapResponse(res, capture.maxBodyBytes) : undefined;
+    let recorded = false;
+    const record = () => {
+        if (recorded)
+            return;
+        recorded = true;
+        try {
+            const aborted = !res.writableFinished;
+            const statusCode = aborted && !res.headersSent ? 499 : res.statusCode;
+            const routePath = req.route?.path;
+            const encoding = (0, tap_1.headerValue)(res.getHeader("content-encoding"));
             (0, breadcrumbs_1.addBreadcrumb)({
                 type: "http",
-                message: `${req.method} ${req.path} -> ${statusCode}`,
+                message: `${req.method} ${url.split("?")[0]} -> ${statusCode}`,
                 timestamp: new Date().toISOString(),
             });
-            agent_1.MidlineAgent.addEvent({
-                type: "request",
-                timestamp: new Date().toISOString(),
-                path: req.path,
+            agent.recordHttp({
+                integration: req.originalUrl !== undefined ? "express" : "node-http",
+                context,
                 method: req.method,
-                statusCode: statusCode,
-                duration,
-                ip: req.ip || req.socket.remoteAddress,
-                userAgent: req.headers["user-agent"]
+                url,
+                statusCode,
+                durationMs: Number(process.hrtime.bigint() - started) / 1e6,
+                ip: req.ip ?? req.socket?.remoteAddress,
+                userAgent: (0, tap_1.headerValue)(req.headers["user-agent"]),
+                routeTemplate: typeof routePath === "string" ? `${req.baseUrl ?? ""}${routePath}` : undefined,
+                aborted,
+                capture,
+                request: {
+                    headers: capture.headers ? req.headers : undefined,
+                    contentType: (0, tap_1.headerValue)(req.headers["content-type"]),
+                    // Whatever a body parser already produced. The raw stream is never read here.
+                    body: capture.requestBody ? req.body : undefined,
+                },
+                response: {
+                    headers: capture.headers ? res.getHeaders() : undefined,
+                    contentType: (0, tap_1.headerValue)(res.getHeader("content-type")),
+                    body: responseTap && !(0, tap_1.isCompressed)(encoding) ? responseTap.body : undefined,
+                    bodyBytes: responseTap?.bytes,
+                    truncated: responseTap?.truncated,
+                },
             });
-        };
-        // Override multiple response methods to ensure we catch all responses
-        const originalSend = res.send.bind(res);
-        const originalJson = res.json.bind(res);
-        const originalEnd = res.end.bind(res);
-        res.send = function (body) {
-            logRequest();
-            return originalSend(body);
-        };
-        res.json = function (body) {
-            logRequest();
-            return originalJson(body);
-        };
-        res.end = function (chunk, encoding) {
-            logRequest();
-            return originalEnd(chunk, encoding);
-        };
-        // Also listen for the 'finish' event as a fallback
-        res.once('finish', () => {
-            logRequest();
-        });
-        next();
+        }
+        catch {
+            // See above.
+        }
+    };
+    res.once("finish", record);
+    res.once("close", record);
+}
+/** Wraps write/end with every argument passed through untouched, callbacks included. */
+function tapResponse(res, limit) {
+    const tap = new tap_1.BodyTap(limit);
+    const write = res.write;
+    const end = res.end;
+    res.write = function (...args) {
+        tap.push(args[0], typeof args[1] === "string" ? args[1] : undefined);
+        return write.apply(this, args);
+    };
+    res.end = function (...args) {
+        if (typeof args[0] !== "function") {
+            tap.push(args[0], typeof args[1] === "string" ? args[1] : undefined);
+        }
+        return end.apply(this, args);
     };
+    return tap;
 }

package/dist/proxy.d.ts

@@ -0,0 +1,70 @@
+import * as http from "http";
+import { MidlineAgent } from "./agent";
+import { CaInput, CaptureOptions, MidlineConfig } from "./types";
+export interface MidlineProxyOptions {
+    /**
+     * The destination API — the thing being monitored. `http://localhost:4000`,
+     * `https://staging.example.com`, `https://api.example.com`. Only its origin and
+     * path prefix are used; clients can never steer a request to another host.
+     * Env fallback: `TARGET_API_URL`.
+     */
+    target?: string;
+    /**
+     * Extra CAs to trust for the destination only (a private/internal CA). Added to
+     * the default trust store; verification is never switched off. Independent of
+     * the Midline server's `ca`. Env fallback: `TARGET_API_CA` (PEM or file path).
+     */
+    targetCa?: CaInput;
+    /** Time allowed for the destination to start responding, in ms. Default 30000. Env: `TARGET_API_TIMEOUT_MS`. */
+    timeoutMs?: number;
+    /** Time allowed to connect to the destination, in ms. Default 5000. */
+    connectTimeoutMs?: number;
+    /**
+     * Retries for requests that never reached the destination (refused, reset, DNS,
+     * connect timeout). Only GET, HEAD and OPTIONS without a body are retried — a
+     * write might have been applied. Default 0. Env: `TARGET_API_RETRIES`.
+     */
+    retries?: number;
+    /** Requests with a larger body get 413. Default 10 MiB. */
+    maxRequestBodyBytes?: number;
+    /** Send the client's Host header upstream instead of the destination's. Default false. */
+    preserveHost?: boolean;
+    /**
+     * Trust `X-Forwarded-*` from the client, e.g. when this proxy itself sits behind a
+     * load balancer. Default false, so clients cannot spoof their address.
+     */
+    trustForwardedHeaders?: boolean;
+    /** Overrides the agent's capture settings for proxied traffic. */
+    capture?: CaptureOptions;
+    /** Where events go. Defaults to `MidlineAgent.current`. Traffic is forwarded either way. */
+    agent?: MidlineAgent;
+    /** Receives proxy diagnostics. Defaults to console.warn. */
+    onError?: (message: string) => void;
+}
+export interface MidlineProxy {
+    (req: http.IncomingMessage, res: http.ServerResponse): void;
+    readonly target: URL;
+    /** Releases pooled upstream connections. */
+    close(): void;
+}
+export declare function resolveTarget(target: string | undefined): URL;
+/**
+ * A reverse proxy for the destination API: clients call it, it forwards to
+ * `target`, and every exchange is reported to Midline out of band.
+ *
+ * The Midline server is never in the request path. If it is down, slow or
+ * misconfigured, traffic keeps flowing and only telemetry is buffered.
+ */
+export declare function createMidlineProxy(options?: MidlineProxyOptions): MidlineProxy;
+export interface StartProxyOptions extends MidlineProxyOptions {
+    /** Default 8080. Env: `MIDLINE_PROXY_PORT`. */
+    port?: number;
+    /** Default 127.0.0.1 — set 0.0.0.0 explicitly to accept traffic from other machines. Env: `MIDLINE_PROXY_HOST`. */
+    host?: string;
+    /** Used to create an agent when `agent` isn't passed and none is initialised. */
+    midline?: MidlineConfig;
+}
+export declare function startMidlineProxy(options?: StartProxyOptions): Promise<http.Server & {
+    proxy: MidlineProxy;
+}>;
+export declare function proxyAddress(server: http.Server): string;