@hue-run/sdk 0.21.1 → 0.22.0

package/dist/cli/import-formats/otlp-protobuf.js

@@ -0,0 +1,486 @@
+import * as zlib from "node:zlib";
+import { ConversionError, isObject, OTLP_SPANS, OtlpTraceCollector, parseJsonText, } from "../traces-import-convert.js";
+/**
+ * Binary OTLP trace files: one protobuf `ExportTraceServiceRequest` (an OTLP/HTTP request body,
+ * a `.pb` or `.binpb` file), and the OpenTelemetry Collector file exporter's length-prefixed
+ * output (`format: proto`, or `compression: zstd`, each message preceded by its size as a 4-byte
+ * big-endian integer). A zstd-compressed message is decompressed first; a message that is JSON
+ * inside (`format: json` with `compression: zstd`) is read as OTLP/JSON. A collector file written
+ * as one zstd stream is undone by the containers before this reads it.
+ *
+ * The reader below decodes the OTLP trace messages the files hold (opentelemetry-proto v1) into
+ * their OTLP/JSON form, ids as hex and 64-bit integers as decimal text, and the spans are then
+ * kept as recorded, exactly as an OTLP/JSON export's are. It is strict: a span with a field of the
+ * wrong wire type, a truncated field or text that is not UTF-8 refuses its trace (the other traces
+ * of the message are read), and damage outside any span makes the message unreadable, that message
+ * alone reported. It is written here because the package carries no protobuf runtime.
+ *
+ * The messages of a length-prefixed file are read one at a time, and their decompressed sizes
+ * together, those of messages that then do not read included, are bounded as one file's are.
+ */
+/** Marks a value decoded from protobuf: no JSON document can carry a symbol key. */
+const PROTOBUF = Symbol("otlp-protobuf");
+const MAX_DEPTH = 64;
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+class Reader {
+    bytes;
+    end;
+    pos;
+    constructor(bytes, start = 0, end = bytes.byteLength) {
+        this.bytes = bytes;
+        this.end = end;
+        this.pos = start;
+    }
+    get done() {
+        return this.pos >= this.end;
+    }
+    varint() {
+        let result = 0n;
+        for (let shift = 0n; shift < 70n; shift += 7n) {
+            if (this.pos >= this.end)
+                throw new ConversionError("a truncated protobuf varint");
+            const byte = this.bytes[this.pos++];
+            result |= BigInt(byte & 0x7f) << shift;
+            if (!(byte & 0x80))
+                return result & 0xffffffffffffffffn;
+        }
+        throw new ConversionError("a protobuf varint over ten bytes");
+    }
+    /** A varint that must fit a length or a small number. */
+    small() {
+        const value = this.varint();
+        if (value > BigInt(Number.MAX_SAFE_INTEGER))
+            throw new ConversionError("a protobuf length too large");
+        return Number(value);
+    }
+    fixed(size) {
+        if (this.pos + size > this.end)
+            throw new ConversionError("a truncated protobuf field");
+        const view = new DataView(this.bytes.buffer, this.bytes.byteOffset + this.pos, size);
+        this.pos += size;
+        return view;
+    }
+    /** A length-delimited field as its own reader. */
+    sub() {
+        const length = this.small();
+        if (this.pos + length > this.end)
+            throw new ConversionError("a truncated protobuf field");
+        const reader = new Reader(this.bytes, this.pos, this.pos + length);
+        this.pos += length;
+        return reader;
+    }
+    bytesField() {
+        const sub = this.sub();
+        return this.bytes.subarray(sub.pos, sub.end);
+    }
+    text() {
+        try {
+            return utf8.decode(this.bytesField());
+        }
+        catch (error) {
+            if (error instanceof ConversionError)
+                throw error;
+            throw new ConversionError("protobuf text that is not UTF-8");
+        }
+    }
+    skip(wire) {
+        if (wire === 0)
+            this.varint();
+        else if (wire === 1)
+            this.fixed(8);
+        else if (wire === 2)
+            this.sub();
+        else if (wire === 5)
+            this.fixed(4);
+        else
+            throw new ConversionError(`a protobuf field of wire type ${wire}`);
+    }
+    /** Reads every field, handing known field numbers to `read` with the wire type they require. */
+    fields(read) {
+        while (!this.done) {
+            const tag = this.small();
+            const field = Math.floor(tag / 8);
+            const wire = tag % 8;
+            if (field === 0)
+                throw new ConversionError("a protobuf field numbered zero");
+            const known = read[field];
+            if (!known)
+                this.skip(wire);
+            else if (known[0] !== wire)
+                throw new ConversionError(`protobuf field ${field} of the wrong wire type`);
+            else
+                known[1](this);
+        }
+    }
+}
+const hex = (bytes) => Buffer.from(bytes).toString("hex");
+const signed = (value) => (value >= 0x8000000000000000n ? value - 0x10000000000000000n : value).toString();
+function anyValue(reader, depth) {
+    if (depth > MAX_DEPTH)
+        throw new ConversionError("protobuf values nested too deep");
+    let value = {};
+    reader.fields({
+        1: [2, (r) => (value = { stringValue: r.text() })],
+        2: [0, (r) => (value = { boolValue: r.varint() !== 0n })],
+        3: [0, (r) => (value = { intValue: signed(r.varint()) })],
+        4: [1, (r) => (value = { doubleValue: r.fixed(8).getFloat64(0, true) })],
+        5: [
+            2,
+            (r) => {
+                const values = [];
+                r.sub().fields({ 1: [2, (item) => values.push(anyValue(item.sub(), depth + 1))] });
+                value = { arrayValue: { values } };
+            },
+        ],
+        6: [
+            2,
+            (r) => {
+                const values = [];
+                r.sub().fields({ 1: [2, (item) => values.push(keyValue(item.sub(), depth + 1))] });
+                value = { kvlistValue: { values } };
+            },
+        ],
+        7: [2, (r) => (value = { bytesValue: Buffer.from(r.bytesField()).toString("base64") })],
+    });
+    return value;
+}
+function keyValue(reader, depth = 0) {
+    let key = "";
+    let value = {};
+    reader.fields({
+        1: [2, (r) => (key = r.text())],
+        2: [2, (r) => (value = anyValue(r.sub(), depth + 1))],
+    });
+    return { key, value };
+}
+const attributeField = (into) => [
+    2,
+    (r) => into.push(keyValue(r.sub())),
+];
+/** Reads fields into an object, leaving out fields the message did not hold, empty lists
+ * included, as OTLP/JSON encoders do. */
+function message(reader, read) {
+    const out = {};
+    reader.fields(read(out));
+    for (const [key, value] of Object.entries(out))
+        if (Array.isArray(value) && !value.length)
+            delete out[key];
+    return out;
+}
+const fixed64 = (r) => r.fixed(8).getBigUint64(0, true).toString();
+const uint32 = (r) => Number(r.varint() & 0xffffffffn);
+function attributesInto(out, field) {
+    const list = [];
+    out[field] = list;
+    return list;
+}
+function span(reader) {
+    return message(reader, (out) => {
+        const attributes = attributesInto(out, "attributes");
+        const events = [];
+        const links = [];
+        out.events = events;
+        out.links = links;
+        return {
+            1: [2, (r) => (out.traceId = hex(r.bytesField()))],
+            2: [2, (r) => (out.spanId = hex(r.bytesField()))],
+            3: [2, (r) => (out.traceState = r.text())],
+            4: [
+                2,
+                (r) => {
+                    const parent = hex(r.bytesField());
+                    if (parent)
+                        out.parentSpanId = parent;
+                },
+            ],
+            5: [2, (r) => (out.name = r.text())],
+            6: [0, (r) => (out.kind = uint32(r))],
+            7: [1, (r) => (out.startTimeUnixNano = fixed64(r))],
+            8: [1, (r) => (out.endTimeUnixNano = fixed64(r))],
+            9: attributeField(attributes),
+            10: [0, (r) => (out.droppedAttributesCount = uint32(r))],
+            11: [
+                2,
+                (r) => events.push(message(r.sub(), (event) => {
+                    const list = attributesInto(event, "attributes");
+                    return {
+                        1: [1, (item) => (event.timeUnixNano = fixed64(item))],
+                        2: [2, (item) => (event.name = item.text())],
+                        3: attributeField(list),
+                        4: [0, (item) => (event.droppedAttributesCount = uint32(item))],
+                    };
+                })),
+            ],
+            12: [0, (r) => (out.droppedEventsCount = uint32(r))],
+            13: [
+                2,
+                (r) => links.push(message(r.sub(), (link) => {
+                    const list = attributesInto(link, "attributes");
+                    return {
+                        1: [2, (item) => (link.traceId = hex(item.bytesField()))],
+                        2: [2, (item) => (link.spanId = hex(item.bytesField()))],
+                        3: [2, (item) => (link.traceState = item.text())],
+                        4: attributeField(list),
+                        5: [0, (item) => (link.droppedAttributesCount = uint32(item))],
+                        6: [5, (item) => (link.flags = item.fixed(4).getUint32(0, true))],
+                    };
+                })),
+            ],
+            14: [0, (r) => (out.droppedLinksCount = uint32(r))],
+            15: [
+                2,
+                (r) => (out.status = message(r.sub(), (status) => ({
+                    2: [2, (item) => (status.message = item.text())],
+                    3: [0, (item) => (status.code = uint32(item))],
+                }))),
+            ],
+            16: [5, (r) => (out.flags = r.fixed(4).getUint32(0, true))],
+        };
+    });
+}
+/** A span the message holds, or why it cannot be read and the trace it names when its trace id
+ * was read before the damage. */
+function readSpan(reader, index, refused) {
+    const start = reader.pos;
+    try {
+        return span(reader);
+    }
+    catch (error) {
+        if (!(error instanceof ConversionError))
+            throw error;
+        let traceId;
+        try {
+            new Reader(reader.bytes, start, reader.end).fields({
+                1: [2, (field) => (traceId ??= hex(field.bytesField()))],
+            });
+        }
+        catch {
+            // The trace id came before the damage, or the span names none.
+        }
+        refused.push({
+            ...(traceId ? { traceId } : {}),
+            reason: `span ${index} is not an OTLP span: ${error.message}`,
+        });
+        return undefined;
+    }
+}
+/** A `TracesData` or `ExportTraceServiceRequest` (the same fields) as OTLP/JSON, with the spans
+ * that could not be read. */
+export function decodeTraces(bytes) {
+    const resourceSpans = [];
+    const refused = [];
+    let spanCount = 0;
+    new Reader(bytes).fields({
+        1: [
+            2,
+            (r) => resourceSpans.push(message(r.sub(), (group) => {
+                const scopeSpans = [];
+                group.scopeSpans = scopeSpans;
+                return {
+                    1: [
+                        2,
+                        (item) => (group.resource = message(item.sub(), (resource) => {
+                            const list = attributesInto(resource, "attributes");
+                            return {
+                                1: attributeField(list),
+                                2: [0, (value) => (resource.droppedAttributesCount = uint32(value))],
+                            };
+                        })),
+                    ],
+                    2: [
+                        2,
+                        (item) => scopeSpans.push(message(item.sub(), (scopeGroup) => {
+                            const spans = [];
+                            scopeGroup.spans = spans;
+                            return {
+                                1: [
+                                    2,
+                                    (value) => (scopeGroup.scope = message(value.sub(), (scope) => {
+                                        const list = attributesInto(scope, "attributes");
+                                        return {
+                                            1: [2, (field) => (scope.name = field.text())],
+                                            2: [2, (field) => (scope.version = field.text())],
+                                            3: attributeField(list),
+                                            4: [0, (field) => (scope.droppedAttributesCount = uint32(field))],
+                                        };
+                                    })),
+                                ],
+                                2: [
+                                    2,
+                                    (value) => {
+                                        const read = readSpan(value.sub(), ++spanCount, refused);
+                                        if (read)
+                                            spans.push(read);
+                                    },
+                                ],
+                                3: [2, (value) => (scopeGroup.schemaUrl = value.text())],
+                            };
+                        })),
+                    ],
+                    3: [2, (item) => (group.schemaUrl = item.text())],
+                };
+            })),
+        ],
+    });
+    return { request: { resourceSpans }, refused };
+}
+const ZSTD = [0x28, 0xb5, 0x2f, 0xfd];
+const isZstd = (bytes) => ZSTD.every((byte, index) => bytes[index] === byte);
+/** Whether bytes cannot be JSON text: JSON holds no raw control character but tab, line feed
+ * and carriage return, while protobuf ids, timestamps and length prefixes are full of them. */
+function binary(bytes) {
+    for (const byte of bytes)
+        if (byte < 0x20 && byte !== 0x09 && byte !== 0x0a && byte !== 0x0d)
+            return true;
+    return false;
+}
+/** A decoded request as a value; its JSON text is made only when a format asks for it. */
+function decoded(traces, line) {
+    let text;
+    return {
+        value: { [PROTOBUF]: traces },
+        get text() {
+            return (text ??= JSON.stringify(traces.request));
+        },
+        unsafeIntegers: false,
+        ...(line !== undefined ? { line } : {}),
+    };
+}
+/** One length-prefixed message's bytes, a zstd message decompressed. `budget` is what the file
+ * may still decompress to. */
+function frameBytes(frame, budget) {
+    let bytes = frame;
+    if (isZstd(frame)) {
+        if (typeof zlib.zstdDecompressSync !== "function")
+            throw new ConversionError("a zstd message, which this Node.js cannot decompress (Node.js 22.15 or later can)");
+        try {
+            bytes = zlib.zstdDecompressSync(frame, { maxOutputLength: Math.max(0, budget) });
+        }
+        catch (error) {
+            if (error instanceof RangeError ||
+                error?.code === "ERR_BUFFER_TOO_LARGE")
+                throw new Oversized();
+            throw new ConversionError("a damaged zstd message");
+        }
+    }
+    if (bytes.byteLength > budget)
+        throw new Oversized();
+    return bytes;
+}
+/** One message read: protobuf, or OTLP/JSON that a zstd message held. */
+function messageValue(bytes, zstd, line) {
+    if (zstd &&
+        !binary(bytes) &&
+        /^\s*\{/.test(Buffer.from(bytes.subarray(0, 64)).toString("utf8"))) {
+        let text;
+        try {
+            text = utf8.decode(bytes);
+        }
+        catch {
+            throw new ConversionError("a JSON message that is not UTF-8");
+        }
+        try {
+            const parsed = parseJsonText(text.trim());
+            return { value: parsed.value, text, unsafeIntegers: parsed.unsafeIntegers, line };
+        }
+        catch {
+            throw new ConversionError("a message that is not JSON");
+        }
+    }
+    return decoded(decodeTraces(bytes), line);
+}
+/** The file's messages together decompress past the bound of one file. */
+class Oversized extends Error {
+}
+/**
+ * The values of a binary OTLP file; undefined when the content is not binary or holds neither
+ * form, so that it is read as text; or why a binary OTLP request cannot be read. In a
+ * length-prefixed file each message is one value, its 1-based position given as its line; a
+ * message that cannot be read is reported with that position and the rest are read, until the
+ * messages together decompress to more than `maxBytes`.
+ */
+export function binaryValues(bytes, maxBytes) {
+    if (!binary(bytes))
+        return undefined;
+    let requestError;
+    if (bytes[0] === 0x0a)
+        try {
+            const value = decoded(decodeTraces(bytes));
+            return { values: [value], problems: [], bytes: () => bytes.byteLength };
+        }
+        catch (error) {
+            if (!(error instanceof ConversionError))
+                throw error;
+            // Not one message: perhaps length-prefixed messages.
+            requestError = error.message;
+        }
+    const frames = [];
+    let pos = 0;
+    let truncated = false;
+    while (pos < bytes.byteLength) {
+        if (pos + 4 > bytes.byteLength) {
+            truncated = true;
+            break;
+        }
+        const length = new DataView(bytes.buffer, bytes.byteOffset + pos, 4).getUint32(0, false);
+        if (pos + 4 + length > bytes.byteLength) {
+            truncated = true;
+            break;
+        }
+        frames.push(bytes.subarray(pos + 4, pos + 4 + length));
+        pos += 4 + length;
+    }
+    if (!frames.length)
+        return requestError === undefined
+            ? undefined
+            : { unsupported: `not an OTLP trace request: ${requestError}` };
+    const problems = [];
+    let total = 0;
+    function* values() {
+        for (const [index, frame] of frames.entries()) {
+            // A message counts what it decompressed to, whether or not it then reads.
+            let size = frame.byteLength;
+            try {
+                const bytes = frameBytes(frame, maxBytes - total);
+                size = bytes.byteLength;
+                const value = messageValue(bytes, isZstd(frame), index + 1);
+                total += size;
+                yield value;
+            }
+            catch (error) {
+                if (error instanceof Oversized) {
+                    problems.push({
+                        line: index + 1,
+                        reason: `the messages decompress to more than ${maxBytes} bytes; this message and the ${frames.length - index - 1} after it were not read`,
+                    });
+                    return;
+                }
+                if (!(error instanceof ConversionError))
+                    throw error;
+                total += size;
+                problems.push({ line: index + 1, reason: `not an OTLP trace message: ${error.message}` });
+            }
+        }
+        if (truncated)
+            problems.push({ line: frames.length + 1, reason: "a truncated length-prefixed message" });
+    }
+    return { values: values(), problems, bytes: () => Math.max(total, bytes.byteLength) };
+}
+export const otlpProtobuf = {
+    id: "otlp_protobuf",
+    manifestFormat: "otlp_json",
+    detect: (value) => isObject(value) && PROTOBUF in value,
+    convert(value, context) {
+        const traces = isObject(value) && PROTOBUF in value ? value[PROTOBUF] : undefined;
+        if (!traces)
+            return;
+        const collector = context.collector(() => new OtlpTraceCollector(), OTLP_SPANS);
+        // A span that could not be decoded refuses its trace, as a malformed OTLP/JSON span does.
+        for (const problem of traces.refused) {
+            const refusal = collector.refuse(problem.traceId, problem.reason);
+            context.refuse(refusal.reason, refusal.traceId);
+        }
+        for (const refusal of collector.add([traces.request], context.source.digest, otlpProtobuf.id))
+            context.refuse(refusal.reason, refusal.traceId);
+    },
+};

package/dist/cli/import-formats/otlp.d.ts

@@ -0,0 +1,4 @@
+import type { ImportAdapter } from "./adapter.js";
+/** OTLP/JSON trace exports (`{"resourceSpans": […]}`, proto field names too): spans kept as
+ * recorded, gathered by trace across files and lines, and with binary OTLP and Jaeger API v3. */
+export declare const otlpJson: ImportAdapter;

package/dist/cli/import-formats/otlp.js

@@ -0,0 +1,15 @@
+import { isObject, OTLP_SPANS, OtlpTraceCollector } from "../traces-import-convert.js";
+/** OTLP/JSON trace exports (`{"resourceSpans": […]}`, proto field names too): spans kept as
+ * recorded, gathered by trace across files and lines, and with binary OTLP and Jaeger API v3. */
+export const otlpJson = {
+    id: "otlp_json",
+    manifestFormat: "otlp_json",
+    detect: (value) => isObject(value) && (Array.isArray(value.resourceSpans) || Array.isArray(value.resource_spans)),
+    convert(value, context) {
+        if (!isObject(value))
+            return;
+        const collector = context.collector(() => new OtlpTraceCollector(), OTLP_SPANS);
+        for (const refusal of collector.add([value], context.source.digest, otlpJson.id))
+            context.refuse(refusal.reason, refusal.traceId);
+    },
+};

package/dist/cli/import-formats/phoenix.d.ts

@@ -0,0 +1,3 @@
+import type { ImportAdapter } from "./adapter.js";
+export declare const phoenixOtlp: ImportAdapter;
+export declare const phoenixSpans: ImportAdapter;