@hue-run/sdk 0.16.0 → 0.17.0

package/dist/privacy.js

@@ -2,7 +2,7 @@ import { SpanStatusCode } from "@opentelemetry/api";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { MAX_CONTENT_BYTES, MAX_RECORD_NODES, REDACTION_CONTEXT_UNITS } from "./config.js";
 import { scrubToolCredentials, withToolCatalogSummary } from "./tool-definitions.js";
-import { hashInlineFiles, INLINE_FILE_LIMIT, isMessageKey } from "./inline-files.js";
+import { hashInlineFiles, mayInlineFiles } from "./inline-files.js";
 import { truncateUtf8 } from "./safety.js";
 export { truncateUtf8 };
 /** Attribute keys (and their dotted children) removed in metadata-only mode. */
@@ -142,18 +142,12 @@ function redactedText(value, path, options, cap) {
         throw new Error("Redaction produced unsupported text");
     return result;
 }
-/** Whether a recorded message's text may inline a file over the inline file limit. */
-function mayInlineFiles(key, text) {
-    return (isMessageKey(key) &&
-        text.length * 3 > INLINE_FILE_LIMIT &&
-        (text.includes('"blob"') || text.includes('"file"')));
-}
 /** Marks a value the upload step does not place. */
 const NOT_HELD = Symbol("not held");
 /**
  * One of a span's own attribute values, when its values may be uploaded: text through the
  * credential scrub and the redactor, whole, and collected when it is over the cap or may inline
- * a large file; bytes over the cap collected as they are. {@link NOT_HELD} for any other value,
+ * media; bytes over the cap collected as they are. {@link NOT_HELD} for any other value,
  * and for text the queue cut when the record was admitted, which is never the whole value.
  */
 function offloadValue(key, value, path, options, budget) {
@@ -168,7 +162,7 @@ function offloadValue(key, value, path, options, budget) {
     }
     if (typeof value !== "string")
         return NOT_HELD;
-    // Each large inline file the queue shrank to its digest is reported as not uploaded; what is
+    // Each inline media part the queue shrank to its digest is reported as not uploaded; what is
     // left of the message is placed like any other value, and reported too if it is cut.
     const digested = budget.digested?.get(key);
     const files = digested?.text === value ? digested.files : 0;
@@ -271,7 +265,7 @@ function attributes(source, options, path, budget, listPrefix = "", own = false)
         return [
             [
                 key,
-                redactValue(scrubToolCredentials(key, hashInlineFiles(key, value)), `${path}.${key}`, options, budget, 0, `${listPrefix}${key}`),
+                redactValue(scrubToolCredentials(key, own ? hashInlineFiles(key, value) : value), `${path}.${key}`, options, budget, 0, `${listPrefix}${key}`),
             ],
         ];
     }));

package/dist/safety.d.ts

@@ -1,6 +1,7 @@
 import { type Span } from "@opentelemetry/api";
 export declare function noopSpan(): Span;
 export declare function safeSpan(source: Span, failed: () => void): Span;
+export declare function spanSource(span: Span): Span;
 /** The bounds `encodeContent` enforces while it copies a value. */
 export interface EncodeLimits {
     bytes: number;

package/dist/safety.js

@@ -96,8 +96,14 @@ class SafeSpan {
         this.write(() => this.source.recordException(...args));
     }
 }
