@traffic-twin/sdk 0.0.0-stage → 0.1.0

package/dist/cjs/capture/body.d.ts

@@ -0,0 +1,11 @@
+export declare class BodyTap {
+    private readonly limit;
+    private chunks;
+    private kept;
+    total: number;
+    ended: boolean;
+    constructor(limit: number);
+    /** Records a chunk (Buffer, Uint8Array or string with encoding). Never throws. */
+    add(chunk: unknown, encoding?: unknown): void;
+    bytes(): Buffer;
+}

package/dist/cjs/capture/body.js

@@ -0,0 +1,73 @@
+"use strict";
+// Body tee (sanitizer.md 9.0): keeps a copy of the first `limit` bytes and counts the rest.
+// Never alters the chunks it sees; copies only what it keeps, once.
+//
+// Every kept chunk is a standalone allocation (its own ArrayBuffer, never a slice of the
+// Buffer pool): the final bytes can then be handed to a worker thread without cloning a
+// whole pool slab. The chunk list is bounded by `limit` bytes; a body made of one chunk
+// (the common case) is returned without any further copy.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BodyTap = void 0;
+class BodyTap {
+    limit;
+    chunks = [];
+    kept = 0;
+    total = 0;
+    ended = false;
+    constructor(limit) {
+        this.limit = limit;
+    }
+    /** Records a chunk (Buffer, Uint8Array or string with encoding). Never throws. */
+    add(chunk, encoding) {
+        try {
+            if (chunk === null || chunk === undefined)
+                return;
+            if (typeof chunk === 'string') {
+                const enc = (typeof encoding === 'string' && Buffer.isEncoding(encoding) ? encoding : 'utf8');
+                const len = Buffer.byteLength(chunk, enc);
+                this.total += len;
+                if (this.kept < this.limit && len > 0) {
+                    const room = this.limit - this.kept;
+                    const b = Buffer.allocUnsafeSlow(len);
+                    b.write(chunk, 0, len, enc);
+                    const take = len > room ? b.subarray(0, room) : b;
+                    this.chunks.push(take);
+                    this.kept += take.length;
+                }
+                return;
+            }
+            if (chunk instanceof Uint8Array) {
+                const len = chunk.byteLength;
+                this.total += len;
+                if (this.kept < this.limit && len > 0) {
+                    const take = Math.min(len, this.limit - this.kept);
+                    // Copy: the app (or Node) may reuse the underlying memory.
+                    const b = Buffer.allocUnsafeSlow(take);
+                    b.set(take === len ? chunk : chunk.subarray(0, take));
+                    this.chunks.push(b);
+                    this.kept += take;
+                }
+            }
+        }
+        catch {
+            // Capturing must never affect the app.
+        }
+    }
+    bytes() {
+        const n = this.chunks.length;
+        if (n === 0)
+            return Buffer.alloc(0);
+        if (n === 1)
+            return this.chunks[0];
+        const b = Buffer.allocUnsafeSlow(this.kept);
+        let o = 0;
+        for (let i = 0; i < n; i++) {
+            const c = this.chunks[i];
+            b.set(c, o);
+            o += c.length;
+        }
+        this.chunks = [b];
+        return b;
+    }
+}
+exports.BodyTap = BodyTap;

package/dist/cjs/capture/common.d.ts

