@hue-run/sdk 0.1.4 → 0.2.0

package/dist/snapshot.js

@@ -0,0 +1,200 @@
+import { createTraceState } from "@opentelemetry/api";
+import { types as utilTypes } from "node:util";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+// Intrinsic accessors are captured once and invoked with an explicit receiver so a
+// hostile object cannot override them; the unbound reference is the point.
+// eslint-disable-next-line @typescript-eslint/unbound-method
+const typedArrayByteLength = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), "byteLength").get;
+// eslint-disable-next-line @typescript-eslint/unbound-method
+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

@@ -1,17 +1,35 @@
 import { type ReadableSpan, type SpanProcessor } from "@opentelemetry/sdk-trace";
 import { type LogRecordProcessor, type ReadableLogRecord } from "@opentelemetry/sdk-logs";
 import { validateOptions } from "./config.js";
-import type { ExportIssue, ExportReport, HueOptions, Signal } from "./types.js";
-type RecordValue = ReadableSpan | ReadableLogRecord;
+import type { ExportIssue, ExportReport, HueOptions } from "./types.js";
+/** A finished span or emitted log record as the OpenTelemetry SDK hands it to a processor. */
+export type RecordValue = ReadableSpan | ReadableLogRecord;
+/**
+ * Rejection of {@link HueClient.flush} and {@link HueClient.shutdown}: telemetry was not fully
+ * accepted. Carries sanitized counts only, never server response text or content.
+ */
 export declare class HueExportError extends Error {
+    /** Non-warning issues observed since the failing drain began. */
     readonly issues: ExportIssue[];
+    /** Cumulative counters and current gauges at the time of the failure. */
     readonly report: ExportReport;
-    constructor(issues: ExportIssue[], report: ExportReport);
+    constructor(
+    /** Non-warning issues observed since the failing drain began. */
+    issues: ExportIssue[], 
+    /** Cumulative counters and current gauges at the time of the failure. */
+    report: ExportReport);
 }
-/** Owned transport components; attach processors during provider construction. */
+/**
+ * Hue's export pipeline: OTLP/HTTP exporters behind bounded batch processors, with cumulative
+ * counters and a sanitized issue history. A client owns one; in attach mode the application attaches
+ * `spanProcessor` and `logRecordProcessor` to its own providers while constructing them.
+ */
 export declare class HueTransport {
+    /** Validated options with defaults applied; `baseUrl` is the origin. Not enumerable, so it does not leak the key when logged. */
     readonly options: ReturnType<typeof validateOptions>;
+    /** Span processor to attach to a tracer provider; a no-op when disabled. */
     readonly spanProcessor: SpanProcessor;
+    /** Log record processor to attach to a logger provider; a no-op when disabled. */
     readonly logRecordProcessor: LogRecordProcessor;
     private sequence;
     private observedSequence;
@@ -22,6 +40,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;
@@ -29,16 +52,31 @@ export declare class HueTransport {
     private flushPromise?;
     constructor(options: HueOptions);
     private enqueue;
-    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;
+    /** Cumulative counters and current queue gauges. */
     getReport(): ExportReport;
+    /** Copies of the latest 128 sanitized issues, oldest first. */
     getIssues(): ExportIssue[];
     /** Monotonic failure marker, retained even when the bounded issue history rolls over. */
     getFailureSequence(): number;
+    /**
+     * Waits for the processors' and exporters' in-flight work; drain the providers first.
+     *
+     * @throws HueExportError when a new non-warning issue was recorded since the previous observation.
+     */
     flush(): Promise<ExportReport>;
     private flushOnce;
+    /**
+     * Flushes and stops the processors; records emitted afterwards are dropped and counted. In attach
+     * mode call it after shutting down the application's providers.
+     *
+     * @throws HueExportError when the final flush observed new failures.
+     */
     shutdown(): Promise<ExportReport>;
 }
+/**
+ * Creates the export pipeline for attach mode; pass it with the application's providers to
+ * {@link createHue}. Validates options like an owned client.
+ *
+ * @throws TypeError for invalid options; see {@link createHue}.
+ */
 export declare function createHueTransport(options: HueOptions): HueTransport;
-export {};