+const spanSources = new WeakMap();
 export function safeSpan(source, failed) {
-    return new SafeSpan(source, failed);
+    const span = new SafeSpan(source, failed);
+    spanSources.set(span, spanSource(source));
+    return span;
+}
+export function spanSource(span) {
+    return spanSources.get(span) ?? span;
 }
 /** One content attribute's bounds: the value cap, and as many values as the Python SDK's content
  * snapshot allows, so a structured value of small members is cut at the cap rather than refused

package/dist/snapshot.d.ts

@@ -1,5 +1,6 @@
 import type { ReadableSpan } from "@opentelemetry/sdk-trace";
 import type { ReadableLogRecord, ReadWriteLogRecord } from "@opentelemetry/sdk-logs";
+import { type MediaDigestMemo } from "./inline-files.js";
 /**
  * How a span's own values over the receiver's value cap are held whole for export to upload:
  * the cap, the bytes the held-value budget has left, and whether nothing else is held (a single
@@ -12,7 +13,7 @@ export interface HoldLimits {
     budget: number;
     first: boolean;
 }
-/** A span's own message whose large inline files shrank to their digest when it was queued: the
+/** A span's own message whose inline media shrank to their digest when it was queued: the
  * text queued, and how many files it lost. */
 export interface DigestedMessage {
     text: string;
@@ -20,7 +21,7 @@ export interface DigestedMessage {
 }
 /** What admission keeps of a record: its copy, the bytes charged for it, whether resource
  * attributes were still unresolved, the value strings it cut, the bytes of the values it held
- * whole for upload, and the span's own messages whose large inline files it shrank to their
+ * whole for upload, and the span's own messages whose inline media it shrank to their
  * digest (with how many files each). */
 export interface RecordSnapshot<T> {
     record: T;
@@ -29,6 +30,8 @@ export interface RecordSnapshot<T> {
     cut: ReadonlySet<string>;
     held: number;
     digested: ReadonlyMap<string, DigestedMessage>;
+    /** The span's own message attributes admission inspected or left to export to inspect. */
+    inspected: ReadonlySet<string>;
 }
-export declare function snapshotSpan(source: ReadableSpan, limit: number, captureContent?: boolean, valueUnits?: number, hold?: HoldLimits): RecordSnapshot<ReadableSpan>;
+export declare function snapshotSpan(source: ReadableSpan, limit: number, captureContent?: boolean, valueUnits?: number, hold?: HoldLimits, memo?: MediaDigestMemo): RecordSnapshot<ReadableSpan>;
 export declare function snapshotLog(source: ReadableLogRecord, limit: number, captureContent?: boolean, valueUnits?: number): RecordSnapshot<ReadWriteLogRecord>;

package/dist/snapshot.js

@@ -1,7 +1,7 @@
 import { createTraceState } from "@opentelemetry/api";
 import { types as utilTypes } from "node:util";
 import { resourceFromAttributes } from "@opentelemetry/resources";
-import { hashInlineFiles, INLINE_FILE_LIMIT, INLINE_FILE_TEXT_PER_RECORD, isMessageKey, } from "./inline-files.js";
+import { hashInlineFiles, hashNestedInlineFiles, INLINE_FILE_TEXT_PER_RECORD, MAX_INLINE_FILE_TEXT, isMessageKey, mayInlineFiles, } from "./inline-files.js";
 import { scrubsToolCredentials, scrubToolCredentials } from "./tool-definitions.js";
 import { MAX_RECORD_NODES } from "./config.js";
 import { truncatedMarker } from "./privacy.js";
@@ -30,6 +30,8 @@ class Snapshot {
     captureContent;
     valueUnits;
     hold;
+    memo;
+    traceId;
     bytes = 512;
     unresolvedResource = false;
     /** The value strings this snapshot cut to `valueUnits`; export recognizes them, so the
@@ -38,28 +40,36 @@ class Snapshot {
     nodes = 0;
     ancestors = new Set();
     copied = new Map();
+    attributesCopied = new Map();
+    ownAttributesCopied = new Map();
     hashed = new Map();
+    nestedHashed = new Map();
     inspected = 0;
     /** Bytes of values held whole for upload, charged to the held-value budget. */
     held = 0;
     /** Set while the span's own attributes are copied: only they may be held for upload. */
     own = false;
-    /** The span's own messages whose large inline files shrank to their digest when queued, by
+    /** The span's own messages whose inline media shrank to their digest when queued, by
      * attribute: the text queued (cut or not), and how many files it lost. */
     digested = new Map();
     /** How many files each message text {@link inlineFiles} hashed replaced by their digest. */
     hashedFiles = new Map();
+    /** The span's own message attributes inspected within the record's allowance, whether here or
+     * left to export for a message held whole: export inspects only these. */
+    inspectedKeys = new Set();
     /**
      * In metadata-only mode the recorded messages, which export strips, are not copied at all. A
      * value string (an attribute's, an event's or link's attribute's, a log body or a status
      * message) longer than `valueUnits` is cut to that length: export cuts it to the value cap
      * anyway, and charging it whole could drop the record before that cut ever ran.
      */
-    constructor(limit, captureContent = true, valueUnits = Infinity, hold) {
+    constructor(limit, captureContent = true, valueUnits = Infinity, hold, memo, traceId = "") {
         this.limit = limit;
         this.captureContent = captureContent;
         this.valueUnits = valueUnits;
         this.hold = hold;
+        this.memo = memo;
+        this.traceId = traceId;
     }
     /** Whether the held-value budget takes `bytes` more, charging them when it does. */
     holds(bytes) {
@@ -74,7 +84,7 @@ class Snapshot {
      * longer than the queued value length or bytes over the cap, within the held-value budget, and
      * a recorded message that may inline a large file kept as it is (export uploads the file).
      * Undefined for a value copied as before; text over the length the budget cannot hold is then
-     * cut and its large inline files shrink to their digest, as before uploads existed.
+     * cut and its inline media shrink to their digest, as before uploads existed.
      */
     heldValue(key, value) {
         if (!this.hold || !this.own)
@@ -86,9 +96,16 @@ class Snapshot {
                 if (this.bytes + fallback > this.limit || !this.holds(value.length * 2))
                     return undefined;
                 this.charge(fallback);
+                // Export parses the held message; its inspection allowance is taken here, in order.
+                if (value.length <= MAX_INLINE_FILE_TEXT &&
+                    mayInlineFiles(key, value) &&
+                    this.inspected + value.length <= INLINE_FILE_TEXT_PER_RECORD) {
+                    this.inspected += value.length;
+                    this.inspectedKeys.add(key);
+                }
                 return { value };
             }
-            // Within the queued length: a recorded message holding a large inline file is held whole
+            // Within the queued length: a recorded message holding an inline media part is held whole
             // for export to upload the file, within the held-value budget, and the queue is charged
             // its copy with the files as their digest, as before. Past the budget, the files shrink to
             // their digest when queued, as before uploads existed.
@@ -119,7 +136,12 @@ class Snapshot {
             throw new BudgetExceeded("Telemetry byte budget exceeded");
     }
     mark() {
-        return { bytes: this.bytes, nodes: this.nodes, copied: this.copied.size };
+        return {
+            bytes: this.bytes,
+            nodes: this.nodes,
+            copied: this.copied.size,
+            attributesCopied: this.attributesCopied.size,
+        };
     }
     /** Back to `mark`, forgetting the values copied since: a later copy must not reuse a partial
      * copy of an item that was left out. */
@@ -131,6 +153,10 @@ class Snapshot {
         for (const key of [...this.copied.keys()])
             if (index++ >= mark.copied)
                 this.copied.delete(key);
+        index = 0;
+        for (const key of [...this.attributesCopied.keys()])
+            if (index++ >= mark.attributesCopied)
+                this.attributesCopied.delete(key);
     }
     /**
      * As many of a span's newest `items` (its events or links) as the record's budget still holds,
@@ -163,7 +189,7 @@ class Snapshot {
         return { kept, dropped: count - kept.length };
     }
     /**
-     * An attribute map. A large inline file in a message attribute shrinks to its digest before it
+     * An attribute map. A inline media part in a message attribute shrinks to its digest before it
      * is charged: export replaces it anyway, and charging the file could drop the whole record.
      */
     attributes(value) {
@@ -179,22 +205,32 @@ class Snapshot {
             this.own = false;
         }
     }
-    /** A message attribute with its large inline files hashed. The same text is hashed once per
-     * record, and a record inspects at most {@link INLINE_FILE_TEXT_PER_RECORD} of it in all;
-     * beyond that, messages are charged as recorded. */
+    /** A message attribute with its inline media hashed. Own and nested attributes cache
+     * separately because small binary media stays inline only in nested attributes. A record
+     * inspects at most {@link INLINE_FILE_TEXT_PER_RECORD} code units in all; beyond that,
+     * messages are charged as recorded. */
     inlineFiles(key, value) {
-        // A UTF-16 unit is at most three UTF-8 bytes, so shorter text cannot hold a file to hash.
-        if (typeof value !== "string" || !isMessageKey(key) || value.length * 3 <= INLINE_FILE_LIMIT)
+        if (typeof value !== "string" ||
+            value.length > MAX_INLINE_FILE_TEXT ||
+            !mayInlineFiles(key, value))
             return value;
-        if (this.hashed.has(value))
-            return this.hashed.get(value);
+        const hashed = this.own ? this.hashed : this.nestedHashed;
+        if (hashed.has(value)) {
+            if (this.own)
+                this.inspectedKeys.add(key);
+            return hashed.get(value);
+        }
         if (this.inspected + value.length > INLINE_FILE_TEXT_PER_RECORD)
             return value;
         this.inspected += value.length;
+        if (this.own)
+            this.inspectedKeys.add(key);
         const count = { files: 0 };
-        const result = hashInlineFiles(key, value, count);
-        this.hashed.set(value, result);
-        if (count.files)
+        const result = this.own
+            ? hashInlineFiles(key, value, count, this.memo, this.traceId)
+            : hashNestedInlineFiles(key, value);
+        hashed.set(value, result);
+        if (this.own && count.files)
             this.hashedFiles.set(value, count.files);
         return result;
     }
@@ -266,8 +302,15 @@ class Snapshot {
             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);
+        // One object can be reused as own attributes, nested attributes and an ordinary log body.
+        // Their copies differ: only attributes inspect media, and only own attributes upload it.
+        const copies = shape === "attributes"
+            ? this.own
+                ? this.ownAttributesCopied
+                : this.attributesCopied
+            : this.copied;
+        if (copies.has(value))
+            return copies.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
@@ -277,14 +320,14 @@ class Snapshot {
             this.charge(length);
             const copy = new Uint8Array(length);
             typedArraySet.call(copy, value);
-            this.copied.set(value, copy);
+            copies.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);
+        copies.set(value, copy);
         this.ancestors.add(value);
         if (array) {
             if (value.length > MAX_RECORD_NODES)
@@ -316,7 +359,7 @@ class Snapshot {
                     ? this.scrubbedBeforeCut(key, this.inlineFiles(key, source))
                     : source, depth + 1, shape === "event" && key === "attributes" ? "attributes" : "value", content || shape === "attributes");
                 copy[key] = copied;
-                // A span's own message whose large inline files shrank to their digest is named as it
+                // A span's own message whose inline media shrank to their digest is named as it
                 // was queued, cut or not, so export reports each file as not uploaded.
                 const files = this.own && shape === "attributes" && typeof source === "string"
                     ? this.hashedFiles.get(source)
@@ -360,7 +403,7 @@ class Snapshot {
             if (value == null || Object.hasOwn(attributes, key))
                 continue;
             this.charge(key.length * 2 + 16);
-            attributes[key] = this.copy(this.scrubbedBeforeCut(key, value), 0, "value", true);
+            attributes[key] = this.copy(this.scrubbedBeforeCut(key, this.inlineFiles(key, value)), 0, "value", true);
         }
         return resourceFromAttributes(attributes, { schemaUrl: this.copy(source.schemaUrl) });
     }
@@ -368,8 +411,8 @@ class Snapshot {
 function contextReader(context) {
     return () => context;
 }
-export function snapshotSpan(source, limit, captureContent = true, valueUnits = Infinity, hold) {
-    const snapshot = new Snapshot(limit, captureContent, valueUnits, hold);
+export function snapshotSpan(source, limit, captureContent = true, valueUnits = Infinity, hold, memo) {
+    const snapshot = new Snapshot(limit, captureContent, valueUnits, hold, memo, source.spanContext().traceId);
     const context = snapshot.context(source.spanContext());
     const fields = snapshot.copy({
         name: source.name,
@@ -416,6 +459,7 @@ export function snapshotSpan(source, limit, captureContent = true, valueUnits =
         cut: snapshot.cut,
         held: snapshot.held,
         digested: snapshot.digested,
+        inspected: snapshot.inspectedKeys,
     };
 }
 export function snapshotLog(source, limit, captureContent = true, valueUnits = Infinity) {
@@ -462,5 +506,6 @@ export function snapshotLog(source, limit, captureContent = true, valueUnits = I
         cut: snapshot.cut,
         held: 0,
         digested: new Map(),
+        inspected: new Set(),
     };
 }

package/dist/transport.d.ts

@@ -79,11 +79,17 @@ export declare class HueTransport {
     private holdsReleased;
     private admissionCuts;
     private admissionDigests;
+    private admissionInspected;
     /** Uploads values over the inline limit apart from their spans; absent when disabled. */
     private uploader?;
     /** Bytes of values over the inline limit queued spans hold whole for upload, and each span's. */
     private heldBytes;
     private held;
+    private mediaMemo;
+    private media;
+    private mediaOwners;
+    private mediaTimer?;
+    private mediaFinalizer;
     private uploaded;
     private uploadFallbacks;
     constructor(options: HueOptions);
@@ -98,6 +104,11 @@ export declare class HueTransport {
     private announceLiveSpans;
     private stopLiveTimer;
     private stopLiveSpans;
+    private mediaIdentity;
+    private releaseMedia;
+    private protectMedia;
+    private releaseMediaIdentity;
+    private sweepMedia;
     /** Bounded: a trace whose root never arrives (an abandoned run) gives way to newer ones. */
     private countDropped;
     /** Cumulative counters and current queue gauges. */