@@ -0,0 +1,75 @@
+import type { Decision, NetError, Sanitizer } from '../sanitizer/sanitizer.js';
+import { ExchangeCtx } from './context.js';
+import type { WireExchange, WireHeaders } from './wire.js';
+/** A finished exchange, converted to sanitizer input lazily (off the request path, possibly in a worker thread). */
+export interface RawExchange {
+    sanitizer: Sanitizer;
+    decision: Decision;
+    wire: WireExchange;
+    dir: 'inbound' | 'outbound';
+    tsMs: number;
+    latencyMs: number;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    status?: number;
+    netError?: NetError;
+    /** Bytes held by this exchange (queue accounting). */
+    heldBytes: number;
+}
+/** What the capture hooks need from the agent. Every method must be cheap and never throw. */
+export interface CaptureHost {
+    /** Current sanitizer when capture is allowed, else null (fast path). */
+    active(): Sanitizer | null;
+    serviceName(): string;
+    /** Header names (lowercase) needed for the inbound sampling decision. */
+    decisionHeaders(): ReadonlySet<string>;
+    /** Whether tt.s may be added to the baggage of a call to this url base (sanitizer.md 12). */
+    mayPropagate(urlBase: string): boolean;
+    /** Whether the policy asks for tt.s on some outbound calls (else unsampled calls need no per-call work). */
+    propagates(): boolean;
+    submit(raw: RawExchange): void;
+    noteSeen(): void;
+    noteSampled(): void;
+    noteOverhead(ns: number): void;
+    noteError(code: string): void;
+}
+/** True while the SDK itself creates a request (exporter, Fleet): such requests are never captured. */
+export declare const internal: {
+    depth: number;
+};
+/** HTTP agents owned by the SDK; requests through them are never captured. */
+export declare const internalAgents: WeakSet<object>;
+export declare function runInternal<T>(fn: () => T): T;
+/** node:http rawHeaders (latin1 strings) to [name, bytes] pairs. */
+export declare function rawPairs(raw: readonly string[] | undefined, only?: ReadonlySet<string>): Array<[string, Buffer]>;
+export declare function rawHeader(raw: readonly string[] | undefined, lower: string): string | undefined;
+/** Parses the serialized header block of an OutgoingMessage (`_header`). */
+export declare function parseHeaderBlock(block: string): Array<[string, Buffer]>;
+/** Headers of an OutgoingMessage (server response or client request) as sent on the wire. */
+export declare function outgoingHeaders(msg: {
+    _header?: unknown;
+    getHeaders?: () => Record<string, unknown>;
+}): Array<[string, Buffer]>;
+/** Headers of an OutgoingMessage in wire form: the serialized block when Node has built it (parsed later), else a flat list. */
+export declare function outgoingHeadersWire(msg: {
+    _header?: unknown;
+    getHeaders?: () => Record<string, unknown>;
+}): WireHeaders;
+/** Splits a request target into raw path and raw query bytes (query undefined without "?"). */
+export declare function splitTarget(target: string): {
+    path: Buffer;
+    query: Buffer | undefined;
+};
+/** Maps a network error to the event enum (event.md). */
+export declare function netErrorOf(err: unknown): NetError;
+/** Trace data for an outbound call, from the inbound context or OpenTelemetry. */
+export declare function outboundTrace(ctx: ExchangeCtx | undefined): {
+    traceId: string;
+    parentSpanId?: string;
+    samplingTraceId?: string;
+};
+/** Monotonic clock in nanoseconds as a double (no BigInt allocation on the request path). */
+export declare function hrNow(): number;
+/** Adds tt.s to a baggage header value without touching the other members. */
+export declare function withTtS(existing: string | undefined, sampled: boolean): string;

package/dist/cjs/capture/common.js

