@foam-ai/node 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/network-capture/collector.js

@@ -0,0 +1,411 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BodyCollector = void 0;
+exports.setHeaderAttributes = setHeaderAttributes;
+const api_1 = require("@opentelemetry/api");
+const api_logs_1 = require("@opentelemetry/api-logs");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const node_crypto_1 = require("node:crypto");
+const zlib = __importStar(require("node:zlib"));
+const constants_js_1 = require("../constants.js");
+const utils_js_1 = require("../utils.js");
+const redact_js_1 = require("./redact.js");
+const ALLOWED_HEADERS = new Set(constants_js_1.SAFE_NETWORK_HEADERS);
+const ATTR = {
+    request: {
+        header: semantic_conventions_1.ATTR_HTTP_REQUEST_HEADER,
+        size: constants_js_1.ATTR_HTTP_REQUEST_BODY_SIZE,
+        content: constants_js_1.ATTR_HTTP_REQUEST_BODY_CONTENT,
+        captureId: constants_js_1.ATTR_FOAM_HTTP_REQUEST_BODY_CAPTURE_ID,
+        complete: constants_js_1.ATTR_FOAM_HTTP_REQUEST_BODY_COMPLETE,
+        truncated: constants_js_1.ATTR_FOAM_HTTP_REQUEST_BODY_TRUNCATED,
+    },
+    response: {
+        header: semantic_conventions_1.ATTR_HTTP_RESPONSE_HEADER,
+        size: constants_js_1.ATTR_HTTP_RESPONSE_BODY_SIZE,
+        content: constants_js_1.ATTR_HTTP_RESPONSE_BODY_CONTENT,
+        captureId: constants_js_1.ATTR_FOAM_HTTP_RESPONSE_BODY_CAPTURE_ID,
+        complete: constants_js_1.ATTR_FOAM_HTTP_RESPONSE_BODY_COMPLETE,
+        truncated: constants_js_1.ATTR_FOAM_HTTP_RESPONSE_BODY_TRUNCATED,
+    },
+};
+let activeCaptures = 0;
+function captureLogger() {
+    return api_logs_1.logs.getLogger(constants_js_1.FOAM_DISTRO_NAME, constants_js_1.FOAM_DISTRO_VERSION);
+}
+function headerValues(value) {
+    return Array.isArray(value) ? value.map(String) : [String(value)];
+}
+function setHeaderAttributes(span, direction, headers) {
+    const attributes = {};
+    for (const [rawName, rawValue] of Object.entries(headers)) {
+        if (rawValue === undefined)
+            continue;
+        const name = rawName.toLowerCase();
+        if (!ALLOWED_HEADERS.has(name))
+            continue;
+        attributes[ATTR[direction].header(name)] = headerValues(rawValue);
+    }
+    if (Object.keys(attributes).length > 0)
+        span.setAttributes(attributes);
+}
+function stringEncoding(encoding) {
+    return typeof encoding === "string" && Buffer.isEncoding(encoding)
+        ? encoding
+        : "utf8";
+}
+function copyBody(value, encoding) {
+    if (typeof value === "string") {
+        return Buffer.from(value, stringEncoding(encoding));
+    }
+    if (Buffer.isBuffer(value))
+        return Buffer.from(value);
+    if (ArrayBuffer.isView(value)) {
+        return Buffer.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
+    }
+    return undefined;
+}
+// Byte length of a body chunk without copying it; undefined for non-body values.
+function bodyByteLength(value, encoding) {
+    if (typeof value === "string") {
+        return Buffer.byteLength(value, stringEncoding(encoding));
+    }
+    if (Buffer.isBuffer(value) || ArrayBuffer.isView(value)) {
+        return value.byteLength;
+    }
+    return undefined;
+}
+function decodeBody(bytes, contentEncoding) {
+    if (contentEncoding === undefined)
+        return bytes;
+    const encodings = headerValues(contentEncoding)
+        .flatMap((value) => value.split(","))
+        .map((value) => value.trim().toLowerCase())
+        .filter((value) => value && value !== "identity");
+    if (encodings.length === 0)
+        return bytes;
+    const limits = { maxOutputLength: constants_js_1.NETWORK_BODY_MAX_DECODE_BYTES };
+    let decoded = bytes;
+    try {
+        for (const encoding of encodings.reverse()) {
+            if (encoding === "gzip" || encoding === "x-gzip") {
+                decoded = zlib.gunzipSync(decoded, limits);
+            }
+            else if (encoding === "deflate") {
+                try {
+                    decoded = zlib.inflateSync(decoded, limits);
+                }
+                catch {
+                    decoded = zlib.unzipSync(decoded, limits);
+                }
+            }
+            else if (encoding === "br") {
+                decoded = zlib.brotliDecompressSync(decoded, limits);
+            }
+            else if (encoding === "zstd") {
+                const decompress = zlib.zstdDecompressSync;
+                if (!decompress)
+                    return undefined;
+                decoded = decompress(decoded, limits);
+            }
+            else {
+                return undefined;
+            }
+        }
+        return decoded;
+    }
+    catch {
+        return undefined;
+    }
+}
+function textEncoding(contentType) {
+    const raw = headerValues(contentType)[0];
+    if (raw === undefined)
+        return undefined;
+    const parts = raw.split(";").map((part) => part.trim());
+    const media = (parts[0] ?? "").toLowerCase();
+    const charset = parts
+        .find((part) => part.toLowerCase().startsWith("charset="))
+        ?.slice("charset=".length)
+        .trim()
+        .replace(/^["']|["']$/g, "")
+        .toLowerCase();
+    const isText = (0, redact_js_1.isTextualBodyMediaType)(media) || Boolean(charset);
+    if (!isText)
+        return undefined;
+    if (charset && Buffer.isEncoding(charset))
+        return charset;
+    if (charset === "iso-8859-1" || charset === "windows-1252")
+        return "latin1";
+    if (media.startsWith("multipart/"))
+        return "latin1";
+    return "utf8";
+}
+// Last index such that `buf.subarray(0, end)` is complete UTF-8, capped at `max`.
+function utf8End(buf, max) {
+    const end = Math.min(max, buf.byteLength);
+    if (end === 0)
+        return 0;
+    let leadAt = end;
+    while (leadAt > 0 && (buf[leadAt - 1] & 0xc0) === 0x80)
+        leadAt--;
+    if (leadAt === 0)
+        return 0;
+    const lead = buf[leadAt - 1];
+    const needed = (lead & 0x80) === 0
+        ? 1
+        : (lead & 0xe0) === 0xc0
+            ? 2
+            : (lead & 0xf0) === 0xe0
+                ? 3
+                : (lead & 0xf8) === 0xf0
+                    ? 4
+                    : Number.POSITIVE_INFINITY;
+    return end - (leadAt - 1) >= needed ? end : leadAt - 1;
+}
+function cappedBody(buf) {
+    if (buf.byteLength <= constants_js_1.NETWORK_BODY_MAX_CAPTURE_BYTES)
+        return buf;
+    return buf.subarray(0, constants_js_1.NETWORK_BODY_MAX_CAPTURE_BYTES);
+}
+function decodeText(decoded, encoding) {
+    const limited = cappedBody(decoded);
+    if (encoding === "utf8" || encoding === "utf-8") {
+        return limited.subarray(0, utf8End(limited, limited.byteLength)).toString(encoding);
+    }
+    return limited.toString(encoding);
+}
+class BodyCollector {
+    span;
+    context;
+    side;
+    direction;
+    headers;
+    id = (0, node_crypto_1.randomUUID)();
+    attr;
+    chunks = [];
+    cleanups = [];
+    deadline;
+    observedBytes = 0;
+    capturedBytes = 0;
+    truncated = false;
+    finalized = false;
+    constructor(span, context, side, direction, headers) {
+        this.span = span;
+        this.context = context;
+        this.side = side;
+        this.direction = direction;
+        this.headers = headers;
+        this.attr = ATTR[direction];
+        activeCaptures += 1;
+        this.deadline = setTimeout(() => this.finalize(false), constants_js_1.NETWORK_CAPTURE_DEADLINE_MS);
+        this.deadline.unref();
+        this.span.setAttribute(this.attr.captureId, this.id);
+    }
+    static create(span, side, direction, headers) {
+        const context = api_1.trace.setSpanContext(api_1.ROOT_CONTEXT, span.spanContext());
+        if (activeCaptures >= constants_js_1.MAX_ACTIVE_CAPTURES ||
+            !span.isRecording() ||
+            (span.spanContext().traceFlags & api_1.TraceFlags.SAMPLED) !==
+                api_1.TraceFlags.SAMPLED ||
+            !captureLogger().enabled({
+                context,
+                eventName: constants_js_1.NETWORK_CAPTURE_EVENT,
+                severityNumber: api_logs_1.SeverityNumber.INFO,
+            })) {
+            return undefined;
+        }
+        return new BodyCollector(span, context, side, direction, headers);
+    }
+    addCleanup(cleanup) {
+        this.cleanups.push(cleanup);
+    }
+    observe(value, encoding) {
+        if (this.finalized)
+            return;
+        if (this.capturedBytes >= constants_js_1.NETWORK_BODY_MAX_CAPTURE_BYTES) {
+            // Past the cap every chunk is discarded; only its length is needed
+            // (for the observed size), so skip the per-chunk copy that would
+            // otherwise double the allocation traffic of large transfers.
+            const length = bodyByteLength(value, encoding);
+            if (length === undefined)
+                return;
+            this.deadline.refresh();
+            this.observedBytes += length;
+            this.truncated = true;
+            this.span.setAttributes({
+                [this.attr.size]: this.observedBytes,
+                [this.attr.truncated]: true,
+            });
+            return;
+        }
+        const bytes = copyBody(value, encoding);
+        if (!bytes)
+            return;
+        this.deadline.refresh();
+        this.observedBytes += bytes.byteLength;
+        this.span.setAttribute(this.attr.size, this.observedBytes);
+        const room = constants_js_1.NETWORK_BODY_MAX_CAPTURE_BYTES - this.capturedBytes;
+        const kept = bytes.byteLength > room ? bytes.subarray(0, room) : bytes;
+        this.chunks.push(kept);
+        this.capturedBytes += kept.byteLength;
+        if (kept.byteLength < bytes.byteLength) {
+            this.truncated = true;
+            this.span.setAttribute(this.attr.truncated, true);
+        }
+    }
+    finalize(complete) {
+        if (this.finalized)
+            return;
+        this.finalized = true;
+        clearTimeout(this.deadline);
+        activeCaptures -= 1;
+        for (const cleanup of this.cleanups.splice(0))
+            (0, utils_js_1.safely)(cleanup);
+        // Runs inside stream handlers; header snapshots may throw on destroyed messages.
+        (0, utils_js_1.safely)(() => {
+            const headers = this.headers();
+            setHeaderAttributes(this.span, this.direction, headers);
+            this.span.setAttributes({
+                [this.attr.complete]: complete,
+                [this.attr.truncated]: this.truncated,
+                [this.attr.size]: this.observedBytes,
+            });
+            this.emit(this.chunks.splice(0), headers, complete);
+        });
+    }
+    emit(buffers, headers, complete) {
+        let outcome;
+        if (this.observedBytes === 0)
+            outcome = "empty";
+        else if (complete)
+            outcome = "captured";
+        else
+            outcome = "incomplete";
+        if (outcome === "empty")
+            return;
+        let wire;
+        if (buffers.length === 0)
+            wire = undefined;
+        else if (buffers.length === 1)
+            wire = buffers[0];
+        else
+            wire = Buffer.concat(buffers);
+        // Span attributes cannot hold bytes (OTel AttributeValue). Text goes on
+        // the span; binary uses the same `http.*.body.content` name on the event.
+        let binaryContent;
+        let chunkSource = wire;
+        let chunkSourceIsDecodedText = false;
+        if (wire !== undefined) {
+            const decoded = decodeBody(wire, headers["content-encoding"]);
+            if (decoded === undefined) {
+                binaryContent = Uint8Array.from(cappedBody(wire));
+            }
+            else {
+                const encoding = textEncoding(headers["content-type"]);
+                if (encoding !== undefined) {
+                    const redacted = (0, redact_js_1.redactBodyText)(decodeText(decoded, encoding), headers["content-type"]);
+                    this.span.setAttribute(this.attr.content, redacted.text);
+                    if (redacted.changed) {
+                        // pcga11: Chunk events must not re-ship bytes the span content
+                        // redacted, so the (possibly compressed) wire bytes are replaced
+                        // with the redacted text.
+                        chunkSource = Buffer.from(redacted.text, encoding);
+                        chunkSourceIsDecodedText = true;
+                    }
+                }
+                else {
+                    binaryContent = Uint8Array.from(cappedBody(decoded));
+                }
+            }
+        }
+        const chunks = [];
+        if (chunkSource) {
+            for (let i = 0; i < chunkSource.byteLength; i += constants_js_1.NETWORK_BODY_CHUNK_BYTES) {
+                chunks.push(chunkSource.subarray(i, i + constants_js_1.NETWORK_BODY_CHUNK_BYTES));
+            }
+        }
+        const common = {
+            [constants_js_1.ATTR_FOAM_HTTP_BODY_ID]: this.id,
+            [constants_js_1.ATTR_FOAM_HTTP_BODY_SIDE]: this.side,
+            [constants_js_1.ATTR_FOAM_HTTP_BODY_DIRECTION]: this.direction,
+            [constants_js_1.ATTR_FOAM_HTTP_BODY_COMPLETE]: complete,
+            [constants_js_1.ATTR_FOAM_HTTP_BODY_TRUNCATED]: this.truncated,
+            [constants_js_1.ATTR_FOAM_HTTP_BODY_OUTCOME]: outcome,
+            [this.attr.size]: this.observedBytes,
+            [constants_js_1.ATTR_FOAM_HTTP_BODY_CAPTURED_BYTES]: chunkSourceIsDecodedText
+                ? (chunkSource?.byteLength ?? 0)
+                : this.capturedBytes,
+            [constants_js_1.ATTR_FOAM_HTTP_BODY_CHUNK_COUNT]: chunks.length,
+        };
+        for (const name of ["content-type", "content-encoding"]) {
+            if (name === "content-encoding" &&
+                chunkSourceIsDecodedText &&
+                headers[name] !== undefined) {
+                common[this.attr.header(name)] = ["identity"];
+                continue;
+            }
+            if (headers[name] !== undefined) {
+                common[this.attr.header(name)] = headerValues(headers[name]);
+            }
+        }
+        const logger = captureLogger();
+        const records = chunks.length === 0 ? [undefined] : chunks;
+        records.forEach((chunk, index) => {
+            logger.emit({
+                eventName: constants_js_1.NETWORK_CAPTURE_EVENT,
+                body: constants_js_1.NETWORK_CAPTURE_EVENT_BODY,
+                severityNumber: api_logs_1.SeverityNumber.INFO,
+                severityText: constants_js_1.SEVERITY_TEXT[api_logs_1.SeverityNumber.INFO],
+                attributes: {
+                    ...common,
+                    ...(chunk
+                        ? {
+                            [constants_js_1.ATTR_FOAM_HTTP_BODY_CHUNK_INDEX]: index,
+                            [constants_js_1.ATTR_FOAM_HTTP_BODY_CHUNK_BYTES]: chunk.byteLength,
+                            [constants_js_1.ATTR_FOAM_HTTP_BODY_CHUNK_CONTENT]: Uint8Array.from(chunk),
+                        }
+                        : {}),
+                    ...(index === 0 && binaryContent
+                        ? { [this.attr.content]: binaryContent }
+                        : {}),
+                },
+                context: this.context,
+            });
+        });
+    }
+}
+exports.BodyCollector = BodyCollector;

package/dist/network-capture/http.d.ts

@@ -0,0 +1,5 @@
+import type { HttpRequestCustomAttributeFunction, HttpResponseCustomAttributeFunction } from "@opentelemetry/instrumentation-http";
+export declare function createNetworkCaptureHooks(bodyCaptureEnabled?: boolean): {
+    requestHook: HttpRequestCustomAttributeFunction;
+    responseHook: HttpResponseCustomAttributeFunction;
+};

package/dist/network-capture/http.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNetworkCaptureHooks = createNetworkCaptureHooks;
+const node_events_1 = require("node:events");
+const utils_js_1 = require("../utils.js");
+const collector_js_1 = require("./collector.js");
+function incomingHeaders(message) {
+    return message.headers;
+}
+function outgoingHeaders(message, direct) {
+    return {
+        ...Object.fromEntries(direct),
+        ...message.getHeaders(),
+    };
+}
+function observeDirectHeaders(args, headers) {
+    const append = (rawKey, value) => {
+        const key = String(rawKey).toLowerCase();
+        const existing = headers.get(key);
+        if (existing === undefined)
+            headers.set(key, value);
+        else if (Array.isArray(existing))
+            existing.push(value);
+        else
+            headers.set(key, [existing, value]);
+    };
+    const candidate = args.length >= 3 && typeof args[1] === "string" ? args[2] : args[1];
+    if (!candidate || typeof candidate !== "object")
+        return;
+    if (Array.isArray(candidate)) {
+        if (candidate.every(Array.isArray)) {
+            for (const entry of candidate) {
+                if (entry.length >= 2) {
+                    append(entry[0], entry[1]);
+                }
+            }
+        }
+        else {
+            for (let index = 0; index + 1 < candidate.length; index += 2) {
+                append(candidate[index], candidate[index + 1]);
+            }
+        }
+        return;
+    }
+    for (const [rawKey, value] of Object.entries(candidate)) {
+        append(rawKey, value);
+    }
+}
+// pcga11:Replaces a method with a wrapped version; returns an undo that restores it unless someone else re-patched it.
+function swapMethod(target, key, wrap) {
+    const original = target[key];
+    const wrapped = wrap(original);
+    target[key] = wrapped;
+    return () => {
+        if (target[key] === wrapped)
+            target[key] = original;
+    };
+}
+// Wraps writeHead (when present) to record inline headers; returns an undo.
+function swapWriteHead(target, directHeaders, afterWriteHead) {
+    const original = target.writeHead;
+    if (!original)
+        return () => { };
+    const wrapped = function (...args) {
+        const result = Reflect.apply(original, this, args);
+        (0, utils_js_1.safely)(() => {
+            observeDirectHeaders(args, directHeaders);
+            afterWriteHead?.();
+        });
+        return result;
+    };
+    target.writeHead = wrapped;
+    return () => {
+        if (target.writeHead === wrapped)
+            target.writeHead = original;
+    };
+}
+// Attaches one-shot listeners; returns an undo that removes all of them.
+function listenOnce(target, listeners) {
+    for (const [event, listener] of listeners)
+        target.once(event, listener);
+    return () => {
+        for (const [event, listener] of listeners) {
+            target.removeListener(event, listener);
+        }
+    };
+}
+function observeWritableHeaders(message, span, direction, directHeaders) {
+    const target = message;
+    const applyHeaders = () => {
+        (0, collector_js_1.setHeaderAttributes)(span, direction, outgoingHeaders(message, directHeaders));
+    };
+    const restoreEnd = swapMethod(target, "end", (originalEnd) => function (...args) {
+        const result = Reflect.apply(originalEnd, this, args);
+        (0, utils_js_1.safely)(applyHeaders);
+        return result;
+    });
+    const restoreWriteHead = swapWriteHead(target, directHeaders, applyHeaders);
+    let removeListeners = () => { };
+    // Runs inside the customer's EventEmitter emit; a throw here would surface
+    // as an uncaughtException in their app.
+    const cleanup = () => (0, utils_js_1.safely)(() => {
+        restoreEnd();
+        restoreWriteHead();
+        removeListeners();
+    });
+    removeListeners = listenOnce(target, [
+        ["finish", cleanup],
+        ["close", cleanup],
+    ]);
+}
+function observeReadable(message, collector) {
+    const target = message;
+    const restorePush = swapMethod(target, "push", (originalPush) => function (...args) {
+        // The parser's delivery path runs first and its result is returned
+        // unconditionally; observation failures must never disturb it.
+        const result = Reflect.apply(originalPush, this, args);
+        (0, utils_js_1.safely)(() => {
+            if (args[0] !== null)
+                collector.observe(args[0], args[1]);
+            else
+                collector.finalize(true);
+        });
+        return result;
+    });
+    const onComplete = () => (0, utils_js_1.safely)(() => collector.finalize(true));
+    const onIncomplete = () => (0, utils_js_1.safely)(() => collector.finalize(false));
+    const removeListeners = listenOnce(target, [
+        ["end", onComplete],
+        ["aborted", onIncomplete],
+        ["close", onIncomplete],
+        [node_events_1.errorMonitor, onIncomplete],
+    ]);
+    collector.addCleanup(() => {
+        restorePush();
+        removeListeners();
+    });
+}
+function observeWritable(message, collector, directHeaders) {
+    const target = message;
+    // Prevents double-observing a final chunk that end() forwards to write() internally.
+    let ending = false;
+    const restoreWrite = swapMethod(target, "write", (originalWrite) => function (...args) {
+        const result = Reflect.apply(originalWrite, this, args);
+        if (!ending)
+            (0, utils_js_1.safely)(() => collector.observe(args[0], args[1]));
+        return result;
+    });
+    const restoreEnd = swapMethod(target, "end", (originalEnd) => function (...args) {
+        ending = true;
+        try {
+            const result = Reflect.apply(originalEnd, this, args);
+            (0, utils_js_1.safely)(() => collector.observe(args[0], args[1]));
+            return result;
+        }
+        finally {
+            ending = false;
+        }
+    });
+    const restoreWriteHead = swapWriteHead(target, directHeaders);
+    const onComplete = () => (0, utils_js_1.safely)(() => collector.finalize(true));
+    const onIncomplete = () => (0, utils_js_1.safely)(() => collector.finalize(false));
+    const removeListeners = listenOnce(target, [
+        ["finish", onComplete],
+        ["close", onIncomplete],
+        [node_events_1.errorMonitor, onIncomplete],
+    ]);
+    collector.addCleanup(() => {
+        restoreWrite();
+        restoreEnd();
+        restoreWriteHead();
+        removeListeners();
+    });
+}
+// pcga11: Instruments one HTTP message on a span:
+// - records headers as `http.<direction>.header.*` attributes
+// - captures the body via a BodyCollector when enabled.
+function hookMessage(span, message, direction, bodyCaptureEnabled) {
+    // pcga11: Duck-type: only outgoing messages (ClientRequest/ServerResponse) have write/end.
+    if ("write" in message && "end" in message) {
+        const side = direction === "request" ? "client" : "server";
+        const directHeaders = new Map();
+        (0, collector_js_1.setHeaderAttributes)(span, direction, outgoingHeaders(message, directHeaders));
+        const collector = bodyCaptureEnabled
+            ? // Headers are passed as a lazy callback so late-set headers are seen at finalize time.
+                collector_js_1.BodyCollector.create(span, side, direction, () => outgoingHeaders(message, directHeaders))
+            : undefined;
+        // With a collector, patch write/end/writeHead to copy body chunks as the app sends them.
+        if (collector)
+            observeWritable(message, collector, directHeaders);
+        else if (span.isRecording()) {
+            observeWritableHeaders(message, span, direction, directHeaders);
+        }
+    }
+    else {
+        const side = direction === "request" ? "server" : "client";
+        const headers = incomingHeaders(message);
+        (0, collector_js_1.setHeaderAttributes)(span, direction, headers);
+        const collector = bodyCaptureEnabled
+            ? collector_js_1.BodyCollector.create(span, side, direction, () => headers)
+            : undefined;
+        if (collector)
+            observeReadable(message, collector);
+    }
+}
+// pcga11: Creates network capture hooks for node:http / node:https. Wraps instance
+// methods: push(), write(), and end() on IncomingMessage / ClientRequest /
+// ServerResponse. This works for all Node versions Foam supports.
+function createNetworkCaptureHooks(bodyCaptureEnabled = true) {
+    // OTel guards hook errors today, but Foam's no-crash guarantee must not
+    // depend on that: any failure here is swallowed and the request proceeds
+    // as if Foam were not installed.
+    return {
+        requestHook(span, request) {
+            (0, utils_js_1.safely)(() => hookMessage(span, request, "request", bodyCaptureEnabled));
+        },
+        responseHook(span, response) {
+            (0, utils_js_1.safely)(() => hookMessage(span, response, "response", bodyCaptureEnabled));
+        },
+    };
+}

package/dist/network-capture/index.d.ts

@@ -0,0 +1,3 @@
+export { createNetworkCaptureHooks } from "./http.js";
+export { createUndiciNetworkCaptureHooks } from "./undici.js";
+export { isHttpCaptureSupported, isUndiciCaptureSupported } from "./support.js";

package/dist/network-capture/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isUndiciCaptureSupported = exports.isHttpCaptureSupported = exports.createUndiciNetworkCaptureHooks = exports.createNetworkCaptureHooks = void 0;
+// 
+// Advanced body capture uses three adapters across Foam's Node range:
+// 1. node:http / node:https — instance push(), write(), and end() wrapping
+//    (every supported Node version).
+// 2. Undici legacy — request:create plus instance onBodySent / onData
+//    (bundled fetch on Node 18.19, 20, 22, and 24.0–24.3, whose Undici is
+//    older than 7.11).
+// 3. Undici modern — bodyChunkSent / bodyChunkReceived channels (Undici
+//    7.11+, including Node 24.4+ and a separately installed undici). Future
+//    Node is chosen by capability: modern channels win when they fire.
+var http_js_1 = require("./http.js");
+Object.defineProperty(exports, "createNetworkCaptureHooks", { enumerable: true, get: function () { return http_js_1.createNetworkCaptureHooks; } });
+var undici_js_1 = require("./undici.js");
+Object.defineProperty(exports, "createUndiciNetworkCaptureHooks", { enumerable: true, get: function () { return undici_js_1.createUndiciNetworkCaptureHooks; } });
+var support_js_1 = require("./support.js");
+Object.defineProperty(exports, "isHttpCaptureSupported", { enumerable: true, get: function () { return support_js_1.isHttpCaptureSupported; } });
+Object.defineProperty(exports, "isUndiciCaptureSupported", { enumerable: true, get: function () { return support_js_1.isUndiciCaptureSupported; } });

package/dist/network-capture/redact.d.ts

@@ -0,0 +1,9 @@
+export interface RedactionResult {
+    readonly text: string;
+    readonly changed: boolean;
+}
+export declare function isSensitiveBodyKey(key: string): boolean;
+export declare function isNdjsonMediaType(media: string): boolean;
+export declare function isJsonSequenceMediaType(media: string): boolean;
+export declare function isTextualBodyMediaType(media: string): boolean;
+export declare function redactBodyText(text: string, contentType: unknown): RedactionResult;