@foam-ai/node 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/network-capture/collector.js

@@ -0,0 +1,312 @@
+"use strict";
+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 node_zlib_1 = require("node:zlib");
+const constants_js_1 = require("../constants.js");
+const utils_js_1 = require("../utils.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 copyBody(value, encoding) {
+    if (typeof value === "string") {
+        const enc = typeof encoding === "string" && Buffer.isEncoding(encoding)
+            ? encoding
+            : "utf8";
+        return Buffer.from(value, enc);
+    }
+    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;
+}
+function decodeBody(bytes, contentEncoding) {
+    if (contentEncoding === undefined)
+        return bytes;
+    const encoding = headerValues(contentEncoding)[0]?.toLowerCase().trim();
+    if (!encoding || encoding === "identity")
+        return bytes;
+    try {
+        if (encoding === "gzip" || encoding === "x-gzip")
+            return (0, node_zlib_1.gunzipSync)(bytes);
+        if (encoding === "deflate") {
+            try {
+                return (0, node_zlib_1.inflateSync)(bytes);
+            }
+            catch {
+                return (0, node_zlib_1.unzipSync)(bytes);
+            }
+        }
+        if (encoding === "br")
+            return (0, node_zlib_1.brotliDecompressSync)(bytes);
+    }
+    catch {
+        return undefined;
+    }
+    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)
+        .toLowerCase();
+    const text = media.startsWith("text/") ||
+        media.endsWith("/json") ||
+        media.endsWith("+json") ||
+        media.endsWith("/xml") ||
+        media.endsWith("+xml") ||
+        media.endsWith("/yaml") ||
+        media.endsWith("+yaml") ||
+        media === "application/x-www-form-urlencoded" ||
+        Boolean(charset);
+    if (!text)
+        return undefined;
+    return charset && Buffer.isEncoding(charset) ? charset : "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;
+}
+// pcga11: Span attributes cannot carry byte arrays (OTel AttributeValue).
+// Text goes on the span; binary uses the same `http.*.body.content` name on
+// the correlated event, where log attributes accept Uint8Array.
+function spanBodyContent(decoded, contentType) {
+    const encoding = textEncoding(contentType);
+    if (encoding === undefined)
+        return undefined;
+    const limited = decoded.byteLength > constants_js_1.NETWORK_BODY_MAX_CAPTURE_BYTES
+        ? decoded.subarray(0, constants_js_1.NETWORK_BODY_MAX_CAPTURE_BYTES)
+        : decoded;
+    const end = encoding === "utf8" || encoding === "utf-8"
+        ? utf8End(limited, limited.byteLength)
+        : limited.byteLength;
+    return limited.subarray(0, end).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;
+        const bytes = copyBody(value, encoding);
+        if (!bytes)
+            return;
+        this.deadline.refresh();
+        this.observedBytes += bytes.byteLength;
+        this.span.setAttribute(this.attr.size, this.observedBytes);
+        if (this.capturedBytes >= constants_js_1.NETWORK_BODY_MAX_CAPTURE_BYTES) {
+            this.truncated = true;
+            this.span.setAttribute(this.attr.truncated, true);
+            return;
+        }
+        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) {
+        const outcome = this.observedBytes === 0
+            ? "empty"
+            : complete
+                ? "captured"
+                : "incomplete";
+        if (outcome === "empty")
+            return;
+        const wire = buffers.length <= 1 ? buffers[0] : Buffer.concat(buffers);
+        let binaryContent;
+        if (wire) {
+            const decoded = decodeBody(wire, headers["content-encoding"]);
+            const source = decoded ?? wire;
+            const text = decoded
+                ? spanBodyContent(decoded, headers["content-type"])
+                : undefined;
+            if (text !== undefined) {
+                this.span.setAttribute(this.attr.content, text);
+            }
+            else {
+                const limited = source.byteLength > constants_js_1.NETWORK_BODY_MAX_CAPTURE_BYTES
+                    ? source.subarray(0, constants_js_1.NETWORK_BODY_MAX_CAPTURE_BYTES)
+                    : source;
+                binaryContent = Uint8Array.from(limited);
+            }
+        }
+        const chunks = [];
+        if (wire) {
+            for (let i = 0; i < wire.byteLength; i += constants_js_1.NETWORK_BODY_CHUNK_BYTES) {
+                chunks.push(wire.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]: this.capturedBytes,
+            [constants_js_1.ATTR_FOAM_HTTP_BODY_CHUNK_COUNT]: chunks.length,
+        };
+        for (const name of ["content-type", "content-encoding"]) {
+            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,6 @@
+import type { HttpRequestCustomAttributeFunction, HttpResponseCustomAttributeFunction } from "@opentelemetry/instrumentation-http";
+/** Builds OTel HTTP request/response hooks that record headers as span attributes and stream bodies as log events. */
+export declare function createNetworkCaptureHooks(bodyCaptureEnabled?: boolean): {
+    requestHook: HttpRequestCustomAttributeFunction;
+    responseHook: HttpResponseCustomAttributeFunction;
+};

package/dist/network-capture/http.js

@@ -0,0 +1,223 @@
+"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);
+    }
+}
+/** 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 = () => { };
+    const cleanup = () => {
+        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 = () => collector.finalize(true);
+    const onIncomplete = () => 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 = () => collector.finalize(true);
+    const onIncomplete = () => collector.finalize(false);
+    const removeListeners = listenOnce(target, [
+        ["finish", onComplete],
+        ["close", onIncomplete],
+        [node_events_1.errorMonitor, onIncomplete],
+    ]);
+    collector.addCleanup(() => {
+        restoreWrite();
+        restoreEnd();
+        restoreWriteHead();
+        removeListeners();
+    });
+}
+/**
+ * Instruments one HTTP message (either side, either direction) on a span:
+ * records headers as `http.<direction>.header.*` attributes and, when enabled,
+ * captures the body via a BodyCollector.
+ */
+function hookMessage(span, message, direction, bodyCaptureEnabled) {
+    // Duck-type: only outgoing messages (ClientRequest/ServerResponse) have write/end.
+    if ("write" in message && "end" in message) {
+        // A writable request is an outgoing client call; a writable response is served by us.
+        const side = direction === "request" ? "client" : "server";
+        // Collects headers passed inline to writeHead(), which don't show up in getHeaders().
+        const directHeaders = new Map();
+        // Eagerly record whatever headers exist right now; late-set headers are handled below.
+        (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()) {
+            // No body capture: still patch end/writeHead so late-set headers land on the span.
+            observeWritableHeaders(message, span, direction, directHeaders);
+        }
+    }
+    else {
+        // Inverse of the writable case: a request arriving at us means we are the server.
+        const side = direction === "request" ? "server" : "client";
+        // Incoming message: headers are fully parsed by Node before the hook runs, so snapshot once.
+        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;
+        // Patch the stream's push() to copy body chunks as they arrive from the socket.
+        if (collector)
+            observeReadable(message, collector);
+    }
+}
+/** Builds OTel HTTP request/response hooks that record headers as span attributes and stream bodies as log events. */
+function createNetworkCaptureHooks(bodyCaptureEnabled = true) {
+    return {
+        requestHook(span, request) {
+            hookMessage(span, request, "request", bodyCaptureEnabled);
+        },
+        responseHook(span, response) {
+            hookMessage(span, response, "response", bodyCaptureEnabled);
+        },
+    };
+}

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

@@ -0,0 +1,2 @@
+export { createNetworkCaptureHooks } from "./http.js";
+export { createUndiciNetworkCaptureHooks } from "./undici.js";

package/dist/network-capture/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUndiciNetworkCaptureHooks = exports.createNetworkCaptureHooks = void 0;
+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; } });

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

@@ -0,0 +1,9 @@
+import type { RequestHookFunction, ResponseHookFunction } from "@opentelemetry/instrumentation-undici";
+/**
+ * Builds OTel Undici/fetch hooks. Headers use the same allowlist as Node HTTP.
+ * Bodies are copied from diagnostics_channel chunks — never from fetch streams.
+ */
+export declare function createUndiciNetworkCaptureHooks(bodyCaptureEnabled?: boolean): {
+    requestHook: RequestHookFunction;
+    responseHook: ResponseHookFunction;
+};