@@ -0,0 +1,180 @@
+"use strict";
+// Shared pieces of the capture hooks.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.internalAgents = exports.internal = void 0;
+exports.runInternal = runInternal;
+exports.rawPairs = rawPairs;
+exports.rawHeader = rawHeader;
+exports.parseHeaderBlock = parseHeaderBlock;
+exports.outgoingHeaders = outgoingHeaders;
+exports.outgoingHeadersWire = outgoingHeadersWire;
+exports.splitTarget = splitTarget;
+exports.netErrorOf = netErrorOf;
+exports.outboundTrace = outboundTrace;
+exports.hrNow = hrNow;
+exports.withTtS = withTtS;
+const context_js_1 = require("./context.js");
+/** True while the SDK itself creates a request (exporter, Fleet): such requests are never captured. */
+exports.internal = { depth: 0 };
+/** HTTP agents owned by the SDK; requests through them are never captured. */
+exports.internalAgents = new WeakSet();
+function runInternal(fn) {
+    exports.internal.depth++;
+    try {
+        return fn();
+    }
+    finally {
+        exports.internal.depth--;
+    }
+}
+const lengthsOf = new WeakMap();
+/** node:http rawHeaders (latin1 strings) to [name, bytes] pairs. */
+function rawPairs(raw, only) {
+    const out = [];
+    if (!raw)
+        return out;
+    let lens;
+    if (only) {
+        lens = lengthsOf.get(only);
+        if (!lens) {
+            lens = new Set();
+            for (const k of only)
+                lens.add(k.length);
+            lengthsOf.set(only, lens);
+        }
+    }
+    for (let i = 0; i + 1 < raw.length; i += 2) {
+        const n = raw[i];
+        // Most headers cannot match by length alone: skip the lowercase copy for them.
+        if (only && (!lens.has(n.length) || !only.has(n.toLowerCase())))
+            continue;
+        out.push([n, Buffer.from(raw[i + 1], 'latin1')]);
+    }
+    return out;
+}
+function rawHeader(raw, lower) {
+    if (!raw)
+        return undefined;
+    for (let i = 0; i + 1 < raw.length; i += 2)
+        if (raw[i].length === lower.length && raw[i].toLowerCase() === lower)
+            return raw[i + 1];
+    return undefined;
+}
+/** Parses the serialized header block of an OutgoingMessage (`_header`). */
+function parseHeaderBlock(block) {
+    const out = [];
+    const lines = block.split('\r\n');
+    for (let i = 1; i < lines.length; i++) {
+        const l = lines[i];
+        if (l === '')
+            continue;
+        const c = l.indexOf(':');
+        if (c <= 0)
+            continue;
+        out.push([l.slice(0, c), Buffer.from(l.slice(c + 1), 'latin1')]);
+    }
+    return out;
+}
+/** Headers of an OutgoingMessage (server response or client request) as sent on the wire. */
+function outgoingHeaders(msg) {
+    if (typeof msg._header === 'string' && msg._header.length > 0)
+        return parseHeaderBlock(msg._header);
+    const out = [];
+    try {
+        const h = msg.getHeaders ? msg.getHeaders() : {};
+        for (const k of Object.keys(h)) {
+            const v = h[k];
+            for (const one of Array.isArray(v) ? v : [v]) {
+                if (one === undefined || one === null)
+                    continue;
+                out.push([k, Buffer.from(String(one), 'latin1')]);
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return out;
+}
+/** Headers of an OutgoingMessage in wire form: the serialized block when Node has built it (parsed later), else a flat list. */
+function outgoingHeadersWire(msg) {
+    if (typeof msg._header === 'string' && msg._header.length > 0)
+        return msg._header;
+    const out = [];
+    try {
+        const h = msg.getHeaders ? msg.getHeaders() : {};
+        for (const k of Object.keys(h)) {
+            const v = h[k];
+            for (const one of Array.isArray(v) ? v : [v]) {
+                if (one === undefined || one === null)
+                    continue;
+                out.push(k, String(one));
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return out;
+}
+/** Splits a request target into raw path and raw query bytes (query undefined without "?"). */
+function splitTarget(target) {
+    let t = target;
+    const abs = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^/?#]*/.exec(t);
+    if (abs)
+        t = t.slice(abs[0].length) || '/';
+    const hash = t.indexOf('#');
+    if (hash >= 0)
+        t = t.slice(0, hash);
+    const q = t.indexOf('?');
+    if (q < 0)
+        return { path: Buffer.from(t, 'latin1'), query: undefined };
+    return { path: Buffer.from(t.slice(0, q), 'latin1'), query: Buffer.from(t.slice(q + 1), 'latin1') };
+}
+/** Maps a network error to the event enum (event.md). */
+function netErrorOf(err) {
+    const e = err;
+    const code = typeof e?.code === 'string' ? e.code : '';
+    if (!code && e?.cause)
+        return netErrorOf(e.cause);
+    if (/TIMEOUT|ETIMEDOUT|ESOCKETTIMEDOUT/.test(code))
+        return 'timeout';
+    if (code === 'ECONNRESET' || code === 'EPIPE' || code === 'UND_ERR_SOCKET' || code === 'ECONNABORTED')
+        return 'reset';
+    if (code === 'ECONNREFUSED')
+        return 'refused';
+    if (code === 'ENOTFOUND' || code === 'EAI_AGAIN' || code === 'EAI_NONAME' || code === 'EAI_FAIL')
+        return 'dns';
+    if (/^ERR_TLS|^ERR_SSL|CERT|UNABLE_TO_VERIFY|SELF_SIGNED|DEPTH_ZERO/.test(code))
+        return 'tls';
+    return 'other';
+}
+/** Trace data for an outbound call, from the inbound context or OpenTelemetry. */
+function outboundTrace(ctx) {
+    if (ctx && !ctx.sampled)
+        return { traceId: '' }; // inherited: not sampled, no ids needed
+    const o = (0, context_js_1.otelActive)();
+    if (ctx) {
+        // Adopt the OpenTelemetry trace id when the inbound request carried none, so the
+        // inbound and outbound events share the app's own trace.
+        if (!ctx.traceKnown && o) {
+            ctx.traceId = o.traceId;
+            ctx.traceKnown = true;
+        }
+        return { traceId: ctx.traceId, parentSpanId: ctx.spanId };
+    }
+    if (o)
+        return { traceId: o.traceId, parentSpanId: o.spanId || undefined, samplingTraceId: o.traceId };
+    return { traceId: (0, context_js_1.newTraceId)() };
+}
+/** Monotonic clock in nanoseconds as a double (no BigInt allocation on the request path). */
+function hrNow() {
+    return performance.now() * 1e6;
+}
+/** Adds tt.s to a baggage header value without touching the other members. */
+function withTtS(existing, sampled) {
+    const member = 'tt.s=' + (sampled ? '1' : '0');
+    if (!existing || existing.trim() === '')
+        return member;
+    return existing + ',' + member;
+}

package/dist/cjs/capture/context.d.ts

@@ -0,0 +1,28 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+export interface ExchangeCtx {
+    sampled: boolean;
+    traceId: string;
+    /** true when traceId came from the request (traceparent) or from OpenTelemetry. */
+    traceKnown: boolean;
+    spanId: string;
+}
+export declare const als: AsyncLocalStorage<ExchangeCtx>;
+/** Context of every unsampled exchange: nothing is recorded for it or for the calls it makes, so one shared frozen object serves. */
+export declare const UNSAMPLED: ExchangeCtx;
+export declare const newTraceId: () => string;
+export declare const newSpanId: () => string;
+/** W3C trace context: returns ids from a traceparent value, or null if invalid. */
+export declare function parseTraceparent(v: string | undefined | null): {
+    traceId: string;
+    spanId: string;
+} | null;
+/**
+ * Loads @opentelemetry/api from the application's dependency tree, if present. Loading the
+ * API package has no side effect; the SDK only calls read-only functions on it.
+ */
+export declare function loadOtelApi(): boolean;
+/** Active OpenTelemetry span context, if the app has one. Never throws. */
+export declare function otelActive(): {
+    traceId: string;
+    spanId: string;
+} | null;

package/dist/cjs/capture/context.js

@@ -0,0 +1,92 @@
+"use strict";
+// Exchange context (event.md 1.1, sanitizer.md 12, ARCHITECTURE 3.2).
+//
+// An AsyncLocalStorage store binds outbound calls to the inbound exchange being served:
+// same trace_id, inherited sampling decision. W3C traceparent is read from the inbound
+// request. If the app uses OpenTelemetry, the active span context is only READ through
+// @opentelemetry/api resolved from the app; this module never registers a provider,
+// propagator or context manager and never injects traceparent.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newSpanId = exports.newTraceId = exports.UNSAMPLED = exports.als = void 0;
+exports.parseTraceparent = parseTraceparent;
+exports.loadOtelApi = loadOtelApi;
+exports.otelActive = otelActive;
+const node_async_hooks_1 = require("node:async_hooks");
+const node_crypto_1 = require("node:crypto");
+const node_module_1 = require("node:module");
+const node_path_1 = require("node:path");
+exports.als = new node_async_hooks_1.AsyncLocalStorage();
+/** Context of every unsampled exchange: nothing is recorded for it or for the calls it makes, so one shared frozen object serves. */
+exports.UNSAMPLED = Object.freeze({ sampled: false, traceId: '', traceKnown: false, spanId: '' });
+// Ids come from a pooled CSPRNG buffer: one system call per 256 ids instead of one per id.
+const pool = Buffer.alloc(4096);
+let poolOff = pool.length;
+function nonZeroHex(bytes) {
+    for (;;) {
+        if (poolOff + bytes > pool.length) {
+            (0, node_crypto_1.randomFillSync)(pool);
+            poolOff = 0;
+        }
+        const h = pool.toString('hex', poolOff, poolOff + bytes);
+        poolOff += bytes;
+        if (!/^0+$/.test(h))
+            return h;
+    }
+}
+const newTraceId = () => nonZeroHex(16);
+exports.newTraceId = newTraceId;
+const newSpanId = () => nonZeroHex(8);
+exports.newSpanId = newSpanId;
+const TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(-.*)?$/;
+/** W3C trace context: returns ids from a traceparent value, or null if invalid. */
+function parseTraceparent(v) {
+    if (typeof v !== 'string')
+        return null;
+    const m = TRACEPARENT.exec(v.trim());
+    if (!m)
+        return null;
+    if (m[1] === 'ff' || (m[1] === '00' && m[5] !== undefined))
+        return null;
+    if (/^0+$/.test(m[2]) || /^0+$/.test(m[3]))
+        return null;
+    return { traceId: m[2], spanId: m[3] };
+}
+let otel;
+/**
+ * Loads @opentelemetry/api from the application's dependency tree, if present. Loading the
+ * API package has no side effect; the SDK only calls read-only functions on it.
+ */
+function loadOtelApi() {
+    if (otel !== undefined)
+        return otel !== null;
+    otel = null;
+    try {
+        const req = (0, node_module_1.createRequire)((0, node_path_1.join)(process.cwd(), '__traffic_twin_resolve__.js'));
+        const mod = req(req.resolve('@opentelemetry/api'));
+        const api = mod.trace ? mod : mod.default;
+        if (api && api.trace && typeof api.trace.getSpanContext === 'function' && api.context)
+            otel = api;
+    }
+    catch {
+        otel = null;
+    }
+    return otel !== null;
+}
+/** Active OpenTelemetry span context, if the app has one. Never throws. */
+function otelActive() {
+    if (!otel)
+        return null;
+    try {
+        const sc = otel.trace.getSpanContext(otel.context.active());
+        if (!sc)
+            return null;
+        if (otel.isSpanContextValid && !otel.isSpanContextValid(sc))
+            return null;
+        if (!/^[0-9a-f]{32}$/.test(sc.traceId) || /^0+$/.test(sc.traceId))
+            return null;
+        return { traceId: sc.traceId, spanId: /^[0-9a-f]{16}$/.test(sc.spanId) ? sc.spanId : '' };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cjs/capture/inbound.d.ts

@@ -0,0 +1,12 @@
+import { BodyTap } from './body.js';
+import { type CaptureHost } from './common.js';
+/** Wraps `push` of an IncomingMessage to tee body bytes (de-chunked by the parser). */
+export declare function tapPush(stream: {
+    push: (chunk: unknown, enc?: unknown) => boolean;
+}, tap: BodyTap): void;
+/** Wraps write/end of an OutgoingMessage to tee body bytes. */
+export declare function tapWrites(msg: {
+    write: (...a: unknown[]) => boolean;
+    end: (...a: unknown[]) => unknown;
+}, tap: BodyTap, onEnd?: () => void): void;
+export declare function installInbound(host: CaptureHost): () => void;

package/dist/cjs/capture/inbound.js

@@ -0,0 +1,195 @@
+"use strict";
+// Inbound capture for node:http / node:https servers through diagnostics_channel
+// (`http.server.request.start`, `http.server.response.finish`). No global patching: the
+// only wrappers are installed on the request/response objects of sampled exchanges, they
+// are synchronous and they never change arguments, return values or timing.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tapPush = tapPush;
+exports.tapWrites = tapWrites;
+exports.installInbound = installInbound;
+const node_diagnostics_channel_1 = __importDefault(require("node:diagnostics_channel"));
+const body_js_1 = require("./body.js");
+const common_js_1 = require("./common.js");
+const context_js_1 = require("./context.js");
+const EMPTY = Buffer.alloc(0);
+const kState = Symbol('traffic-twin.inbound');
+/** Wraps `push` of an IncomingMessage to tee body bytes (de-chunked by the parser). */
+function tapPush(stream, tap) {
+    const orig = stream.push;
+    stream.push = function push(chunk, enc) {
+        if (chunk === null)
+            tap.ended = true;
+        else
+            tap.add(chunk, enc);
+        // eslint-disable-next-line prefer-rest-params
+        return orig.apply(this, arguments);
+    };
+}
+/** Wraps write/end of an OutgoingMessage to tee body bytes. */
+function tapWrites(msg, tap, onEnd) {
+    const ow = msg.write;
+    const oe = msg.end;
+    msg.write = function write(chunk, enc) {
+        if (typeof chunk !== 'function')
+            tap.add(chunk, typeof enc === 'string' ? enc : undefined);
+        // eslint-disable-next-line prefer-rest-params
+        return ow.apply(this, arguments);
+    };
+    msg.end = function end(chunk, enc) {
+        if (typeof chunk !== 'function')
+            tap.add(chunk, typeof enc === 'string' ? enc : undefined);
+        tap.ended = true;
+        if (onEnd) {
+            try {
+                onEnd();
+            }
+            catch {
+                // ignore
+            }
+        }
+        // eslint-disable-next-line prefer-rest-params
+        return oe.apply(this, arguments);
+    };
+}
+function installInbound(host) {
+    const onStart = (message) => {
+        const t = (0, common_js_1.hrNow)();
+        const { request, response } = message;
+        try {
+            start(host, request, response, t);
+        }
+        catch {
+            host.noteError('capture_inbound_start');
+        }
+    };
+    const onFinish = (message) => {
+        const { request, response } = message;
+        // Unsampled exchanges (the vast majority at low rates) carry no state: nothing to do.
+        if (response[kState] === undefined)
+            return;
+        const t = (0, common_js_1.hrNow)();
+        try {
+            finish(host, request, response, t);
+        }
+        catch {
+            host.noteError('capture_inbound_finish');
+        }
+    };
+    node_diagnostics_channel_1.default.subscribe('http.server.request.start', onStart);
+    node_diagnostics_channel_1.default.subscribe('http.server.response.finish', onFinish);
+    return () => {
+        node_diagnostics_channel_1.default.unsubscribe('http.server.request.start', onStart);
+        node_diagnostics_channel_1.default.unsubscribe('http.server.response.finish', onFinish);
+    };
+}
+function start(host, req, res, t) {
+    const san = host.active();
+    if (!san)
+        return;
+    host.noteSeen();
+    const raw = req.rawHeaders;
+    const tph = (0, common_js_1.rawHeader)(raw, 'traceparent');
+    const tp = tph === undefined ? null : (0, context_js_1.parseTraceparent)(tph);
+    const service = host.serviceName();
+    const decision = san.decideRaw(service, raw, tp?.traceId) ?? san.decide({
+        dir: 'inbound',
+        service_name: service,
+        req_headers: (0, common_js_1.rawPairs)(raw, host.decisionHeaders()),
+        trace_id: tp?.traceId,
+    });
+    if (!decision.sampled) {
+        // Nothing is recorded for this exchange or for the calls it makes (their decision is
+        // inherited): no tees, no wrappers, no ids; only the shared "not sampled" context.
+        context_js_1.als.enterWith(context_js_1.UNSAMPLED);
+        host.noteOverhead((0, common_js_1.hrNow)() - t);
+        return;
+    }
+    const ctx = { sampled: true, traceId: tp?.traceId ?? (0, context_js_1.newTraceId)(), traceKnown: !!tp, spanId: (0, context_js_1.newSpanId)() };
+    // Bind the rest of this request's async work (handlers, outbound calls) to ctx.
+    context_js_1.als.enterWith(ctx);
+    host.noteSampled();
+    const limit = san.policy.captureLimit; // max(max_body_bytes, bodies.max_large_body_bytes) + 1 (sanitizer.md 9.0, 22.5)
+    const st = {
+        san,
+        decision,
+        ctx,
+        parentSpanId: tp?.spanId,
+        t0: performance.now(),
+        tsMs: Date.now(),
+        reqTap: new body_js_1.BodyTap(limit),
+        resTap: new body_js_1.BodyTap(limit),
+        overheadNs: 0,
+    };
+    tapPush(req, st.reqTap);
+    // res.end() runs inside the handler, where an OpenTelemetry server span (if any) is active:
+    // adopt its trace id when the request carried none, so the event joins the app's trace.
+    tapWrites(res, st.resTap, () => {
+        if (st.ctx.traceKnown)
+            return;
+        const o = (0, context_js_1.otelActive)();
+        if (o) {
+            st.ctx.traceId = o.traceId;
+            st.ctx.traceKnown = true;
+        }
+    });
+    res[kState] = st;
+    st.overheadNs = (0, common_js_1.hrNow)() - t;
+}
+function finish(host, req, res, t) {
+    const st = res[kState];
+    if (!st)
+        return;
+    res[kState] = undefined;
+    const latencyMs = Math.max(0, Math.floor(performance.now() - st.t0));
+    // 9.0: a body the app did not read to the end is "not consumed"; an empty body is complete.
+    const reqConsumed = req.readableEnded || (req.complete && st.reqTap.total === 0);
+    const status = res.statusCode;
+    const method = req.method ?? '';
+    const noBody = method === 'HEAD' || status === 204 || status === 304 || (status >= 100 && status < 200);
+    const target = req.url ?? '/';
+    const respHeaders = (0, common_js_1.outgoingHeadersWire)(res);
+    // Express: only routes defined directly on the app carry their complete template.
+    let route;
+    if (req.route && typeof req.route.path === 'string' && (req.baseUrl === '' || req.baseUrl === undefined))
+        route = req.route.path;
+    const reqBody = reqConsumed ? st.reqTap.bytes() : EMPTY;
+    const resBody = noBody ? EMPTY : st.resTap.bytes();
+    const resTotal = noBody ? 0 : st.resTap.total;
+    const resEnded = noBody || st.resTap.ended;
+    const wire = {
+        dir: 'inbound',
+        service_name: host.serviceName(),
+        method,
+        target,
+        trace_id: st.ctx.traceKnown ? st.ctx.traceId : undefined,
+        req_headers: req.rawHeaders,
+        req_body: reqBody,
+        req_body_total: st.reqTap.total,
+        req_body_consumed: reqConsumed,
+        status,
+        resp_headers: respHeaders,
+        resp_body: resBody,
+        resp_body_total: resEnded ? resTotal : 'unknown',
+    };
+    if (route !== undefined) {
+        wire.framework = 'express';
+        wire.framework_route = route;
+    }
+    host.submit({
+        sanitizer: st.san,
+        decision: st.decision,
+        dir: 'inbound',
+        tsMs: st.tsMs,
+        latencyMs,
+        traceId: st.ctx.traceId,
+        spanId: st.ctx.spanId,
+        parentSpanId: st.parentSpanId,
+        status,
+        heldBytes: reqBody.length + resBody.length,
+        wire,
+    });
+    host.noteOverhead(st.overheadNs + ((0, common_js_1.hrNow)() - t));
+}

package/dist/cjs/capture/outbound-http.d.ts

@@ -0,0 +1,4 @@
+import { type CaptureHost } from './common.js';
+/** How long an unread response body is waited for before the exchange is closed as not consumed. */
+export declare const UNREAD_BODY_TIMEOUT_MS = 60000;
+export declare function installOutboundHttp(host: CaptureHost): () => void;