@hue-run/sdk 0.1.4 → 0.1.5

package/dist/privacy.js

@@ -1,5 +1,5 @@
 import { resourceFromAttributes } from "@opentelemetry/resources";
-import { MAX_CONTENT_BYTES } from "./config.js";
+import { MAX_BODY_BYTES, MAX_CONTENT_BYTES } from "./config.js";
 const contentPrefixes = [
     "gen_ai.input.messages",
     "gen_ai.output.messages",
@@ -38,45 +38,62 @@ const contentPrefixes = [
 function isContentKey(key) {
     return contentPrefixes.some((prefix) => key === prefix || key.startsWith(`${prefix}.`));
 }
-function redactValue(value, path, options, depth = 0) {
-    if (depth > 32)
+function redactValue(value, path, options, budget, depth = 0) {
+    if (++budget.nodes > 16384 || depth > 32)
         throw new Error("Telemetry value exceeds the supported nesting limit");
     if (typeof value === "string") {
         const result = options.redact ? options.redact(value, path) : value;
-        if (typeof result !== "string" || !result.isWellFormed() || result.includes("\u0000"))
+        // JavaScript can supply an async redactor despite the synchronous contract.
+        // Observe its rejection before dropping the invalid record.
+        if (result && typeof result === "object")
+            void Promise.resolve(result).catch(() => { });
+        if (typeof result !== "string" ||
+            result.length > MAX_CONTENT_BYTES ||
+            !result.isWellFormed() ||
+            result.includes("\u0000"))
             throw new Error("Redaction produced unsupported text");
         if (Buffer.byteLength(result) > MAX_CONTENT_BYTES)
             throw new Error("Telemetry text exceeds 256 KiB");
+        budget.bytes += Buffer.byteLength(result);
+        if (budget.bytes > MAX_BODY_BYTES)
+            throw new Error("Redacted record exceeds the content budget");
         return result;
     }
-    if (Array.isArray(value))
-        return value.map((item, index) => redactValue(item, `${path}.${index}`, options, depth + 1));
+    if (Array.isArray(value)) {
+        if (value.length > 16384)
+            throw new Error("Telemetry array exceeds the complexity limit");
+        return value.map((item, index) => redactValue(item, `${path}.${index}`, options, budget, depth + 1));
+    }
     if (value instanceof Uint8Array) {
         if (value.byteLength > MAX_CONTENT_BYTES)
             throw new Error("Telemetry bytes exceed 256 KiB");
+        budget.bytes += value.byteLength;
+        if (budget.bytes > MAX_BODY_BYTES)
+            throw new Error("Redacted record exceeds the content budget");
         return value;
     }
     if (value !== null && typeof value === "object")
         return Object.fromEntries(Object.entries(value).map(([key, item]) => [
             key,
-            redactValue(item, `${path}.${key}`, options, depth + 1),
+            redactValue(item, `${path}.${key}`, options, budget, depth + 1),
         ]));
     return value;
 }
-function attributes(source, options, path) {
+function attributes(source, options, path, budget) {
     return Object.fromEntries(Object.entries(source).flatMap(([key, value]) => !options.captureContent && isContentKey(key)
         ? []
-        : [[key, redactValue(value, `${path}.${key}`, options)]]));
+        : [[key, redactValue(value, `${path}.${key}`, options, budget)]]));
 }
-function redactResource(resource, options, cache) {
+function redactResource(resource, options, cache, budget) {
     let result = cache.get(resource);
     if (!result) {
-        result = resourceFromAttributes(attributes(resource.attributes, options, "resource.attributes"), { schemaUrl: resource.schemaUrl });
+        result = resourceFromAttributes(attributes(resource.attributes, options, "resource.attributes", budget), { schemaUrl: resource.schemaUrl });
         cache.set(resource, result);
     }
     return result;
 }
 export function redactSpan(span, options, cache) {
+    const budget = { bytes: 0, nodes: 0 };
     return {
         name: span.name,
         kind: span.kind,
@@ -89,22 +106,22 @@ export function redactSpan(span, options, cache) {
         status: {
             code: span.status.code,
             ...(options.captureContent && span.status.message !== undefined
-                ? { message: String(redactValue(span.status.message, "status.message", options)) }
+                ? { message: String(redactValue(span.status.message, "status.message", options, budget)) }
                 : {}),
         },
-        attributes: attributes(span.attributes, options, "attributes"),
+        attributes: attributes(span.attributes, options, "attributes", budget),
         events: span.events
             .filter((event) => options.captureContent ||
             !/^gen_ai\.(?:system|user|assistant|tool|choice)/.test(event.name))
             .map((event) => ({
             ...event,
-            attributes: attributes(event.attributes ?? {}, options, `events.${event.name}`),
+            attributes: attributes(event.attributes ?? {}, options, `events.${event.name}`, budget),
         })),
         links: span.links.map((link) => ({
             ...link,
-            attributes: attributes(link.attributes ?? {}, options, "links.attributes"),
+            attributes: attributes(link.attributes ?? {}, options, "links.attributes", budget),
         })),
-        resource: redactResource(span.resource, options, cache),
+        resource: redactResource(span.resource, options, cache, budget),
         instrumentationScope: span.instrumentationScope,
         droppedAttributesCount: span.droppedAttributesCount,
         droppedEventsCount: span.droppedEventsCount,
@@ -112,7 +129,8 @@ export function redactSpan(span, options, cache) {
     };
 }
 export function redactLog(log, options, cache) {
-    const body = options.captureContent ? redactValue(log.body, "body", options) : undefined;
+    const budget = { bytes: 0, nodes: 0 };
+    const body = options.captureContent ? redactValue(log.body, "body", options, budget) : undefined;
     if (body !== undefined && Buffer.byteLength(JSON.stringify(body)) > MAX_CONTENT_BYTES)
         throw new Error("Telemetry log body exceeds 256 KiB");
     return {
@@ -123,13 +141,13 @@ export function redactLog(log, options, cache) {
         severityNumber: log.severityNumber,
         eventName: log.eventName,
         body: body,
-        attributes: attributes(log.attributes, options, "attributes"),
-        resource: redactResource(log.resource, options, cache),
+        attributes: attributes(log.attributes, options, "attributes", budget),
+        resource: redactResource(log.resource, options, cache, budget),
         instrumentationScope: {
             ...log.instrumentationScope,
             ...(log.instrumentationScope.attributes
                 ? {
-                    attributes: attributes(log.instrumentationScope.attributes, options, "scope.attributes"),
+                    attributes: attributes(log.instrumentationScope.attributes, options, "scope.attributes", budget),
                 }
                 : {}),
         },

package/dist/safety.d.ts

@@ -0,0 +1,8 @@
+import { type Span } from "@opentelemetry/api";
+import type { JsonValue } from "./types.js";
+export declare function noopSpan(): Span;
+export declare function safeSpan(source: Span, failed: () => void): Span;
+/** Validate a bounded data tree without invoking toJSON or property getters. */
+export declare function encodeContent(value: JsonValue): string;
+/** Bounded conservative accounting for the record data retained by our queue, not total process RSS. */
+export declare function estimateRecordBytes(value: unknown, limit: number): number;

package/dist/safety.js

@@ -0,0 +1,179 @@
+import { INVALID_SPAN_CONTEXT, trace } from "@opentelemetry/api";
+import { types as utilTypes } from "node:util";
+import { MAX_CONTENT_BYTES } from "./config.js";
+export function noopSpan() {
+    return trace.wrapSpanContext(INVALID_SPAN_CONTEXT);
+}
+/** Isolate the public Span interface without changing its fluent method contract. */
+class SafeSpan {
+    source;
+    failed;
+    constructor(source, failed) {
+        this.source = source;
+        this.failed = failed;
+    }
+    write(work) {
+        try {
+            const result = work();
+            // Broken/custom providers can return rejected promises from synchronous
+            // OTel methods. Observe them without awaiting on application code paths.
+            if (result && typeof result.then === "function")
+                void Promise.resolve(result).catch(this.failed);
+        }
+        catch {
+            this.failed();
+        }
+    }
+    spanContext() {
+        try {
+            const ids = this.source.spanContext();
+            if (!ids || typeof ids.traceId !== "string" || typeof ids.spanId !== "string")
+                throw new TypeError("Invalid span context");
+            return {
+                traceId: ids.traceId,
+                spanId: ids.spanId,
+                traceFlags: ids.traceFlags,
+                isRemote: ids.isRemote,
+                traceState: ids.traceState,
+            };
+        }
+        catch {
+            this.failed();
+            return INVALID_SPAN_CONTEXT;
+        }
+    }
+    isRecording() {
+        try {
+            return this.source.isRecording() === true;
+        }
+        catch {
+            this.failed();
+            return false;
+        }
+    }
+    setAttribute(...args) {
+        this.write(() => this.source.setAttribute(...args));
+        return this;
+    }
+    setAttributes(...args) {
+        this.write(() => this.source.setAttributes(...args));
+        return this;
+    }
+    addEvent(...args) {
+        this.write(() => this.source.addEvent(...args));
+        return this;
+    }
+    addLink(...args) {
+        this.write(() => this.source.addLink(...args));
+        return this;
+    }
+    addLinks(...args) {
+        this.write(() => this.source.addLinks(...args));
+        return this;
+    }
+    setStatus(...args) {
+        this.write(() => this.source.setStatus(...args));
+        return this;
+    }
+    updateName(...args) {
+        this.write(() => this.source.updateName(...args));
+        return this;
+    }
+    end(...args) {
+        this.write(() => this.source.end(...args));
+    }
+    recordException(...args) {
+        this.write(() => this.source.recordException(...args));
+    }
+}
+export function safeSpan(source, failed) {
+    return new SafeSpan(source, failed);
+}
+/** Validate a bounded data tree without invoking toJSON or property getters. */
+export function encodeContent(value) {
+    let nodes = 0;
+    let bytes = 0;
+    const ancestors = new Set();
+    const charge = (amount) => {
+        bytes += amount;
+        if (bytes > MAX_CONTENT_BYTES)
+            throw new RangeError("Content limit exceeded");
+    };
+    const visit = (item, depth) => {
+        if (++nodes > 16384 || depth > 32)
+            throw new RangeError("Content complexity limit exceeded");
+        if (typeof item === "string") {
+            if (item.length > MAX_CONTENT_BYTES)
+                throw new RangeError("Content limit exceeded");
+            charge(Buffer.byteLength(JSON.stringify(item)));
+            return item;
+        }
+        if (item === null || typeof item === "boolean" || typeof item === "number") {
+            if (typeof item === "number" && !Number.isFinite(item))
+                throw new TypeError("Invalid number");
+            charge(JSON.stringify(item).length);
+            return item;
+        }
+        if (!item || typeof item !== "object" || ancestors.has(item))
+            throw new TypeError("Invalid JSON");
+        // Even descriptor/prototype reads can execute application code on a Proxy.
+        // The native check also handles revoked proxies without invoking their traps.
+        if (utilTypes.isProxy(item))
+            throw new TypeError("JSON proxies are unsupported");
+        const array = Array.isArray(item);
+        if (!array && ![Object.prototype, null].includes(Object.getPrototypeOf(item)))
+            throw new TypeError("Expected JSON data");
+        ancestors.add(item);
+        charge(2);
+        const result = array ? [] : Object.create(null);
+        // Own descriptors avoid executing application accessors during capture.
+        const keys = array
+            ? Array.from({ length: Math.min(item.length, 16385) }, (_, i) => String(i))
+            : Object.keys(item);
+        if (keys.length > 16384)
+            throw new RangeError("Content complexity limit exceeded");
+        for (const key of keys) {
+            const descriptor = Object.getOwnPropertyDescriptor(item, key);
+            if (!descriptor || !("value" in descriptor))
+                throw new TypeError("Expected JSON data property");
+            charge(1 + (array ? 0 : Buffer.byteLength(JSON.stringify(key)) + 1));
+            const child = visit(descriptor.value, depth + 1);
+            if (array)
+                result.push(child);
+            else
+                result[key] = child;
+        }
+        ancestors.delete(item);
+        return result;
+    };
+    const encoded = JSON.stringify(visit(value, 0));
+    if (Buffer.byteLength(encoded) > MAX_CONTENT_BYTES)
+        throw new RangeError("Content limit exceeded");
+    return encoded;
+}
+/** Bounded conservative accounting for the record data retained by our queue, not total process RSS. */
+export function estimateRecordBytes(value, limit) {
+    let bytes = 0;
+    let nodes = 0;
+    const seen = new Set();
+    const visit = (item, depth) => {
+        if (++nodes > 16384 || depth > 32)
+            throw new RangeError("Telemetry complexity limit exceeded");
+        bytes += 16;
+        if (typeof item === "string")
+            bytes += item.length * 2;
+        else if (item instanceof Uint8Array)
+            bytes += item.byteLength;
+        else if (item && typeof item === "object" && !seen.has(item)) {
+            seen.add(item);
+            for (const [key, child] of Object.entries(item)) {
+                bytes += key.length * 2 + 16;
+                visit(child, depth + 1);
+            }
+        }
+        if (bytes > limit)
+            throw new RangeError("Telemetry byte limit exceeded");
+    };
+    visit(value, 0);
+    return bytes;
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,12 @@
+import type { ReadableSpan } from "@opentelemetry/sdk-trace";
+import type { ReadableLogRecord, ReadWriteLogRecord } from "@opentelemetry/sdk-logs";
+export declare function snapshotSpan(source: ReadableSpan, limit: number): {
+    record: ReadableSpan;
+    bytes: number;
+    unresolvedResource: boolean;
+};
+export declare function snapshotLog(source: ReadableLogRecord, limit: number): {
+    record: ReadWriteLogRecord;
+    bytes: number;
+    unresolvedResource: boolean;
+};

package/dist/snapshot.js

@@ -0,0 +1,196 @@
+import { createTraceState } from "@opentelemetry/api";
+import { types as utilTypes } from "node:util";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+const typedArrayByteLength = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), "byteLength").get;
+const typedArraySet = Uint8Array.prototype.set;
+/** Copies only exported data, with the same finite budget used for admission. */
+class Snapshot {
+    limit;
+    bytes = 512;
+    unresolvedResource = false;
+    nodes = 0;
+    ancestors = new Set();
+    copied = new Map();
+    constructor(limit) {
+        this.limit = limit;
+    }
+    charge(bytes) {
+        this.bytes += bytes;
+        if (this.bytes > this.limit)
+            throw new RangeError("Telemetry byte budget exceeded");
+    }
+    copy(value, depth = 0) {
+        if (++this.nodes > 16384 || depth > 32)
+            throw new RangeError("Telemetry complexity limit exceeded");
+        this.charge(16);
+        if (typeof value === "string") {
+            this.charge(value.length * 2);
+            return value;
+        }
+        if (value === null ||
+            value === undefined ||
+            typeof value === "boolean" ||
+            typeof value === "number")
+            return value;
+        if (typeof value !== "object")
+            throw new TypeError("Unsupported telemetry value");
+        if (utilTypes.isProxy(value))
+            throw new TypeError("Telemetry proxies are unsupported");
+        if (this.ancestors.has(value))
+            throw new TypeError("Cyclic telemetry value");
+        if (this.copied.has(value))
+            return this.copied.get(value);
+        if (utilTypes.isUint8Array(value)) {
+            // Own accessors/subclasses cannot disguise the retained byte count.
+            // A length-tracking SharedArrayBuffer view can grow on another thread
+            // after charging: keep the destination fixed and reject growth during
+            // the intrinsic copy instead of retaining an uncharged larger array.
+            const length = typedArrayByteLength.call(value);
+            this.charge(length);
+            const copy = new Uint8Array(length);
+            typedArraySet.call(copy, value);
+            this.copied.set(value, copy);
+            return copy;
+        }
+        const array = Array.isArray(value);
+        if (!array && ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+            throw new TypeError("Telemetry must contain data objects");
+        const copy = array ? [] : Object.create(null);
+        this.copied.set(value, copy);
+        this.ancestors.add(value);
+        if (array) {
+            if (value.length > 16384)
+                throw new RangeError("Telemetry complexity limit exceeded");
+            for (let index = 0; index < value.length; index++) {
+                const descriptor = Object.getOwnPropertyDescriptor(value, index);
+                if (descriptor && !("value" in descriptor))
+                    throw new TypeError("Telemetry accessors are unsupported");
+                copy.push(this.copy(descriptor?.value, depth + 1));
+            }
+        }
+        else {
+            for (const key in value) {
+                if (!Object.hasOwn(value, key))
+                    continue;
+                const descriptor = Object.getOwnPropertyDescriptor(value, key);
+                if (!descriptor || !("value" in descriptor))
+                    throw new TypeError("Telemetry accessors are unsupported");
+                this.charge(key.length * 2 + 16);
+                copy[key] = this.copy(descriptor.value, depth + 1);
+            }
+        }
+        this.ancestors.delete(value);
+        return copy;
+    }
+    context(source) {
+        if (!source)
+            return undefined;
+        const { traceState, ...context } = this.copy({
+            traceId: source.traceId,
+            spanId: source.spanId,
+            traceFlags: source.traceFlags,
+            isRemote: source.isRemote,
+            traceState: source.traceState?.serialize(),
+        });
+        return {
+            ...context,
+            ...(traceState !== undefined ? { traceState: createTraceState(traceState) } : {}),
+        };
+    }
+    resource(source) {
+        // Do not retain a detector promise or its mutable resource graph. Later
+        // records can include metadata once detection completes. The caller is
+        // informed if this record omits unresolved resource attributes.
+        this.unresolvedResource ||= source.asyncAttributesPending === true;
+        const attributes = Object.create(null);
+        const raw = source.getRawAttributes();
+        if (raw.length > 16384)
+            throw new RangeError("Resource complexity limit exceeded");
+        for (const [key, value] of raw) {
+            if (value && typeof value.then === "function") {
+                this.unresolvedResource = true;
+                continue;
+            }
+            if (value == null || Object.hasOwn(attributes, key))
+                continue;
+            this.charge(key.length * 2 + 16);
+            attributes[key] = this.copy(value);
+        }
+        return resourceFromAttributes(attributes, { schemaUrl: this.copy(source.schemaUrl) });
+    }
+}
+function contextReader(context) {
+    return () => context;
+}
+export function snapshotSpan(source, limit) {
+    const snapshot = new Snapshot(limit);
+    const context = snapshot.context(source.spanContext());
+    if (source.links.length > 16384)
+        throw new RangeError("Link complexity limit exceeded");
+    const links = source.links.map((link) => ({
+        context: snapshot.context(link.context),
+        attributes: snapshot.copy(link.attributes),
+        droppedAttributesCount: snapshot.copy(link.droppedAttributesCount),
+    }));
+    const record = {
+        ...snapshot.copy({
+            name: source.name,
+            kind: source.kind,
+            startTime: source.startTime,
+            endTime: source.endTime,
+            duration: source.duration,
+            ended: source.ended,
+            status: source.status,
+            attributes: source.attributes,
+            events: source.events,
+            instrumentationScope: source.instrumentationScope,
+            droppedAttributesCount: source.droppedAttributesCount,
+            droppedEventsCount: source.droppedEventsCount,
+            droppedLinksCount: source.droppedLinksCount,
+        }),
+        spanContext: contextReader(context),
+        parentSpanContext: snapshot.context(source.parentSpanContext),
+        links,
+        resource: snapshot.resource(source.resource),
+    };
+    return { record, bytes: snapshot.bytes, unresolvedResource: snapshot.unresolvedResource };
+}
+export function snapshotLog(source, limit) {
+    const snapshot = new Snapshot(limit);
+    // Only our batching processor sees this copy. Its writer methods deliberately
+    // cannot mutate the admitted snapshot or invalidate its charged byte count.
+    const record = {
+        ...snapshot.copy({
+            hrTime: source.hrTime,
+            hrTimeObserved: source.hrTimeObserved,
+            severityText: source.severityText,
+            severityNumber: source.severityNumber,
+            eventName: source.eventName,
+            body: source.body,
+            attributes: source.attributes,
+            instrumentationScope: source.instrumentationScope,
+            droppedAttributesCount: source.droppedAttributesCount,
+        }),
+        spanContext: snapshot.context(source.spanContext),
+        resource: snapshot.resource(source.resource),
+        setAttribute() {
+            return this;
+        },
+        setAttributes() {
+            return this;
+        },
+        setBody() {
+            return this;
+        },
+        setEventName() {
+            return this;
+        },
+        setSeverityNumber() {
+            return this;
+        },
+        setSeverityText() {
+            return this;
+        },
+    };
+    return { record, bytes: snapshot.bytes, unresolvedResource: snapshot.unresolvedResource };
+}

package/dist/transport.d.ts

@@ -22,6 +22,11 @@ export declare class HueTransport {
     private failed;
     private spans;
     private logs;
+    private pendingBytes;
+    private dropped;
+    private instrumentationFailures;
+    private diagnosticPending;
+    private lastDiagnosticAt;
     private traceExporter;
     private logExporter;
     private closed;
@@ -32,6 +37,7 @@ export declare class HueTransport {
     finish(signal: Signal, records: RecordValue[]): void;
     acceptedRecords(signal: Signal, count: number): void;
     issue(signal: Signal, kind: ExportIssue["kind"], count: number, message: string, status?: number): void;
+    instrumentationFailure(signal?: Signal): void;
     getReport(): ExportReport;
     getIssues(): ExportIssue[];
     /** Monotonic failure marker, retained even when the bounded issue history rolls over. */