Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(native): extract inline media from raw OTEL documents (#18219)

Valery Meleshkinca176937b385
diff --git a/packages/native/Cargo.lock b/packages/native/Cargo.lock
index 5f747ae826..91e5438c1e 100644
--- a/packages/native/Cargo.lock
+++ b/packages/native/Cargo.lock
@@ -2,6 +2,19 @@
# It is not intended for manual editing.
version = 4
+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if",
+ "getrandom 0.3.4",
+ "once_cell",
+ "version_check",
+ "zerocopy",
+]
+
[[package]]
name = "aho-corasick"
version = "1.1.5"
@@ -44,12 +57,39 @@ version = "1.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
[[package]]
name = "bitflags"
version = "2.13.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+[[package]]
+name = "bitvec"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddcec3d12c579d40898fe0a9a358a803c23e9c52ca3c425707f81c9436211837"
+dependencies = [
+ "funty",
+ "radium",
+ "tap",
+ "wyz",
+]
+
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
[[package]]
name = "bnum"
version = "0.13.0"
@@ -110,6 +150,16 @@ dependencies = [
"serde",
]
+[[package]]
+name = "cc"
+version = "1.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f74872d07caf508b30a21f6836e7d7016a2eaf7d9ff4f48deaa58cd8a0407630"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
[[package]]
name = "cfg-if"
version = "1.0.4"
@@ -186,6 +236,15 @@ dependencies = [
"unicode-segmentation",
]
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
[[package]]
name = "crossbeam-epoch"
version = "0.9.20"
@@ -207,12 +266,32 @@ version = "0.2.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
[[package]]
name = "ctor"
version = "1.0.13"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "914a755b7c2d4af2bdcff7ce1739e2db9a1b81a9b07123d8015786ae03c0980d"
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
[[package]]
name = "displaydoc"
version = "0.2.7"
@@ -236,6 +315,12 @@ version = "1.0.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aedcfb3409746eddb02b9e19ebda1c3394f759a152e48ee875a0844d1b955484"
+
[[package]]
name = "foldhash"
version = "0.2.0"
@@ -251,6 +336,12 @@ dependencies = [
"percent-encoding",
]
+[[package]]
+name = "funty"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6d5a32815ae3f33302d95fdcb2ce17862f8c65363dcfd29360480ba1001fc9c"
+
[[package]]
name = "futures"
version = "0.3.34"
@@ -339,6 +430,16 @@ dependencies = [
"slab",
]
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
[[package]]
name = "getrandom"
version = "0.2.17"
@@ -641,6 +742,19 @@ version = "1.0.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+[[package]]
+name = "jiter"
+version = "0.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc2f2b4e673d798b3dbad0af24bc23b92013e680a6b9ad300b4e5e52fafe0586"
+dependencies = [
+ "ahash",
+ "bitvec",
+ "lexical-parse-float",
+ "num-traits",
+ "smallvec",
+]
+
[[package]]
name = "js-sys"
version = "0.3.104"
@@ -656,12 +770,17 @@ dependencies = [
name = "langfuse-native"
version = "0.0.0"
dependencies = [
+ "aho-corasick",
+ "base64",
"bytes",
"chrono",
"clickhouse",
"clickhouse-types",
+ "getrandom 0.3.4",
"hdbscan-rs",
"holomap",
+ "jiter",
+ "memchr",
"metrics",
"metrics-exporter-dogstatsd",
"napi",
@@ -670,6 +789,9 @@ dependencies = [
"ndarray",
"proptest",
"rust_decimal",
+ "serde",
+ "serde_json",
+ "sha2",
"tracing",
"tracing-subscriber",
]
@@ -680,6 +802,31 @@ version = "1.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+[[package]]
+name = "lexical-parse-float"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52a9f232fbd6f550bc0137dcb5f99ab674071ac2d690ac69704593cb4abbea56"
+dependencies = [
+ "lexical-parse-integer",
+ "lexical-util",
+]
+
+[[package]]
+name = "lexical-parse-integer"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a7a039f8fb9c19c996cd7b2fcce303c1b2874fe1aca544edc85c4a5f8489b34"
+dependencies = [
+ "lexical-util",
+]
+
+[[package]]
+name = "lexical-util"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2604dd126bb14f13fb5d1bd6a66155079cb9fa655b37f875b3a742c705dbed17"
+
[[package]]
name = "libc"
version = "0.2.189"
@@ -1092,6 +1239,12 @@ version = "5.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+[[package]]
+name = "radium"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc33ff2d4973d518d823d61aa239014831e521c75da58e3df4840d3f47749d09"
+
[[package]]
name = "radix_trie"
version = "0.2.1"
@@ -1333,6 +1486,27 @@ dependencies = [
"zmij",
]
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+ "sha2-asm",
+]
+
+[[package]]
+name = "sha2-asm"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b845214d6175804686b2bd482bcffe96651bb2d1200742b712003504a2dac1ab"
+dependencies = [
+ "cc",
+]
+
[[package]]
name = "sharded-slab"
version = "0.1.7"
@@ -1342,6 +1516,12 @@ dependencies = [
"lazy_static",
]
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
[[package]]
name = "simba"
version = "0.10.2"
@@ -1421,6 +1601,12 @@ dependencies = [
"syn 3.0.4",
]
+[[package]]
+name = "tap"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369"
+
[[package]]
name = "thiserror"
version = "2.0.20"
@@ -1649,6 +1835,12 @@ version = "0.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
[[package]]
name = "want"
version = "0.3.1"
@@ -1796,6 +1988,15 @@ version = "0.6.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
+[[package]]
+name = "wyz"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05f360fc0b24296329c78fda852a1e9ae82de9cf7b27dae4b7f62f118f77b9ed"
+dependencies = [
+ "tap",
+]
+
[[package]]
name = "yoke"
version = "0.8.3"
diff --git a/packages/native/Cargo.toml b/packages/native/Cargo.toml
index 8028563f43..76dc2f7d3e 100644
--- a/packages/native/Cargo.toml
+++ b/packages/native/Cargo.toml
@@ -11,18 +11,26 @@ publish = false
crate-type = ["cdylib"]
[dependencies]
+aho-corasick = "1.1"
+base64 = "0.22"
bytes = "1"
chrono = { version = "0.4", default-features = false, features = ["alloc", "std"] }
clickhouse = { version = "=0.15.2", default-features = false }
clickhouse-types = "=0.1.3"
hdbscan-rs = { version = "=0.6.1", default-features = false }
+getrandom = "0.3"
+memchr = "2"
holomap = { version = "=0.3.0", default-features = false }
metrics = "0.24"
metrics-exporter-dogstatsd = "0.9"
napi = { version = "3", default-features = false, features = ["napi9"] }
napi-derive = "3"
ndarray = "0.16"
+jiter = { version = "=0.17.0", default-features = false }
rust_decimal = { version = "1.37.2", default-features = false, features = ["std"] }
+serde = "1"
+serde_json = { version = "1", features = ["float_roundtrip", "raw_value"] }
+sha2 = { version = "0.10", features = ["asm"] }
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
diff --git a/packages/native/index.d.ts b/packages/native/index.d.ts
index 6333e6e0be..15434691dc 100644
--- a/packages/native/index.d.ts
+++ b/packages/native/index.d.ts
@@ -1,5 +1,31 @@
/* auto-generated by NAPI-RS */
/* eslint-disable */
+export declare class EarlyOtelBatch {
+ /** Release this handle; pending reads retain ownership until they complete. */
+ dispose(): Promise<void>
+ /** Copy the compact document on libuv without consuming the batch's JSON. */
+ copyJsonBuffer(): Promise<Buffer>
+ /**
+ * Transfer the compact document to a Node Buffer without a UTF-8-to-JS-string copy.
+ * The Buffer finalizer owns the Rust allocation; only the batch's accounting is released
+ * here because Node now owns the allocation through that finalizer. Media metadata and
+ * source ranges remain owned by this batch for later reads.
+ */
+ takeJsonBuffer(): Buffer
+ get media(): Array<ExtractedOtelMedia>
+ /** Return the number of extracted media descriptors without materializing them in JavaScript. */
+ mediaCount(): number
+ /** Materialize a bounded page of descriptors for callers processing very large batches. */
+ mediaPage(offset: number, limit: number): Array<ExtractedOtelMedia>
+ /** Decode one media body. Callers control concurrency and the returned Buffer's lifetime. */
+ mediaBody(index: number): Promise<Buffer>
+ /**
+ * Read media text for the selected number of remaining JSON string layers.
+ * Omitting the count returns the exact spelling after parsing the outer document.
+ */
+ originalMedia(index: number, jsonLayers?: number | undefined | null): Promise<string>
+}
+
/** A snapshot of one finalized event row, retained until its JS handle and any encoder tasks drop it. */
export declare class PreparedEvent {
/**
@@ -12,6 +38,21 @@ export declare class PreparedEvent {
static columns(): Array<PreparedEventColumn>
}
+export declare class ValidatedOtelJson {
+ /**
+ * Return sanitized bytes only when malformed UTF-8 required replacement.
+ * Masking must see the same source as validation and media discovery.
+ */
+ normalizedBytes(): Buffer | null
+ /** Release a superseded masking input without waiting for the JS handle to be collected. */
+ dispose(): Promise<void>
+ /**
+ * Consume the validated input and create a batch, optionally extracting media.
+ * When `extract_media` is false, the batch retains the JSON without media discovery or hashing.
+ */
+ extract(extractMedia: boolean): Promise<EarlyOtelBatch>
+}
+
/**
* Fits topic clusters and a separate 2D display projection in memory.
* This is CPU-bound and synchronous; call it in a killable child process.
@@ -26,6 +67,17 @@ export declare function clusterTopicEmbeddings(embeddings: Array<Array<number>>,
*/
export declare function encodeClickhouseEvents(rows: PreparedEvent[], maxRowsPerBlock: number): Promise<NativeEventBlock[]>
+export interface ExtractedOtelMedia {
+ index: number
+ reference: string
+ contentType: string
+ sha256Hash: string
+ kind: string
+ originalByteLength: number
+ originalJsonDepth: number
+ originalHasJsonEscapes: boolean
+}
+
/**
* Hello-world entry point. It proves that the worker can load and call the
* addon and that native code reports through the same telemetry as the rest
@@ -91,3 +143,9 @@ export interface TopicClusteringSettings {
/** Number of neighboring samples, excluding the sample itself. */
minSamples: number
}
+
+/**
+ * Snapshot bytes once on the JS thread. Only Rust-owned memory reaches the validator task;
+ * retaining a mutable Node Buffer across an async read would not enforce that ownership.
+ */
+export declare function validateOtelJson(bytes: Buffer): Promise<ValidatedOtelJson>
diff --git a/packages/native/index.js b/packages/native/index.js
index fac7fc465e..9d1bf248db 100644
--- a/packages/native/index.js
+++ b/packages/native/index.js
@@ -700,8 +700,11 @@ if (!nativeBinding) {
}
module.exports = nativeBinding
+module.exports.EarlyOtelBatch = nativeBinding.EarlyOtelBatch
module.exports.PreparedEvent = nativeBinding.PreparedEvent
+module.exports.ValidatedOtelJson = nativeBinding.ValidatedOtelJson
module.exports.clusterTopicEmbeddings = nativeBinding.clusterTopicEmbeddings
module.exports.encodeClickhouseEvents = nativeBinding.encodeClickhouseEvents
module.exports.hello = nativeBinding.hello
module.exports.initTelemetry = nativeBinding.initTelemetry
+module.exports.validateOtelJson = nativeBinding.validateOtelJson
diff --git a/packages/native/proptest-regressions/otel_media/payload_tests.txt b/packages/native/proptest-regressions/otel_media/payload_tests.txt
new file mode 100644
index 0000000000..524a17de49
--- /dev/null
+++ b/packages/native/proptest-regressions/otel_media/payload_tests.txt
@@ -0,0 +1,8 @@
+# Seeds for failure cases proptest has generated in the past. It is
+# automatically read and these particular cases re-run before any
+# novel cases are generated.
+#
+# It is recommended to check this file in to source control so that
+# everyone who runs the test benefits from these saved cases.
+cc 69e3ccf362686bd62c55b9c8ca13cb5b3c3d814d668c4bf9ef0b2b0e909c1ec7 # shrinks to value = Object {"": Object {"": Array [Array [Array [Object {"": Number(-7.192824773711748e-238)}]]]}}
+cc 79f9322c97a64cd124d577c66a0538cd53cfda00e8077ff4137fda195f26259c # shrinks to suffix = "", payloads = [[0], [0], [0]], layers = 2
diff --git a/packages/native/src/lib.rs b/packages/native/src/lib.rs
index 4035a38ea4..94824e0868 100644
--- a/packages/native/src/lib.rs
+++ b/packages/native/src/lib.rs
@@ -8,12 +8,19 @@
/// Rust-only encoder for prepared v4 `events_full` rows.
pub mod native_codec;
mod native_js;
+mod native_memory;
pub(crate) mod native_schema;
+mod native_task;
+mod otel_input;
+mod otel_media;
+mod otel_media_task;
mod telemetry;
mod topics;
pub use topics::{cluster_topic_embeddings, TopicClusteringResult, TopicClusteringSettings};
+pub use otel_input::{validate_otel_json, EarlyOtelBatch, ValidatedOtelJson};
+
use std::sync::Arc;
use std::time::Duration;
@@ -98,8 +105,11 @@ impl Task for EncodeClickhouseEventsTask {
type JsValue = Vec<NativeEventBlock>;
fn compute(&mut self) -> Result<Self::Output> {
- native_codec::encode_v4_native_blocks(&self.rows, self.max_rows_per_block)
- .map_err(Error::from_reason)
+ std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+ native_codec::encode_v4_native_blocks(&self.rows, self.max_rows_per_block)
+ }))
+ .map_err(|_| Error::from_reason("native encoding task panicked"))?
+ .map_err(Error::from_reason)
}
fn resolve(&mut self, _env: Env, output: Self::Output) -> Result<Self::JsValue> {
diff --git a/packages/native/src/native_memory.rs b/packages/native/src/native_memory.rs
new file mode 100644
index 0000000000..fc408e5bbe
--- /dev/null
+++ b/packages/native/src/native_memory.rs
@@ -0,0 +1,97 @@
+//! V8 accounting that follows Rust ownership, including in-flight libuv tasks.
+
+use std::sync::{
+ atomic::{AtomicI64, Ordering},
+ Arc,
+};
+
+use napi::threadsafe_function::{ThreadsafeFunction, ThreadsafeFunctionCallMode};
+use napi::{Env, Result, Status};
+
+type MemoryAdjuster = ThreadsafeFunction<i64, (), (), Status, false, true>;
+
+pub(crate) struct NativeMemory {
+ bytes: AtomicI64,
+ adjust: Arc<MemoryAdjuster>,
+}
+
+impl NativeMemory {
+ pub(crate) fn new(env: &Env, bytes: usize) -> Result<Self> {
+ let adjust = memory_adjuster(env)?;
+ let bytes = bytes as i64;
+ let total = env.adjust_external_memory(bytes)?;
+ tracing::trace!(delta = bytes, total, "V8 external memory adjusted");
+ metrics::gauge!("langfuse.native.otel_media.retained_bytes").increment(bytes as f64);
+ Ok(Self {
+ bytes: AtomicI64::new(bytes),
+ adjust,
+ })
+ }
+
+ pub(crate) fn resize(&self, bytes: usize) {
+ let bytes = bytes as i64;
+ let previous = self.bytes.swap(bytes, Ordering::AcqRel);
+ self.adjust(bytes - previous);
+ }
+
+ pub(crate) fn release(&self, bytes: usize) {
+ let bytes = bytes as i64;
+ let previous = self.bytes.fetch_sub(bytes, Ordering::AcqRel);
+ debug_assert!(previous >= bytes);
+ self.adjust(-bytes);
+ }
+
+ fn adjust(&self, delta: i64) {
+ if delta == 0 {
+ return;
+ }
+ metrics::gauge!("langfuse.native.otel_media.retained_bytes").increment(delta as f64);
+ // Closing is expected once the environment stops accepting callbacks.
+ let status = self
+ .adjust
+ .call(delta, ThreadsafeFunctionCallMode::NonBlocking);
+ if status != Status::Ok && status != Status::Closing {
+ tracing::warn!(?status, "native external-memory adjustment failed");
+ }
+ }
+}
+
+impl Drop for NativeMemory {
+ fn drop(&mut self) {
+ let bytes = self.bytes.swap(0, Ordering::AcqRel);
+ self.adjust(-bytes);
+ }
+}
+
+fn memory_adjuster(env: &Env) -> Result<Arc<MemoryAdjuster>> {
+ // Share one adjuster per environment; worker threads must not retain or call Env directly.
+ if let Some(adjust) = env.get_instance_data::<Arc<MemoryAdjuster>>()? {
+ return Ok(Arc::clone(adjust));
+ }
+
+ // A weak callback does not keep Node alive. It marshals adjustments onto the
+ // JS thread even when the last Rust owner is dropped on a worker thread.
+ let callback = env.create_function_from_closure::<(), (), _>("nativeMemory", |_| Ok(()))?;
+ let adjust = Arc::new(
+ callback
+ .build_threadsafe_function::<i64>()
+ .weak::<true>()
+ .build_callback(|context| {
+ // Accounting failure must never turn a cleanup callback into
+ // an uncaught JavaScript exception.
+ match context.env.adjust_external_memory(context.value) {
+ Ok(total) => {
+ tracing::trace!(delta = context.value, total, "V8 external memory adjusted")
+ }
+ Err(error) => {
+ tracing::warn!(%error, "native external-memory adjustment failed")
+ }
+ }
+ Ok(())
+ })?,
+ );
+ env.set_instance_data(Arc::clone(&adjust), (), |context| {
+ drop(context.value);
+ })?;
+ Ok(adjust)
+}
diff --git a/packages/native/src/native_task.rs b/packages/native/src/native_task.rs
new file mode 100644
index 0000000000..461e5d00b5
--- /dev/null
+++ b/packages/native/src/native_task.rs
@@ -0,0 +1,64 @@
+//! Run owned Rust work on libuv and expose only the completed result to Node.
+
+use napi::bindgen_prelude::*;
+use napi::JsError;
+use std::panic::{catch_unwind, AssertUnwindSafe};
+
+pub(crate) type NativeResult<T> = Result<T, &'static str>;
+
+/// Preserve a native error code when constructing its JavaScript error on the JS thread.
+pub(crate) fn to_js_error(env: Env, error: Error<&'static str>) -> Error {
+ Error::from(JsError::from(error).into_unknown(env))
+}
+
+pub struct OwnedTask<T> {
+ work: Option<Box<dyn FnOnce() -> NativeResult<T> + Send>>,
+}
+
+impl<T: Send + ToNapiValue + TypeName + 'static> OwnedTask<T> {
+ pub(crate) fn new(work: impl FnOnce() -> NativeResult<T> + Send + 'static) -> Self {
+ Self {
+ work: Some(Box::new(work)),
+ }
+ }
+}
+
+impl<T: Send + ToNapiValue + TypeName + 'static> Task for OwnedTask<T> {
+ type Output = NativeResult<T>;
+ type JsValue = T;
+
+ fn compute(&mut self) -> Result<Self::Output> {
+ let work = self
+ .work
+ .take()
+ .ok_or_else(|| Error::from_reason("native task already executed"))?;
+ // libuv calls compute through an extern-C callback. Unwinding through
+ // that boundary aborts Node rather than rejecting the pending promise.
+ let result = catch_unwind(AssertUnwindSafe(work))
+ .unwrap_or_else(|_| Err(Error::new("ERR_NATIVE_PANIC", "native task panicked")));
+ Ok(result)
+ }
+
+ fn resolve(&mut self, env: Env, output: Self::Output) -> Result<T> {
+ // Construct the JS error here so Promise rejection preserves its custom code.
+ output.map_err(|error| to_js_error(env, error))
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn task_panics_become_errors_before_the_ffi_boundary() {
+ let mut task = OwnedTask::<()> {
+ work: Some(Box::new(|| panic!("invalid internal state"))),
+ };
+ let error = task
+ .compute()
+ .unwrap()
+ .expect_err("panic must reject the task");
+ assert_eq!(error.status, "ERR_NATIVE_PANIC");
+ assert_eq!(error.reason, "native task panicked");
+ }
+}
diff --git a/packages/native/src/otel_input.rs b/packages/native/src/otel_input.rs
new file mode 100644
index 0000000000..e23e1672d5
--- /dev/null
+++ b/packages/native/src/otel_input.rs
@@ -0,0 +1,305 @@
+//! Owned raw input and extracted-media handles shared by the TS and Rust paths.
+
+use std::sync::{Arc, Mutex};
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use crate::native_memory::NativeMemory;
+use crate::native_task::to_js_error;
+use crate::otel_media::{self, EarlyMediaResult, ExtractedMedia, ValidatedPayload};
+use crate::otel_media_task::OtelMediaTask;
+
+const MAX_MEDIA_PAGE: usize = 4_096;
+
+#[napi]
+pub struct ValidatedOtelJson {
+ payload: Option<(ValidatedPayload, NativeMemory)>,
+}
+
+#[napi]
+impl ValidatedOtelJson {
+ /// Return sanitized bytes only when malformed UTF-8 required replacement.
+ /// Masking must see the same source as validation and media discovery.
+ #[napi]
+ pub fn normalized_bytes(&self, env: Env) -> Result<Option<Buffer>> {
+ let (payload, _) = self.payload.as_ref().ok_or_else(|| {
+ to_js_error(
+ env,
+ Error::new(
+ "ERR_OTEL_CLOSED",
+ "OTEL input already extracted or disposed",
+ ),
+ )
+ })?;
+ Ok(payload
+ .normalized_bytes()
+ .map(|bytes| Buffer::from(bytes.to_vec())))
+ }
+
+ /// Release a superseded masking input without waiting for the JS handle to be collected.
+ #[napi(ts_return_type = "Promise<void>")]
+ pub fn dispose(&mut self) -> AsyncTask<OtelMediaTask<()>> {
+ let payload = self.payload.take();
+ OtelMediaTask::run("dispose", move || {
+ drop(payload);
+ Ok(())
+ })
+ }
+
+ /// Consume the validated input and create a batch, optionally extracting media.
+ /// When `extract_media` is false, the batch retains the JSON without media discovery or hashing.
+ #[napi(ts_return_type = "Promise<EarlyOtelBatch>")]
+ pub fn extract(&mut self, extract_media: bool) -> AsyncTask<OtelMediaTask<EarlyOtelBatch>> {
+ // Claim ownership before scheduling, so a later dispose cannot invalidate this task.
+ let payload = self.payload.take();
+ OtelMediaTask::run("extract", move || {
+ let (validated, memory) = payload.ok_or_else(|| {
+ Error::new(
+ "ERR_OTEL_CLOSED",
+ "OTEL input already extracted or disposed",
+ )
+ })?;
+ let result = if extract_media {
+ validated
+ .compact()
+ .map_err(|error| Error::new(error.code(), error.to_string()))?
+ } else {
+ let source = validated.into_source();
+ EarlyMediaResult {
+ compact_json: source,
+ media: Vec::new(),
+ }
+ };
+ let batch = ExtractedBatch {
+ json: Mutex::new(Some(String::from_utf8(result.compact_json).map_err(
+ |_| Error::new("ERR_OTEL_INTERNAL", "compacted JSON is not UTF-8"),
+ )?)),
+ media: result.media,
+ _memory: memory,
+ };
+ batch._memory.resize(batch.retained_bytes());
+ Ok(EarlyOtelBatch {
+ inner: Some(Arc::new(batch)),
+ })
+ })
+ }
+}
+
+pub(crate) struct ExtractedBatch {
+ pub(crate) json: Mutex<Option<String>>,
+ pub(crate) media: Vec<ExtractedMedia>,
+ _memory: NativeMemory,
+}
+
+impl ExtractedBatch {
+ fn retained_bytes(&self) -> usize {
+ let mut seen = std::collections::HashSet::new();
+ self.json
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner)
+ .as_ref()
+ .map_or(0, String::capacity)
+ + self.media.capacity() * std::mem::size_of::<ExtractedMedia>()
+ + self.media.iter().map(|media| media.retained_bytes(&mut seen)).sum::<usize>()
+ // Source-backed entries all share the batch's one source allocation.
+ + self.media.iter().find_map(ExtractedMedia::source_capacity).unwrap_or(0)
+ }
+
+ fn take_json(&self) -> std::result::Result<String, Error<&'static str>> {
+ self.json
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner)
+ .take()
+ .ok_or_else(|| Error::new("ERR_OTEL_JSON_CONSUMED", "OTEL JSON already consumed"))
+ }
+}
+
+#[napi]
+pub struct EarlyOtelBatch {
+ inner: Option<Arc<ExtractedBatch>>,
+}
+
+impl EarlyOtelBatch {
+ pub(crate) fn data(&self) -> std::result::Result<Arc<ExtractedBatch>, Error<&'static str>> {
+ self.inner
+ .as_ref()
+ .map(Arc::clone)
+ .ok_or_else(|| Error::new("ERR_OTEL_CLOSED", "OTEL input already disposed"))
+ }
+}
+
+fn media_descriptor(index: usize, media: &ExtractedMedia) -> ExtractedOtelMedia {
+ ExtractedOtelMedia {
+ index: index as u32,
+ reference: media.reference(),
+ content_type: media.metadata.content_type.clone(),
+ sha256_hash: media.metadata.sha256_hash.clone(),
+ kind: media.kind.as_str().to_owned(),
+ original_byte_length: media.original_byte_length() as f64,
+ original_json_depth: media.original_json_depth(),
+ original_has_json_escapes: media.original_has_json_escapes(),
+ }
+}
+
+#[napi(object)]
+pub struct ExtractedOtelMedia {
+ pub index: u32,
+ pub reference: String,
+ pub content_type: String,
+ pub sha256_hash: String,
+ pub kind: String,
+ pub original_byte_length: f64,
+ pub original_json_depth: u8,
+ pub original_has_json_escapes: bool,
+}
+
+#[napi]
+impl EarlyOtelBatch {
+ /// Release this handle; pending reads retain ownership until they complete.
+ #[napi(ts_return_type = "Promise<void>")]
+ pub fn dispose(&mut self) -> AsyncTask<OtelMediaTask<()>> {
+ let inner = self.inner.take();
+ OtelMediaTask::run("dispose", move || {
+ drop(inner);
+ Ok(())
+ })
+ }
+
+ /// Copy the compact document on libuv without consuming the batch's JSON.
+ #[napi(js_name = "copyJsonBuffer", ts_return_type = "Promise<Buffer>")]
+ pub fn copy_json_buffer(&self) -> AsyncTask<OtelMediaTask<Buffer>> {
+ let data = self.data();
+ OtelMediaTask::run("copy_json", move || {
+ let data = data.map_err(|error| Error::new("ERR_OTEL_CLOSED", error.reason))?;
+ let json = data
+ .json
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner);
+ let json = json.as_ref().ok_or_else(|| {
+ Error::new("ERR_OTEL_JSON_CONSUMED", "OTEL JSON already consumed")
+ })?;
+ Ok(Buffer::from(json.as_bytes().to_vec()))
+ })
+ }
+
+ /// Transfer the compact document to a Node Buffer without a UTF-8-to-JS-string copy.
+ /// The Buffer finalizer owns the Rust allocation; only the batch's accounting is released
+ /// here because Node now owns the allocation through that finalizer. Media metadata and
+ /// source ranges remain owned by this batch for later reads.
+ #[napi(js_name = "takeJsonBuffer", ts_return_type = "Buffer")]
+ pub fn take_json_buffer(&self, env: Env) -> Result<Buffer> {
+ let data = self.data().map_err(|error| to_js_error(env, error))?;
+ let json = data.take_json().map_err(|error| to_js_error(env, error))?;
+ let retained = json.capacity();
+ let result = Buffer::from(json.into_bytes());
+ data._memory.release(retained);
+ Ok(result)
+ }
+
+ #[napi(getter)]
+ pub fn media(&self, env: Env) -> Result<Vec<ExtractedOtelMedia>> {
+ Ok(self
+ .data()
+ .map_err(|error| to_js_error(env, error))?
+ .media
+ .iter()
+ .enumerate()
+ .map(|(index, media)| media_descriptor(index, media))
+ .collect())
+ }
+
+ /// Return the number of extracted media descriptors without materializing them in JavaScript.
+ #[napi]
+ pub fn media_count(&self, env: Env) -> Result<u32> {
+ let count = self
+ .data()
+ .map_err(|error| to_js_error(env, error))?
+ .media
+ .len();
+ u32::try_from(count)
+ .map_err(|_| Error::from_reason("media descriptor count exceeds UInt32"))
+ }
+
+ /// Materialize a bounded page of descriptors for callers processing very large batches.
+ #[napi]
+ pub fn media_page(&self, env: Env, offset: u32, limit: u32) -> Result<Vec<ExtractedOtelMedia>> {
+ let data = self.data().map_err(|error| to_js_error(env, error))?;
+ let offset = offset as usize;
+ let limit = limit as usize;
+ if limit == 0 || limit > MAX_MEDIA_PAGE {
+ return Err(Error::new(
+ Status::InvalidArg,
+ format!("media page limit must be between 1 and {MAX_MEDIA_PAGE}"),
+ ));
+ }
+ if offset > data.media.len() {
+ return Err(Error::new(
+ Status::InvalidArg,
+ "media page offset is beyond the descriptor count",
+ ));
+ }
+ let end = offset.saturating_add(limit).min(data.media.len());
+ Ok(data.media[offset..end]
+ .iter()
+ .enumerate()
+ .map(|(index, media)| media_descriptor(offset + index, media))
+ .collect())
+ }
+
+ /// Decode one media body. Callers control concurrency and the returned Buffer's lifetime.
+ #[napi(ts_return_type = "Promise<Buffer>")]
+ pub fn media_body(&self, index: u32) -> AsyncTask<OtelMediaTask<Buffer>> {
+ let inner = self.data();
+ OtelMediaTask::run("decode", move || {
+ let inner = inner.map_err(|error| Error::new("ERR_OTEL_CLOSED", error.reason))?;
+ let media = inner
+ .media
+ .get(index as usize)
+ .ok_or_else(|| Error::new("ERR_OTEL_MEDIA_INDEX", "unknown media index"))?;
+ media
+ .decode()
+ .map(Buffer::from)
+ .map_err(|error| Error::new("ERR_OTEL_MEDIA_DECODE", error.to_string()))
+ })
+ }
+
+ /// Read media text for the selected number of remaining JSON string layers.
+ /// Omitting the count returns the exact spelling after parsing the outer document.
+ #[napi(ts_return_type = "Promise<string>")]
+ pub fn original_media(
+ &self,
+ index: u32,
+ json_layers: Option<u32>,
+ ) -> AsyncTask<OtelMediaTask<String>> {
+ let inner = self.data();
+ OtelMediaTask::run("restore", move || {
+ let inner = inner.map_err(|error| Error::new("ERR_OTEL_CLOSED", error.reason))?;
+ inner
+ .media
+ .get(index as usize)
+ .ok_or_else(|| Error::new("ERR_OTEL_MEDIA_INDEX", "unknown media index"))?
+ .original_value_for_layers(json_layers)
+ .map_err(|error| Error::new("ERR_OTEL_MEDIA_DECODE", error.to_string()))
+ })
+ }
+}
+
+/// Snapshot bytes once on the JS thread. Only Rust-owned memory reaches the validator task;
+/// retaining a mutable Node Buffer across an async read would not enforce that ownership.
+#[napi(ts_return_type = "Promise<ValidatedOtelJson>")]
+pub fn validate_otel_json(
+ env: Env,
+ bytes: Buffer,
+) -> Result<AsyncTask<OtelMediaTask<ValidatedOtelJson>>> {
+ let bytes = bytes.to_vec();
+ let memory = NativeMemory::new(&env, bytes.capacity())?;
+ Ok(OtelMediaTask::run("validate", move || {
+ let payload = otel_media::validate(bytes)
+ .map_err(|error| Error::new(error.code(), error.to_string()))?;
+ memory.resize(payload.retained_bytes());
+ Ok(ValidatedOtelJson {
+ payload: Some((payload, memory)),
+ })
+ }))
+}
diff --git a/packages/native/src/otel_media/data_uri.rs b/packages/native/src/otel_media/data_uri.rs
new file mode 100644
index 0000000000..8c3f2e6bcb
--- /dev/null
+++ b/packages/native/src/otel_media/data_uri.rs
@@ -0,0 +1,110 @@
+//! Recognize base64 Data URI spans inside decoded strings.
+
+use std::ops::Range;
+
+use super::encoding::{
+ has_data_uri_boundary, is_base64_character, is_data_uri_terminator, is_valid_content_type,
+ is_valid_data_uri_parameters,
+};
+use super::rules::{is_supported_content_type, BASE64_MARKER, DATA_URI_PREFIX};
+
+pub(super) struct ParsedDataUri<'a> {
+ pub(super) start: usize,
+ pub(super) end: usize,
+ pub(super) valid: Option<&'a str>,
+}
+
+pub(super) fn parse_data_uri(value: &str, mut start: usize) -> Option<ParsedDataUri<'_>> {
+ let bytes = value.as_bytes();
+ let mut header_cursor = start + DATA_URI_PREFIX.len();
+ let marker_start = loop {
+ let Some(&byte) = bytes.get(header_cursor) else {
+ return Some(ParsedDataUri {
+ start,
+ end: bytes.len(),
+ valid: None,
+ });
+ };
+ if byte == b',' {
+ return Some(ParsedDataUri {
+ start,
+ end: header_cursor + 1,
+ valid: None,
+ });
+ }
+ if byte == b'd' && bytes[header_cursor..].starts_with(DATA_URI_PREFIX.as_bytes()) {
+ if has_data_uri_boundary(value, header_cursor) {
+ start = header_cursor;
+ }
+ header_cursor += DATA_URI_PREFIX.len();
+ continue;
+ }
+ if byte == b';' && bytes[header_cursor..].starts_with(BASE64_MARKER.as_bytes()) {
+ break header_cursor;
+ }
+ header_cursor += 1;
+ };
+ let after_prefix = start + DATA_URI_PREFIX.len();
+ let content_type_end = bytes
+ .get(after_prefix..marker_start)?
+ .iter()
+ .position(|byte| *byte == b';')
+ .map(|offset| after_prefix + offset)
+ .unwrap_or(marker_start);
+ let content_type = value.get(after_prefix..content_type_end)?;
+ let parameters = value.get(content_type_end..marker_start)?;
+ if !is_valid_content_type(content_type)
+ || !is_valid_data_uri_parameters(parameters)
+ || !is_supported_content_type(content_type)
+ {
+ return Some(ParsedDataUri {
+ start,
+ end: marker_start + BASE64_MARKER.len(),
+ valid: None,
+ });
+ }
+ let data_start = marker_start + BASE64_MARKER.len();
+ let mut end = data_start;
+ let mut padding = 0;
+ let mut valid = true;
+ while end < value.len() && is_base64_character(value.as_bytes()[end]) {
+ match value.as_bytes()[end] {
+ b'=' => {
+ padding += 1;
+ if padding > 2 {
+ valid = false;
+ }
+ }
+ _ if padding > 0 => valid = false,
+ _ => {}
+ }
+ end += 1;
+ }
+ if end < value.len() && !is_data_uri_terminator(value.as_bytes()[end]) {
+ valid = false;
+ }
+ let encoded = &value[data_start..end];
+ let valid = (valid && !encoded.is_empty() && encoded.len() % 4 != 1).then_some(content_type);
+ Some(ParsedDataUri { start, end, valid })
+}
+
+pub(super) fn find_data_uri_candidates(value: &str) -> Vec<(Range<usize>, &str)> {
+ let mut candidates = Vec::new();
+ let mut cursor = 0;
+ while let Some(relative) = value[cursor..].find(DATA_URI_PREFIX) {
+ let start = cursor + relative;
+ if !has_data_uri_boundary(value, start) {
+ cursor = start + DATA_URI_PREFIX.len();
+ continue;
+ }
+ let Some(candidate) = parse_data_uri(value, start) else {
+ cursor = start + DATA_URI_PREFIX.len();
+ continue;
+ };
+ if let Some(content_type) = candidate.valid {
+ candidates.push((candidate.start..candidate.end, content_type));
+ }
+ cursor = candidate.end.max(start + DATA_URI_PREFIX.len());
+ }
+ candidates
+}
diff --git a/packages/native/src/otel_media/encoding.rs b/packages/native/src/otel_media/encoding.rs
new file mode 100644
index 0000000000..b38de34429
--- /dev/null
+++ b/packages/native/src/otel_media/encoding.rs
@@ -0,0 +1,411 @@
+//! Byte encoding, Data URI syntax checks, and bounded hashing.
+
+use base64::engine::general_purpose::{GeneralPurpose, GeneralPurposeConfig};
+use base64::engine::{DecodePaddingMode, Engine};
+use sha2::{Digest, Sha256};
+
+use super::payload::{MediaDecodeError, MediaEncoding};
+use super::rules::BASE64_MARKER;
+
+// Match the existing Buffer/base64 decoder after the caller has validated the
+// character grammar: padding may be omitted or repeated, and trailing bits are
+// accepted.
+pub(super) const BASE64: GeneralPurpose = GeneralPurpose::new(
+ &base64::alphabet::STANDARD,
+ GeneralPurposeConfig::new()
+ .with_decode_padding_mode(DecodePaddingMode::Indifferent)
+ .with_decode_allow_trailing_bits(true),
+);
+
+pub(super) const BASE64_HASH_CHUNK_SIZE: usize = 16 * 1024;
+pub(super) const BASE64_HASH_DECODED_CHUNK_SIZE: usize = BASE64_HASH_CHUNK_SIZE / 4 * 3;
+
+pub(super) fn is_data_uri_terminator(byte: u8) -> bool {
+ matches!(
+ byte,
+ b'\t'
+ | b'\n'
+ | b'\r'
+ | b' '
+ | b'!'
+ | b'"'
+ | b'\''
+ | b')'
+ | b','
+ | b'.'
+ | b';'
+ | b'>'
+ | b'?'
+ | b']'
+ | b'}'
+ )
+}
+
+pub(super) fn is_base64_character(byte: u8) -> bool {
+ byte.is_ascii_alphanumeric() || matches!(byte, b'+' | b'/' | b'=')
+}
+
+pub(super) fn is_valid_content_type(value: &str) -> bool {
+ let mut pieces = value.split('/');
+ let Some(kind) = pieces.next() else {
+ return false;
+ };
+ let Some(subtype) = pieces.next() else {
+ return false;
+ };
+ pieces.next().is_none()
+ && !kind.is_empty()
+ && !subtype.is_empty()
+ && kind
+ .bytes()
+ .all(|byte| byte.is_ascii_alphanumeric() || b"!#$&^_.+-".contains(&byte))
+ && subtype
+ .bytes()
+ .all(|byte| byte.is_ascii_alphanumeric() || b"!#$&^_.+-".contains(&byte))
+}
+
+/// Validate the optional parameters between a Data URI media type and `;base64`.
+///
+/// Parameter names use token syntax and values must be non-empty and free of
+/// delimiters or whitespace. Malformed headers remain inline text.
+pub(super) fn is_valid_data_uri_parameters(value: &str) -> bool {
+ if value.is_empty() {
+ return true;
+ }
+ let bytes = value.as_bytes();
+ let mut cursor = 0;
+ while cursor < bytes.len() {
+ if bytes[cursor] != b';' {
+ return false;
+ }
+ cursor += 1;
+ let name_start = cursor;
+ while cursor < bytes.len()
+ && bytes[cursor] != b'='
+ && bytes[cursor] != b';'
+ && bytes[cursor] != b','
+ {
+ cursor += 1;
+ }
+ if cursor == name_start
+ || cursor >= bytes.len()
+ || bytes[cursor] != b'='
+ || !bytes[name_start..cursor]
+ .iter()
+ .all(|byte| byte.is_ascii_alphanumeric() || b"!#$&^_.+-".contains(byte))
+ {
+ return false;
+ }
+ cursor += 1;
+ let value_start = cursor;
+ while cursor < bytes.len() && bytes[cursor] != b';' {
+ cursor += 1;
+ }
+ if cursor == value_start
+ || bytes[value_start..cursor]
+ .iter()
+ .any(|byte| b",\t\n\r \"'<>[]{}".contains(byte))
+ // Use ECMAScript whitespace semantics for compatibility with the
+ // existing detector; Rust's `char::is_whitespace` differs here.
+ || value[value_start..cursor].chars().any(|character| {
+ matches!(character,
+ '\u{0009}'..='\u{000d}' | '\u{0020}' | '\u{00a0}' | '\u{1680}' |
+ '\u{2000}'..='\u{200a}' | '\u{2028}' | '\u{2029}' | '\u{202f}' |
+ '\u{205f}' | '\u{3000}' | '\u{feff}')
+ })
+ {
+ return false;
+ }
+ }
+ true
+}
+
+pub(super) fn has_data_uri_boundary(value: &str, start: usize) -> bool {
+ start == 0
+ || !value.as_bytes()[start - 1].is_ascii_alphanumeric()
+ && value.as_bytes()[start - 1] != b'-'
+ && value.as_bytes()[start - 1] != b'_'
+}
+
+pub(super) fn decode_python_bytes_literal(value: &[u8]) -> Result<Vec<u8>, MediaDecodeError> {
+ let mut output = Vec::with_capacity(value.len().saturating_sub(3));
+ visit_python_bytes_literal(value, |byte| output.push(byte))?;
+ Ok(output)
+}
+
+fn visit_python_bytes_literal(
+ value: &[u8],
+ mut visit_byte: impl FnMut(u8),
+) -> Result<(), MediaDecodeError> {
+ if value.len() < 3 || value[0] != b'b' || !matches!(value[1], b'\'' | b'"') {
+ return Err(MediaDecodeError::InvalidPythonBytes);
+ }
+ let quote = value[1];
+ if *value.last().unwrap_or(&0) != quote {
+ return Err(MediaDecodeError::InvalidPythonBytes);
+ }
+ let mut cursor = 2;
+ while cursor + 1 < value.len() {
+ let byte = value[cursor];
+ if byte != b'\\' {
+ // Python's bytes representation escapes non-ASCII/control bytes, and
+ // an unescaped delimiter cannot occur inside the literal.
+ if !(0x20..=0x7e).contains(&byte) || byte == quote {
+ return Err(MediaDecodeError::InvalidPythonBytes);
+ }
+ visit_byte(byte);
+ cursor += 1;
+ continue;
+ }
+ cursor += 1;
+ if cursor == value.len() - 1 {
+ return Err(MediaDecodeError::InvalidPythonBytes);
+ }
+ let Some(escaped) = value.get(cursor).copied() else {
+ return Err(MediaDecodeError::InvalidPythonBytes);
+ };
+ match escaped {
+ b'\\' | b'\'' | b'"' => visit_byte(escaped),
+ b'n' => visit_byte(b'\n'),
+ b'r' => visit_byte(b'\r'),
+ b't' => visit_byte(b'\t'),
+ b'x' => {
+ let Some(bytes) = value
+ .get(cursor + 1..cursor + 3)
+ .and_then(|bytes| bytes.first_chunk::<2>())
+ else {
+ return Err(MediaDecodeError::InvalidPythonBytes);
+ };
+ let Some(hi) = hex_digit(bytes[0]) else {
+ return Err(MediaDecodeError::InvalidPythonBytes);
+ };
+ let Some(lo) = hex_digit(bytes[1]) else {
+ return Err(MediaDecodeError::InvalidPythonBytes);
+ };
+ visit_byte((hi << 4) | lo);
+ cursor += 2;
+ }
+ _ => return Err(MediaDecodeError::InvalidPythonBytes),
+ }
+ cursor += 1;
+ }
+ Ok(())
+}
+
+/// Hash decoded media in bounded chunks. Discovery needs only the content ID;
+/// full decoding remains deferred to upload.
+pub(super) fn hash_encoded_data(
+ encoded_data: &[u8],
+ encoding: MediaEncoding,
+) -> Result<[u8; 32], MediaDecodeError> {
+ let mut hasher = Sha256::new();
+ match encoding {
+ MediaEncoding::Base64DataUri => {
+ hash_base64(&mut hasher, data_uri_payload(encoded_data)?)?;
+ }
+ MediaEncoding::Base64 => hash_base64(&mut hasher, encoded_data)?,
+ MediaEncoding::PythonBytesLiteral => hash_python_bytes_literal(&mut hasher, encoded_data)?,
+ }
+ Ok(hasher.finalize().into())
+}
+
+fn data_uri_payload(value: &[u8]) -> Result<&[u8], MediaDecodeError> {
+ let marker = value
+ .windows(BASE64_MARKER.len())
+ .position(|window| window == BASE64_MARKER.as_bytes())
+ .ok_or(MediaDecodeError::InvalidDataUri)?;
+ Ok(&value[marker + BASE64_MARKER.len()..])
+}
+
+/// Match `Buffer.from(..., "base64")` after syntax validation: remove redundant
+/// padding and ignore a lone final sextet that cannot produce a byte. The
+/// returned prefix is shared by hashing and upload decoding.
+fn node_base64_payload(mut value: &[u8]) -> Result<&[u8], MediaDecodeError> {
+ while value.last() == Some(&b'=') {
+ value = &value[..value.len() - 1];
+ }
+ if value.len() % 4 == 1 {
+ value = &value[..value.len() - 1];
+ }
+ // Empty decoded payloads are not media candidates.
+ if value.is_empty() {
+ return Err(MediaDecodeError::InvalidDataUri);
+ }
+ Ok(value)
+}
+
+fn hash_base64(hasher: &mut Sha256, value: &[u8]) -> Result<(), MediaDecodeError> {
+ let value = node_base64_payload(value)?;
+ // Keep chunks aligned to Base64 groups. The final chunk handles omitted
+ // padding and non-zero trailing bits.
+ let mut decoded = [0_u8; BASE64_HASH_DECODED_CHUNK_SIZE];
+ for chunk in value.chunks(BASE64_HASH_CHUNK_SIZE) {
+ let decoded_length = BASE64
+ .decode_slice(chunk, &mut decoded)
+ .map_err(MediaDecodeError::Base64Slice)?;
+ hasher.update(&decoded[..decoded_length]);
+ }
+ Ok(())
+}
+
+fn hash_python_bytes_literal(hasher: &mut Sha256, value: &[u8]) -> Result<(), MediaDecodeError> {
+ // Empty Python bytes are not media candidates.
+ if value.len() == 3 {
+ return Err(MediaDecodeError::InvalidPythonBytes);
+ }
+ let mut decoded = [0; BASE64_HASH_DECODED_CHUNK_SIZE];
+ let mut decoded_len = 0;
+ visit_python_bytes_literal(value, |byte| {
+ decoded[decoded_len] = byte;
+ decoded_len += 1;
+ if decoded_len == decoded.len() {
+ hasher.update(&decoded[..]);
+ decoded_len = 0;
+ }
+ })?;
+ hasher.update(&decoded[..decoded_len]);
+ Ok(())
+}
+
+pub(super) fn is_python_bytes_literal(value: &str) -> bool {
+ let bytes = value.as_bytes();
+ bytes.len() >= 3
+ && bytes[0] == b'b'
+ && matches!(bytes[1], b'\'' | b'"')
+ && bytes.last() == bytes.get(1)
+}
+
+pub(super) fn is_valid_base64_syntax(value: &[u8]) -> bool {
+ if value.is_empty() || value.len() % 4 == 1 {
+ return false;
+ }
+ let mut padding = 0;
+ for byte in value {
+ if *byte == b'=' {
+ padding += 1;
+ if padding > 2 {
+ return false;
+ }
+ } else if padding > 0 || !is_base64_character(*byte) {
+ return false;
+ }
+ }
+ true
+}
+
+pub(super) fn hex_digit(byte: u8) -> Option<u8> {
+ match byte {
+ b'0'..=b'9' => Some(byte - b'0'),
+ b'a'..=b'f' => Some(byte - b'a' + 10),
+ b'A'..=b'F' => Some(byte - b'A' + 10),
+ _ => None,
+ }
+}
+
+pub(super) fn decode_encoded_data(
+ encoded_data: &[u8],
+ encoding: MediaEncoding,
+) -> Result<Vec<u8>, MediaDecodeError> {
+ let value = match encoding {
+ MediaEncoding::Base64DataUri => data_uri_payload(encoded_data)?,
+ MediaEncoding::Base64 => encoded_data,
+ MediaEncoding::PythonBytesLiteral => return decode_python_bytes_literal(encoded_data),
+ };
+ BASE64
+ .decode(node_base64_payload(value)?)
+ .map_err(MediaDecodeError::Base64)
+}
+
+#[cfg(test)]
+mod tests {
+ use base64::Engine;
+ use proptest::prelude::*;
+ use sha2::{Digest, Sha256};
+
+ use super::{
+ decode_python_bytes_literal, hash_encoded_data, BASE64, BASE64_HASH_DECODED_CHUNK_SIZE,
+ };
+ use super::{MediaDecodeError, MediaEncoding};
+
+ #[test]
+ fn python_bytes_decoder_and_hasher_share_escape_validation() {
+ let encoded = br#"b"abc\n\r\t\\\'\"\x41""#;
+ let expected = b"abc\n\r\t\\'\"A";
+ let expected_hash: [u8; 32] = Sha256::digest(expected).into();
+ assert_eq!(decode_python_bytes_literal(encoded).unwrap(), expected);
+ assert_eq!(
+ hash_encoded_data(encoded, MediaEncoding::PythonBytesLiteral).unwrap(),
+ expected_hash
+ );
+
+ let malformed_single_quote = b"b'abc\\'";
+ let malformed_double_quote = b"b\"abc\\\"";
+ for invalid in [
+ b"b'bad\\q'".as_slice(),
+ b"b'bad\\x0'",
+ b"b'caf\xc3\xa9'",
+ malformed_single_quote.as_slice(),
+ malformed_double_quote.as_slice(),
+ ] {
+ assert!(matches!(
+ decode_python_bytes_literal(invalid),
+ Err(MediaDecodeError::InvalidPythonBytes)
+ ));
+ assert!(matches!(
+ hash_encoded_data(invalid, MediaEncoding::PythonBytesLiteral),
+ Err(MediaDecodeError::InvalidPythonBytes)
+ ));
+ }
+
+ let valid_single_quote = b"b'abc\\''";
+ let valid_double_quote = b"b\"abc\\\"\"";
+ for (literal, expected) in [
+ (valid_single_quote.as_slice(), b"abc'".as_slice()),
+ (valid_double_quote.as_slice(), b"abc\"".as_slice()),
+ ] {
+ let expected_hash: [u8; 32] = Sha256::digest(expected).into();
+ assert_eq!(decode_python_bytes_literal(literal).unwrap(), expected);
+ assert_eq!(
+ hash_encoded_data(literal, MediaEncoding::PythonBytesLiteral).unwrap(),
+ expected_hash
+ );
+ }
+ }
+
+ #[test]
+ fn hashes_large_python_bytes_literals_in_bounded_chunks() {
+ let decoded = vec![b'a'; BASE64_HASH_DECODED_CHUNK_SIZE + 17];
+ let mut encoded = Vec::with_capacity(decoded.len() + 3);
+ encoded.extend_from_slice(b"b'");
+ encoded.extend_from_slice(&decoded);
+ encoded.push(b'\'');
+ let expected_hash: [u8; 32] = Sha256::digest(&decoded).into();
+
+ assert_eq!(
+ hash_encoded_data(&encoded, MediaEncoding::PythonBytesLiteral).unwrap(),
+ expected_hash
+ );
+ }
+
+ proptest! {
+ #[test]
+ fn bounded_base64_hash_matches_decoded_content(bytes in prop_oneof![
+ prop::collection::vec(any::<u8>(), 1..4096),
+ prop::collection::vec(
+ any::<u8>(),
+ BASE64_HASH_DECODED_CHUNK_SIZE..(2 * BASE64_HASH_DECODED_CHUNK_SIZE + 17),
+ ),
+ ]) {
+ // Pin the first partial chunk as well as sampling arbitrary bodies and padding.
+ let boundary: [u8; BASE64_HASH_DECODED_CHUNK_SIZE + 1] =
+ std::array::from_fn(|index| index.wrapping_mul(31) as u8);
+ for bytes in [bytes.as_slice(), boundary.as_slice()] {
+ let encoded = BASE64.encode(bytes);
+ let expected: [u8; 32] = Sha256::digest(bytes).into();
+ prop_assert_eq!(hash_encoded_data(encoded.as_bytes(), MediaEncoding::Base64).unwrap(), expected);
+ let unpadded = encoded.trim_end_matches('=');
+ prop_assert_eq!(hash_encoded_data(unpadded.as_bytes(), MediaEncoding::Base64).unwrap(), expected);
+ }
+ }
+ }
+}
diff --git a/packages/native/src/otel_media/json.rs b/packages/native/src/otel_media/json.rs
new file mode 100644
index 0000000000..9ebc4f7024
--- /dev/null
+++ b/packages/native/src/otel_media/json.rs
@@ -0,0 +1,89 @@
+//! Shared JSON validation and string decoding.
+//!
+//! `validate_json` checks a complete document with Jiter, or borrowed serde
+//! `RawValue` when Jiter cannot read it; neither constructs objects or arrays.
+//! `decode_json_string` reads keys and provider labels for the structural walk.
+
+use std::borrow::Cow;
+use std::ops::Range;
+
+use jiter::Jiter;
+use serde::Deserialize;
+use serde_json::value::RawValue;
+
+use super::payload::EarlyMediaError;
+
+/// Validate one complete JSON value without building a JSON tree.
+///
+/// The fast path uses jiter's skip parser. If it cannot validate the input, the
+/// `RawValue` fallback checks a borrowed value instead of materializing a tree;
+/// neither path calls back into JavaScript.
+pub(super) fn validate_json(text: &str) -> Result<(), EarlyMediaError> {
+ let mut cursor = Jiter::new(text.as_bytes());
+ if cursor.next_skip().is_ok() && cursor.finish().is_ok() {
+ return Ok(());
+ }
+
+ // The input boundary has checked UTF-8. `RawValue` borrows from the string,
+ // so the fallback need not check UTF-8 or copy the whole input again.
+ let input = text.as_bytes();
+ let mut deserializer = serde_json::Deserializer::from_str(text);
+ let raw = <&RawValue>::deserialize(&mut deserializer).map_err(|error| {
+ EarlyMediaError::InvalidJson {
+ offset: serde_error_offset(input, &error),
+ message: "invalid JSON",
+ }
+ })?;
+
+ let value_start = skip_whitespace(input, 0);
+ let value_end = value_start + raw.get().len();
+ if skip_whitespace(input, value_end) != input.len() {
+ return Err(EarlyMediaError::TrailingBytes {
+ offset: skip_whitespace(input, value_end),
+ });
+ }
+ deserializer
+ .end()
+ .map_err(|error| EarlyMediaError::TrailingBytes {
+ offset: serde_error_offset(input, &error),
+ })
+}
+
+fn serde_error_offset(input: &[u8], error: &serde_json::Error) -> usize {
+ let target_line = error.line().saturating_sub(1);
+ let mut line = 0;
+ let mut offset = 0;
+ while line < target_line {
+ let Some(relative) = input[offset..].iter().position(|&byte| byte == b'\n') else {
+ return input.len();
+ };
+ offset += relative + 1;
+ line += 1;
+ }
+ offset
+ .saturating_add(error.column().saturating_sub(1))
+ .min(input.len())
+}
+
+pub(super) fn skip_whitespace(input: &[u8], mut cursor: usize) -> usize {
+ while matches!(input.get(cursor), Some(b' ' | b'\n' | b'\r' | b'\t')) {
+ cursor += 1;
+ }
+ cursor
+}
+
+pub(super) fn decode_json_string<'a>(
+ input: &'a [u8],
+ token_range: Range<usize>,
+) -> Option<Cow<'a, str>> {
+ let raw = input.get(token_range.start + 1..token_range.end.checked_sub(1)?)?;
+ if !raw.contains(&b'\\') {
+ return std::str::from_utf8(raw).ok().map(Cow::Borrowed);
+ }
+ let token = input.get(token_range)?;
+ let mut jiter = Jiter::new(token);
+ jiter
+ .next_str()
+ .ok()
+ .map(|value| Cow::Owned(value.to_owned()))
+}
diff --git a/packages/native/src/otel_media/json_cursor.rs b/packages/native/src/otel_media/json_cursor.rs
new file mode 100644
index 0000000000..6f13b30260
--- /dev/null
+++ b/packages/native/src/otel_media/json_cursor.rs
@@ -0,0 +1,221 @@
+//! Advance through validated JSON while keeping offsets in the original input.
+//!
+//! `structural_walk` owns the container stack; each frame supplies `ContainerState`.
+//! Jiter consumes the next key, array element, closing delimiter, or scalar token.
+//! For a token Jiter cannot represent, `recover_token` borrows its span through
+//! serde's `RawValue`, then resumes Jiter at the following byte. No value tree is built.
+//!
+//! ```text
+//! advance(state) -> Child(key range) | Closed
+//! consume_scalar(peek) -> token range
+//! position() -> absolute input offset, including after recovery
+//! ```
+
+use std::ops::Range;
+
+use jiter::{Jiter, JiterError, JiterErrorType, JsonErrorType, Peek};
+use serde::Deserialize;
+use serde_json::value::RawValue;
+
+use super::payload::EarlyMediaError;
+use super::WalkStats;
+
+// Selects Jiter's first-child or next-child call for an object/array. Jiter handles
+// the separators and closing delimiter. `repr(u8)` keeps the deep-container stack
+// to one byte per open container; ordinary traversal also retains field context.
+#[repr(u8)]
+#[derive(Clone, Copy)]
+pub(super) enum ContainerState {
+ ObjectFirst,
+ ObjectNext,
+ ArrayFirst,
+ ArrayNext,
+}
+
+impl ContainerState {
+ pub(super) fn new(peek: Peek) -> Self {
+ match peek {
+ Peek::Object => Self::ObjectFirst,
+ Peek::Array => Self::ArrayFirst,
+ _ => unreachable!("container state starts at an object or array"),
+ }
+ }
+
+ pub(super) fn is_object(self) -> bool {
+ matches!(self, Self::ObjectFirst | Self::ObjectNext)
+ }
+}
+
+pub(super) enum ContainerStep {
+ // No key for an array element or an object key containing an unpaired surrogate.
+ Child(Option<Range<usize>>),
+ Closed,
+}
+
+pub(super) struct JsonCursor<'a> {
+ input: &'a [u8],
+ base: usize,
+ parser: Jiter<'a>,
+}
+
+impl<'a> JsonCursor<'a> {
+ pub(super) fn new(input: &'a [u8]) -> Self {
+ Self {
+ input,
+ base: 0,
+ parser: Jiter::new(input),
+ }
+ }
+
+ pub(super) fn position(&self) -> usize {
+ self.base + self.parser.current_index()
+ }
+
+ pub(super) fn peek(&mut self, stats: &mut WalkStats) -> Result<Peek, EarlyMediaError> {
+ let start = self.position();
+ let peek = self
+ .parser
+ .peek()
+ .map_err(|error| jiter_invalid(self.base, &error))?;
+ stats.add_bytes(self.position() - start);
+ Ok(peek)
+ }
+
+ fn rebase(&mut self, position: usize) {
+ self.base = position;
+ self.parser = Jiter::new(&self.input[position..]);
+ }
+
+ // RawValue borrows exactly one token; it does not build a value tree or change its spelling.
+ fn recover_token(
+ &mut self,
+ start: usize,
+ stats: &mut WalkStats,
+ ) -> Result<(), EarlyMediaError> {
+ let mut deserializer = serde_json::Deserializer::from_slice(&self.input[start..]);
+ let raw = <&RawValue>::deserialize(&mut deserializer).map_err(|_| {
+ EarlyMediaError::InvalidJson {
+ offset: start,
+ message: "invalid JSON value",
+ }
+ })?;
+ stats.add_bytes(raw.get().len());
+ self.rebase(start + raw.get().len());
+ Ok(())
+ }
+
+ pub(super) fn consume_scalar(
+ &mut self,
+ peek: Peek,
+ stats: &mut WalkStats,
+ ) -> Result<Range<usize>, EarlyMediaError> {
+ let start = self.position();
+ let result = match peek {
+ Peek::String => self.parser.next_bytes().map(|_| ()),
+ Peek::Null => self.parser.known_null(),
+ Peek::True | Peek::False => self.parser.known_bool(peek).map(|_| ()),
+ number if number.is_num() => self.parser.next_number_bytes().map(|_| ()),
+ _ => {
+ return Err(EarlyMediaError::InvalidJson {
+ offset: start,
+ message: "unexpected JSON value",
+ })
+ }
+ };
+ if let Err(error) = result {
+ if can_recover_token(&error) {
+ self.recover_token(start, stats)?;
+ } else {
+ return Err(jiter_invalid(self.base, &error));
+ }
+ }
+ let end = self.position();
+ stats.add_bytes(end - start);
+ Ok(start..end)
+ }
+
+ pub(super) fn advance(
+ &mut self,
+ state: &mut ContainerState,
+ stats: &mut WalkStats,
+ ) -> Result<ContainerStep, EarlyMediaError> {
+ let start = self.position();
+ let step = if state.is_object() {
+ self.advance_object(*state, stats)?
+ } else {
+ self.advance_array(*state)?
+ };
+ *state = if state.is_object() {
+ ContainerState::ObjectNext
+ } else {
+ ContainerState::ArrayNext
+ };
+ stats.add_bytes(self.position() - start);
+ Ok(step)
+ }
+
+ fn advance_object(
+ &mut self,
+ state: ContainerState,
+ stats: &mut WalkStats,
+ ) -> Result<ContainerStep, EarlyMediaError> {
+ let key = match state {
+ ContainerState::ObjectFirst => self.parser.next_object_bytes(),
+ _ => self.parser.next_key_bytes(),
+ };
+ Ok(match key {
+ Ok(Some(bytes)) => {
+ // Jiter returns key contents borrowed from input, excluding the quotes.
+ let quote = bytes.as_ptr() as usize - self.input.as_ptr() as usize - 1;
+ debug_assert_eq!(self.input.get(quote), Some(&b'"'));
+ debug_assert_eq!(self.input.get(quote + bytes.len() + 1), Some(&b'"'));
+ ContainerStep::Child(Some(quote..quote + bytes.len() + 2))
+ }
+ Ok(None) => ContainerStep::Closed,
+ Err(error) if can_recover_token(&error) => {
+ self.recover_token(self.position(), stats)?;
+ // Jiter consumes a key and its colon together. After recovering a
+ // surrogate key, consume that one delimiter before resuming Jiter.
+ if self.peek(stats)?.into_inner() != b':' {
+ return Err(EarlyMediaError::InvalidJson {
+ offset: self.position(),
+ message: "expected object colon",
+ });
+ }
+ self.rebase(self.position() + 1);
+ ContainerStep::Child(None)
+ }
+ Err(error) => return Err(jiter_invalid(self.base, &error)),
+ })
+ }
+
+ fn advance_array(&mut self, state: ContainerState) -> Result<ContainerStep, EarlyMediaError> {
+ let value = match state {
+ ContainerState::ArrayFirst => self.parser.next_array(),
+ _ => self.parser.array_step(),
+ }
+ .map_err(|error| jiter_invalid(self.base, &error))?;
+ Ok(match value {
+ Some(_) => ContainerStep::Child(None),
+ None => ContainerStep::Closed,
+ })
+ }
+}
+
+fn can_recover_token(error: &JiterError) -> bool {
+ matches!(
+ error.error_type,
+ JiterErrorType::JsonError(
+ JsonErrorType::LoneLeadingSurrogateInHexEscape
+ | JsonErrorType::UnexpectedEndOfHexEscape
+ | JsonErrorType::NumberOutOfRange
+ )
+ )
+}
+
+fn jiter_invalid(base: usize, error: &JiterError) -> EarlyMediaError {
+ EarlyMediaError::InvalidJson {
+ offset: base.saturating_add(error.index),
+ message: "invalid JSON",
+ }
+}
diff --git a/packages/native/src/otel_media/mod.rs b/packages/native/src/otel_media/mod.rs
new file mode 100644
index 0000000000..1ae02756b5
--- /dev/null
+++ b/packages/native/src/otel_media/mod.rs
@@ -0,0 +1,99 @@
+//! Remove large inline media before ingestion parses and normalizes the JSON.
+//!
+//! Each extracted attachment becomes a temporary reference in the JSON. Its removed
+//! source text is retained for upload or restoration later.
+//! For example (reference abbreviated):
+//!
+//! ```text
+//! {"image":"data:image/png;base64,..."} -> {"image":"<media-ref>"} + retained media
+//! ```
+//!
+//! Supported forms, in the payload locations selected by `rules`:
+//! - Data URIs in string values, including URIs surrounded by ordinary text.
+//! The URI supplies its own MIME type; no provider object is needed.
+//! - Recognized provider objects containing raw base64 or Python bytes literals.
+//! Sibling fields identify the body and MIME type (see `provider_shapes`).
+//!
+//! Both forms can also occur in JSON stored inside strings, within `scanner`'s
+//! nesting limits. Beyond those limits, only unambiguous Data URI text is extracted.
+//! Arbitrary base64-looking strings outside recognized provider objects stay inline,
+//! as do candidates smaller than `rules::MIN_EARLY_MEDIA_BYTES`.
+//!
+//! The two entry points separate validation from extraction so masking can run in
+//! between. Changed masking output must be validated again before extraction.
+//!
+//! ```text
+//! validate(bytes)
+//! `-- json::validate_json check syntax with jiter; retain owned bytes
+//! -> ValidatedPayload checked JSON, not a parsed object tree
+//!
+//! ValidatedPayload::compact()
+//! |-- scanner::discover
+//! | |-- structural_walk::scan find strings that could contain media
+//! | | -> Candidate byte range of one quoted JSON string
+//! | `-- inspect those strings decode with jiter; recognize and hash media
+//! | -> MediaManifest edit plan: ranges to replace + media metadata
+//! `-- payload::apply_edit_plan replace those ranges with temporary references
+//! -> EarlyMediaResult smaller JSON + extracted media records
+//! ```
+//!
+//! Validation and discovery each use a fresh jiter cursor; neither builds a JSON
+//! tree. Discovery keeps the field context needed to select media while jiter
+//! advances through tokens. Borrowed serde spans handle tokens jiter cannot read.
+//! `validate` takes ownership of the input buffer. Cursors and discovery borrow it;
+//! `compact` consumes it and returns owned compact JSON plus retained media. Media
+//! ranges keep the source alive through `Arc`, or own a detached copy (see `payload`).
+//! `otel_input` owns that result behind N-API handles; consumers perform uploads later.
+
+mod data_uri;
+mod encoding;
+mod json;
+mod json_cursor;
+mod payload;
+mod provider_shapes;
+mod rules;
+mod scanner;
+mod structural_walk;
+
+/// Test counters for traversal scaling, not production telemetry. Outside tests,
+/// there are no fields and `add_bytes` does nothing. Tests use these counts to detect
+/// repeated traversal and growing index allocations without timing assertions.
+#[derive(Default)]
+pub(super) struct WalkStats {
+ // Instrumented cursor advances and marker scans, not every read inside libraries.
+ #[cfg(test)]
+ pub(super) bytes_walked: usize,
+ // Stack/candidate-vector capacities, not total heap use or RSS. Retained
+ // media has separate accounting.
+ #[cfg(test)]
+ pub(super) peak_index_bytes: usize,
+}
+
+impl WalkStats {
+ #[inline(always)]
+ pub(super) fn add_bytes(&mut self, bytes: usize) {
+ #[cfg(test)]
+ {
+ self.bytes_walked = self.bytes_walked.saturating_add(bytes);
+ }
+ #[cfg(not(test))]
+ {
+ let _ = bytes;
+ }
+ }
+
+ #[cfg(test)]
+ pub(super) fn update_peak(&mut self, bytes: usize) {
+ self.peak_index_bytes = self.peak_index_bytes.max(bytes);
+ }
+}
+
+pub use payload::{validate, EarlyMediaResult, ExtractedMedia, ValidatedPayload};
+
+#[cfg(test)]
+pub fn extract_media(input: &[u8]) -> Result<EarlyMediaResult, payload::EarlyMediaError> {
+ validate(input.to_vec())?.compact()
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/packages/native/src/otel_media/payload.rs b/packages/native/src/otel_media/payload.rs
new file mode 100644
index 0000000000..bd507dde71
--- /dev/null
+++ b/packages/native/src/otel_media/payload.rs
@@ -0,0 +1,605 @@
+//! Source ownership and compaction; discovery borrows, this module owns.
+//!
+//! ```text
+//! ValidatedPayload { source } + MediaManifest
+//! | apply_edit_plan: replace ranges, copy untouched JSON verbatim
+//! v
+//! EarlyMediaResult
+//! + compact_json reuses source if no edits
+//! + ExtractedMedia[]
+//! + Arc<MediaMetadata> content identity shared across occurrences
+//! + occurrence ID replacement/restoration identity
+//! + storage spelling after parsing the outer JSON once
+//! + json_decode_layers remaining JSON string decodes before media decoding
+//! ```
+//!
+//! `MediaPayloadKind` identifies the media shape; `MediaSource` distinguishes URI
+//! from provider values; `MediaEncoding` selects base64 or Python-bytes decoding.
+//! Storage removes exactly the outer JSON string's escaping. For a URI in embedded
+//! JSON (quotes omitted), the same slash has these spellings:
+//! ```text
+//! outer source span data:image\\/png;base64,...
+//! retained text data:image\/png;base64,... restore this into the outer value
+//! decoded media text data:image/png;base64,... remove one more layer for upload
+//! ```
+//! `MediaStorage` shares the source allocation by `Arc` when its bytes already
+//! match the retained text; otherwise it owns the unescaped bytes. Small source
+//! ranges can be copied out to release an otherwise mostly-unused allocation.
+
+use std::borrow::Cow;
+use std::collections::HashSet;
+use std::fmt;
+use std::io::Write;
+use std::ops::Range;
+use std::sync::Arc;
+
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use base64::Engine;
+use jiter::Jiter;
+
+const SOURCE_DETACH_MIN_BYTES: usize = 8 * 1024 * 1024;
+
+/// Media shape that was found in the source payload.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum MediaPayloadKind {
+ DataUri,
+ Anthropic,
+ Vertex,
+ Gemini,
+ AiSdkV6,
+ AiSdkV7,
+}
+
+impl MediaPayloadKind {
+ /// Stable labels used when reporting extracted media.
+ pub fn as_str(self) -> &'static str {
+ match self {
+ Self::DataUri => "data_uri",
+ Self::Anthropic => "anthropic",
+ Self::Vertex => "vertex",
+ Self::Gemini => "gemini",
+ Self::AiSdkV6 => "ai_sdk_v6",
+ Self::AiSdkV7 => "ai_sdk_v7",
+ }
+ }
+}
+
+/// Whether the extracted body came from a Data URI or a raw provider value.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum MediaSource {
+ Base64DataUri,
+ Bytes,
+}
+
+impl MediaSource {
+ pub fn as_str(self) -> &'static str {
+ match self {
+ Self::Base64DataUri => "base64_data_uri",
+ Self::Bytes => "bytes",
+ }
+ }
+}
+
+/// Encoding used by the extracted text. Decoding is intentionally deferred to
+/// the upload adapter so extraction does not create a second large allocation.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum MediaEncoding {
+ /// A complete `data:<type>;base64,<payload>` value.
+ Base64DataUri,
+ /// A raw base64 provider value without a Data URI header.
+ Base64,
+ PythonBytesLiteral,
+}
+
+/// Metadata shared by occurrences with the same source, content type and hash.
+/// Source ranges and encodings stay on the occurrence so restoration retains
+/// its exact representation rather than just the decoded content identity.
+#[derive(Debug, Eq, PartialEq)]
+pub struct MediaMetadata {
+ pub source: MediaSource,
+ pub content_type: String,
+ pub sha256_hash: String,
+}
+
+impl MediaMetadata {
+ fn retained_bytes(&self) -> usize {
+ std::mem::size_of::<Self>() + self.content_type.capacity() + self.sha256_hash.capacity()
+ }
+}
+
+/// One media occurrence removed from the compact document.
+///
+/// Temporary references identify occurrences; metadata hashes identify assets.
+/// Distinct source spellings can share an upload without sharing restoration text.
+///
+/// Store the spelling visible after parsing the outer JSON once. Restoration
+/// reads that spelling; upload removes `json_decode_layers` remaining string
+/// layers before decoding base64/Python bytes. A plain base64 span stays borrowed.
+///
+/// For a slash escaped inside an embedded JSON string (quotes omitted):
+/// ```text
+/// outer source a\\/b
+/// stored spelling a\/b outer JSON layer removed during compaction
+/// media text a/b one remaining JSON decode before media decoding
+/// ```
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ExtractedMedia {
+ pub(crate) metadata: Arc<MediaMetadata>,
+ occurrence_id: u128,
+ /// Number of serialized JSON documents between the outer input and this candidate.
+ /// Used to adjust restoration to the consumer's current serialization layer.
+ original_json_depth: u8,
+ pub kind: MediaPayloadKind,
+ pub encoding: MediaEncoding,
+ /// Source spelling after parsing the outer JSON, retaining any nested escapes.
+ storage: MediaStorage,
+ /// Remaining JSON unescapes needed to reach media text. Zero when the stored
+ /// spelling already matches, even if the candidate was in an embedded document.
+ json_decode_layers: u8,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+enum MediaStorage {
+ Owned(Vec<u8>),
+ Source {
+ bytes: Arc<Vec<u8>>,
+ range: Range<usize>,
+ },
+}
+
+impl ExtractedMedia {
+ /// Temporary identity travels with this occurrence through normalization.
+ /// Upload deduplication uses the separate content hash.
+ pub fn reference(&self) -> String {
+ let mut bytes = Vec::with_capacity(reference_length(&self.metadata));
+ write_reference(&mut bytes, &self.metadata, self.occurrence_id);
+ String::from_utf8(bytes).expect("media reference is UTF-8")
+ }
+
+ /// Decode a body without consuming its encoded text, allowing retry or inline restoration.
+ pub fn decode(&self) -> Result<Vec<u8>, MediaDecodeError> {
+ super::encoding::decode_encoded_data(&self.encoded_data()?, self.encoding)
+ }
+
+ /// Return the media text used for inline restoration.
+ pub fn original_value(&self) -> Result<String, MediaDecodeError> {
+ String::from_utf8(self.original_data().to_vec())
+ .map_err(|_| MediaDecodeError::InvalidSourceText)
+ }
+
+ /// Return the source spelling at a requested number of remaining JSON layers.
+ /// `None` returns the exact spelling after parsing the outer document;
+ /// zero returns the fully decoded candidate.
+ pub fn original_value_for_layers(
+ &self,
+ json_layers: Option<u32>,
+ ) -> Result<String, MediaDecodeError> {
+ let Some(json_layers) = json_layers else {
+ return self.original_value();
+ };
+ if json_layers > MAX_JSON_LAYER_ADJUSTMENT {
+ return Err(MediaDecodeError::JsonLayerLimit);
+ }
+ if json_layers == 0 {
+ return String::from_utf8(self.encoded_data()?.into_owned())
+ .map_err(|_| MediaDecodeError::InvalidSourceText);
+ }
+
+ let source_depth = u32::from(self.original_json_depth);
+ let mut value = self.original_data().to_vec();
+ if json_layers < source_depth {
+ for _ in 0..(source_depth - json_layers) {
+ value = unescape_json_layer(&value)?;
+ }
+ } else {
+ for _ in 0..(json_layers - source_depth) {
+ value = escape_json_layer(&value)?;
+ }
+ }
+ String::from_utf8(value).map_err(|_| MediaDecodeError::InvalidSourceText)
+ }
+
+ /// Whether inline restoration differs from the fully decoded media text.
+ pub fn original_has_json_escapes(&self) -> bool {
+ self.json_decode_layers != 0
+ }
+
+ /// Number of serialized JSON documents containing this candidate.
+ pub fn original_json_depth(&self) -> u8 {
+ self.original_json_depth
+ }
+
+ /// Number of UTF-8 bytes in the source representation restored when an
+ /// upload fails.
+ pub fn original_byte_length(&self) -> usize {
+ self.original_data().len()
+ }
+
+ pub(crate) fn retained_bytes(&self, seen: &mut HashSet<*const MediaMetadata>) -> usize {
+ let metadata = if seen.insert(Arc::as_ptr(&self.metadata)) {
+ self.metadata.retained_bytes()
+ } else {
+ 0
+ };
+ metadata + storage_retained_bytes(&self.storage)
+ }
+
+ pub(crate) fn source_capacity(&self) -> Option<usize> {
+ match &self.storage {
+ MediaStorage::Source { bytes, .. } => Some(bytes.capacity()),
+ MediaStorage::Owned(_) => None,
+ }
+ }
+
+ fn encoded_data(&self) -> Result<Cow<'_, [u8]>, MediaDecodeError> {
+ let mut value = Cow::Borrowed(self.original_data());
+ for _ in 0..self.json_decode_layers {
+ value = Cow::Owned(unescape_json_layer(&value)?);
+ }
+ Ok(value)
+ }
+
+ fn original_data(&self) -> &[u8] {
+ storage_bytes(&self.storage)
+ }
+}
+
+fn storage_bytes(storage: &MediaStorage) -> &[u8] {
+ match storage {
+ MediaStorage::Owned(bytes) => bytes,
+ MediaStorage::Source { bytes, range } => &bytes[range.clone()],
+ }
+}
+
+fn storage_retained_bytes(storage: &MediaStorage) -> usize {
+ match storage {
+ MediaStorage::Owned(bytes) => bytes.capacity(),
+ MediaStorage::Source { .. } => 0,
+ }
+}
+
+/// Result of validating and extracting one JSON document.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct EarlyMediaResult {
+ /// Valid JSON with extracted values replaced by temporary occurrence references.
+ pub compact_json: Vec<u8>,
+ /// Media removed from `compact_json`, in source traversal order.
+ pub media: Vec<ExtractedMedia>,
+}
+
+/// An owned, syntax-validated source snapshot. Discovery is deferred until
+/// extraction so masking cannot cause media hashing of a discarded input.
+#[derive(Debug, Eq, PartialEq)]
+pub struct ValidatedPayload {
+ source: Vec<u8>,
+ normalized: bool,
+}
+
+/// OTLP receivers sanitize invalid UTF-8 sequences to U+FFFD before processing:
+/// https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md#utf-8-string-handling
+/// All later offsets refer to the sanitized source. Valid UTF-8 keeps its allocation.
+pub fn validate(input: Vec<u8>) -> Result<ValidatedPayload, EarlyMediaError> {
+ let (input, normalized) = match String::from_utf8(input) {
+ Ok(input) => (input, false),
+ Err(error) => (String::from_utf8_lossy(error.as_bytes()).into_owned(), true),
+ };
+ super::json::validate_json(&input)?;
+ Ok(ValidatedPayload {
+ source: input.into_bytes(),
+ normalized,
+ })
+}
+
+impl ValidatedPayload {
+ pub(crate) fn normalized_bytes(&self) -> Option<&[u8]> {
+ self.normalized.then_some(self.source.as_slice())
+ }
+
+ /// Retained source allocation used for the validation handle's baseline.
+ pub(crate) fn retained_bytes(&self) -> usize {
+ self.source.capacity()
+ }
+
+ /// Discover and apply edits only for the accepted payload selected for extraction.
+ /// Source-backed candidates keep ranges into the owned source allocation.
+ pub fn compact(self) -> Result<EarlyMediaResult, EarlyMediaError> {
+ let ValidatedPayload { source, .. } = self;
+ let manifest = super::scanner::discover(source.as_slice())?;
+ if manifest.entries.is_empty() {
+ // Reuse the source allocation when there are no replacements.
+ return Ok(EarlyMediaResult {
+ compact_json: source,
+ media: Vec::new(),
+ });
+ }
+ apply_edit_plan(Arc::new(source), manifest)
+ }
+
+ /// Return the validated source allocation without running media discovery.
+ pub fn into_source(self) -> Vec<u8> {
+ self.source
+ }
+}
+
+/// Transient discovery output consumed by compaction.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(super) struct MediaManifest {
+ pub(super) entries: Vec<MediaManifestEntry>,
+}
+
+#[cfg(test)]
+impl MediaManifest {
+ /// Retained allocations in the transient discovery result for bounded-memory tests.
+ pub(super) fn retained_bytes(&self) -> usize {
+ let mut seen = HashSet::new();
+ self.entries.capacity() * std::mem::size_of::<MediaManifestEntry>()
+ + self
+ .entries
+ .iter()
+ .map(|entry| {
+ if seen.insert(Arc::as_ptr(&entry.metadata)) {
+ entry.metadata.retained_bytes()
+ } else {
+ 0
+ }
+ })
+ .sum::<usize>()
+ }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub(super) struct MediaManifestEntry {
+ pub(crate) metadata: Arc<MediaMetadata>,
+ pub(crate) original_json_depth: u8,
+ pub kind: MediaPayloadKind,
+ pub encoding: MediaEncoding,
+ /// Exact raw source span replaced during compaction. Also supplies the
+ /// restoration spelling; it need not equal the JSON-unescaped upload text.
+ pub(super) edit_range: Range<usize>,
+ /// JSON unescapes remaining after the outer input is parsed once.
+ pub(super) json_decode_layers: u8,
+}
+
+/// JSON syntax errors and failures to construct or apply a media edit plan.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum EarlyMediaError {
+ InvalidJson {
+ offset: usize,
+ message: &'static str,
+ },
+ TrailingBytes {
+ offset: usize,
+ },
+ InvalidEditPlan {
+ entry: usize,
+ },
+ RandomnessUnavailable,
+}
+
+impl fmt::Display for EarlyMediaError {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ match self {
+ Self::InvalidJson { offset, message } => {
+ write!(f, "invalid JSON at byte {offset}: {message}")
+ }
+ Self::TrailingBytes { offset } => write!(f, "trailing JSON bytes at byte {offset}"),
+ Self::RandomnessUnavailable => f.write_str("could not create temporary media identity"),
+ Self::InvalidEditPlan { entry } => {
+ write!(
+ f,
+ "media edit plan has an invalid source span at entry {entry}"
+ )
+ }
+ }
+ }
+}
+
+impl std::error::Error for EarlyMediaError {}
+
+impl EarlyMediaError {
+ /// Stable error codes exposed through N-API.
+ pub fn code(&self) -> &'static str {
+ match self {
+ Self::InvalidEditPlan { .. } | Self::RandomnessUnavailable => "ERR_OTEL_INTERNAL",
+ Self::InvalidJson { .. } | Self::TrailingBytes { .. } => "ERR_OTEL_INVALID_JSON",
+ }
+ }
+}
+
+#[derive(Debug)]
+pub enum MediaDecodeError {
+ Base64(base64::DecodeError),
+ Base64Slice(base64::DecodeSliceError),
+ InvalidPythonBytes,
+ InvalidDataUri,
+ InvalidSourceText,
+ InvalidJsonString,
+ JsonLayerLimit,
+}
+
+impl fmt::Display for MediaDecodeError {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ match self {
+ Self::Base64(error) => write!(f, "invalid base64 media: {error}"),
+ Self::Base64Slice(error) => write!(f, "invalid base64 media: {error}"),
+ Self::InvalidPythonBytes => f.write_str("invalid Python bytes literal"),
+ Self::InvalidDataUri => f.write_str("invalid Data URI media"),
+ Self::InvalidSourceText => f.write_str("media source is not UTF-8 text"),
+ Self::InvalidJsonString => f.write_str("invalid JSON string representation"),
+ Self::JsonLayerLimit => f.write_str("JSON string layer limit exceeded"),
+ }
+ }
+}
+
+impl std::error::Error for MediaDecodeError {}
+
+fn apply_edit_plan(
+ source: Arc<Vec<u8>>,
+ manifest: MediaManifest,
+) -> Result<EarlyMediaResult, EarlyMediaError> {
+ let entries = manifest.entries;
+ let input = source.as_slice();
+ validate_edit_plan(input, &entries)?;
+ let mut nonce = [0; 16];
+ getrandom::fill(&mut nonce).map_err(|_| EarlyMediaError::RandomnessUnavailable)?;
+ let first_id = u128::from_le_bytes(nonce);
+ let replacement_bytes = entries
+ .iter()
+ .map(|entry| {
+ // The temporary ID has a fixed-width representation, independent of the index.
+ reference_length(&entry.metadata)
+ })
+ .sum::<usize>();
+ let removed_bytes = entries
+ .iter()
+ .map(|entry| entry.edit_range.len())
+ .sum::<usize>();
+ let mut compact_json = Vec::with_capacity(
+ input
+ .len()
+ .saturating_sub(removed_bytes)
+ .saturating_add(replacement_bytes),
+ );
+ let mut cursor = 0;
+ let mut media = Vec::with_capacity(entries.len());
+ for (index, entry) in entries.into_iter().enumerate() {
+ let occurrence_id = first_id.wrapping_add(index as u128);
+ compact_json.extend_from_slice(&input[cursor..entry.edit_range.start]);
+ write_reference(&mut compact_json, &entry.metadata, occurrence_id);
+ cursor = entry.edit_range.end;
+ let raw = &input[entry.edit_range.clone()];
+ let storage = if raw.contains(&b'\\') {
+ MediaStorage::Owned(
+ unescape_json_layer(raw)
+ .map_err(|_| EarlyMediaError::InvalidEditPlan { entry: index })?,
+ )
+ } else {
+ MediaStorage::Source {
+ bytes: Arc::clone(&source),
+ range: entry.edit_range,
+ }
+ };
+ media.push(ExtractedMedia {
+ metadata: entry.metadata,
+ occurrence_id,
+ original_json_depth: entry.original_json_depth,
+ kind: entry.kind,
+ encoding: entry.encoding,
+ storage,
+ json_decode_layers: entry.json_decode_layers,
+ });
+ }
+ compact_json.extend_from_slice(&input[cursor..]);
+
+ detach_small_source_ranges(&source, &mut media);
+ Ok(EarlyMediaResult {
+ compact_json,
+ media,
+ })
+}
+
+const MAX_JSON_LAYER_ADJUSTMENT: u32 = 16;
+
+fn unescape_json_layer(value: &[u8]) -> Result<Vec<u8>, MediaDecodeError> {
+ let mut token = Vec::with_capacity(value.len() + 2);
+ token.push(b'"');
+ token.extend_from_slice(value);
+ token.push(b'"');
+ let mut decoder = Jiter::new(&token);
+ let decoded = decoder
+ .next_str()
+ .map_err(|_| MediaDecodeError::InvalidJsonString)?
+ .as_bytes()
+ .to_vec();
+ decoder
+ .finish()
+ .map_err(|_| MediaDecodeError::InvalidJsonString)?;
+ Ok(decoded)
+}
+
+fn escape_json_layer(value: &[u8]) -> Result<Vec<u8>, MediaDecodeError> {
+ let value = std::str::from_utf8(value).map_err(|_| MediaDecodeError::InvalidSourceText)?;
+ let encoded = serde_json::to_string(value).map_err(|_| MediaDecodeError::InvalidJsonString)?;
+ Ok(encoded.as_bytes()[1..encoded.len() - 1].to_vec())
+}
+
+pub(super) fn validate_edit_plan(
+ input: &[u8],
+ entries: &[MediaManifestEntry],
+) -> Result<(), EarlyMediaError> {
+ // Compaction consumes entries in source order. Keeping this invariant here
+ // makes overlapping edits fail before any output or media handle is built.
+ let mut previous_end = 0;
+ for (index, entry) in entries.iter().enumerate() {
+ if entry.edit_range.start < previous_end
+ || entry.edit_range.start > entry.edit_range.end
+ || entry.edit_range.end > input.len()
+ {
+ return Err(EarlyMediaError::InvalidEditPlan { entry: index });
+ }
+ previous_end = entry.edit_range.end;
+ }
+ Ok(())
+}
+
+fn reference_length(metadata: &MediaMetadata) -> usize {
+ "@@@langfuseMedia:type=|id=|source=@@@".len()
+ + metadata.content_type.len()
+ + 22
+ + metadata.source.as_str().len()
+}
+
+fn write_reference(output: &mut Vec<u8>, metadata: &MediaMetadata, id: u128) {
+ // The registry distinguishes pending occurrences from pre-existing public
+ // references. Both use 22-character IDs, so temporary IDs do not inflate JSON.
+ let mut encoded_id = [0; 22];
+ URL_SAFE_NO_PAD
+ .encode_slice(id.to_le_bytes(), &mut encoded_id)
+ .expect("22 bytes hold an unpadded base64-encoded 128-bit ID");
+ let id = std::str::from_utf8(&encoded_id).expect("base64 IDs are ASCII");
+ write!(
+ output,
+ "@@@langfuseMedia:type={}|id={id}|source={}@@@",
+ metadata.content_type,
+ metadata.source.as_str()
+ )
+ .expect("writing a media reference to a Vec cannot fail");
+}
+
+/// Detach small source-backed ranges when they account for less than half of
+/// the source snapshot. Keeping a source-backed range for a media-heavy
+/// document avoids replacing one large allocation with another large copy.
+fn detach_small_source_ranges(source: &Arc<Vec<u8>>, media: &mut [ExtractedMedia]) {
+ if source.len() < SOURCE_DETACH_MIN_BYTES {
+ return;
+ }
+
+ let source_backed_bytes = media
+ .iter()
+ .map(|entry| &entry.storage)
+ .filter_map(|storage| match storage {
+ MediaStorage::Source { range, .. } => Some(range.len()),
+ MediaStorage::Owned(_) => None,
+ })
+ .sum::<usize>();
+ if source_backed_bytes.saturating_mul(2) >= source.len() {
+ return;
+ }
+
+ for entry in media {
+ let Some(range) = (match &entry.storage {
+ MediaStorage::Source { range, .. } => Some(range.clone()),
+ MediaStorage::Owned(_) => None,
+ }) else {
+ continue;
+ };
+ let Some(bytes) = source.get(range) else {
+ continue;
+ };
+ entry.storage = MediaStorage::Owned(bytes.to_vec());
+ }
+}
+
+#[cfg(test)]
+#[path = "payload_tests.rs"]
+mod tests;
diff --git a/packages/native/src/otel_media/payload_tests.rs b/packages/native/src/otel_media/payload_tests.rs
new file mode 100644
index 0000000000..c22ca858ba
--- /dev/null
+++ b/packages/native/src/otel_media/payload_tests.rs
@@ -0,0 +1,100 @@
+use proptest::prelude::*;
+use serde_json::Value;
+
+use super::super::rules::MIN_EARLY_MEDIA_BYTES;
+use super::super::tests::{data_uri, json_string_strategy, json_value_strategy};
+use super::super::validate;
+use super::MediaStorage;
+
+proptest! {
+#[test]
+fn compaction_preserves_source_bytes_around_generated_data_uri(
+ suffix in json_string_strategy(),
+ payloads in prop::collection::vec(prop::collection::vec(any::<u8>(), MIN_EARLY_MEDIA_BYTES..MIN_EARLY_MEDIA_BYTES + 32), 3..5),
+ layers in 0usize..4,
+) {
+ let prefix_json = serde_json::to_string(&format!("café-雪{suffix}")).unwrap();
+ let payloads = payloads.into_iter().enumerate().map(|(index, mut payload)| {
+ payload.push(index as u8);
+ payload
+ }).collect::<Vec<_>>();
+ let uris = payloads.iter().map(|payload| data_uri(payload)).collect::<Vec<_>>();
+
+ // Escapes before and between URI spans exercise decoded-to-source offsets.
+ // Adjacent provider values also cover whole-token replacement.
+ // Providers cover plain objects, one embedded document, and adjacent embedded documents.
+ for provider in [false, true] {
+ let originals = uris.iter().map(|uri| {
+ if provider { uri.split_once(',').unwrap().1.to_owned() } else { uri.clone() }
+ }).collect::<Vec<_>>();
+ let media_json = if provider {
+ originals.iter().enumerate().map(|(index, data)| {
+ let fields = if index % 2 == 0 { r#""type":"media","mime_type":"image/png""# }
+ else { r#""type":"base64","media_type":"image/png""# };
+ let object = format!(r#"{{{fields},"data":"{data}"}}"#);
+ if layers > 1 { serde_json::to_string(&object).unwrap() } else { object }
+ }).collect::<Vec<_>>().join(", ")
+ } else {
+ std::iter::once(format!(r#""before \u2603\uD83D\uDE00 {} \/\t\u0061 {} after""#, originals[0], originals[1]))
+ .chain(originals[2..].iter().map(|uri| format!("\"{uri}\"")))
+ .collect::<Vec<_>>().join(", ")
+ };
+ let mut source = format!(
+ "{{\n \"prefix\" : {prefix_json},\n \"escaped_prefix\" : \"café\\/雪\\u2603\",\n \"media\" : [{media_json}],\n \"slash\" : \"left\\/right\",\n \"number\" : 1.2300e+04\n}}"
+ );
+ let document_layers = if provider { usize::from(layers == 1) } else { layers };
+ for layer in 0..document_layers {
+ source = format!("{{ \n \"layer{layer}\" : {}, \"number\" : 7.000e0 \n}}", serde_json::to_string(&source).unwrap());
+ }
+ let validated = validate(source.as_bytes().to_vec()).unwrap();
+ prop_assert_eq!(validated.source.as_slice(), source.as_bytes());
+ let source_ptr = validated.source.as_ptr();
+ let compacted = validated.compact().unwrap();
+ prop_assert_eq!(compacted.media.len(), originals.len(), "provider={}, layers={}", provider, layers);
+ let mut expected = source;
+ for ((original, body), media) in originals.iter().zip(&payloads).zip(&compacted.media) {
+ prop_assert!(media.reference().starts_with("@@@langfuseMedia:type=image/png|id="));
+ prop_assert_eq!(media.original_value().unwrap(), original.as_str());
+ prop_assert_eq!(media.decode().unwrap(), body.as_slice());
+ expected = expected.replacen(original, &media.reference(), 1);
+ match &media.storage {
+ MediaStorage::Source { bytes, range } => {
+ prop_assert_eq!(bytes.as_ptr(), source_ptr);
+ prop_assert_eq!(&bytes[range.clone()], original.as_bytes());
+ }
+ MediaStorage::Owned(_) => prop_assert!(false, "ASCII media should retain the original source allocation"),
+ }
+ }
+ prop_assert_eq!(String::from_utf8(compacted.compact_json).unwrap(), expected);
+ }
+
+ // An escaped candidate instead owns decoded text, but must replace its exact source span.
+ let (header, payload) = uris[0].split_once(',').unwrap();
+ let escaped = format!("{header},\\u{:04x}{}", payload.as_bytes()[0], &payload[1..]);
+ let source = format!(r#"{{"image":"\uD83D\uDE00 {escaped} after"}}"#);
+ let compacted = validate(source.as_bytes().to_vec()).unwrap().compact().unwrap();
+ prop_assert_eq!(compacted.media.len(), 1);
+ let media = &compacted.media[0];
+ prop_assert_eq!(media.original_value().unwrap(), uris[0].as_str());
+ prop_assert_eq!(media.decode().unwrap(), payloads[0].as_slice());
+ prop_assert!(matches!(&media.storage, MediaStorage::Owned(_)));
+ prop_assert_eq!(String::from_utf8(compacted.compact_json).unwrap(), source.replacen(&escaped, &media.reference(), 1));
+}
+
+#[test]
+fn valid_json_values_survive_scan_and_compaction(
+ value in json_value_strategy(6),
+) {
+ let source = serde_json::to_vec(&value).expect("serialize generated JSON");
+ let validated = validate(source.clone()).expect("valid JSON remains native");
+ prop_assert_eq!(validated.source.as_slice(), source.as_slice());
+
+ let compacted = validated.compact().expect("compact media");
+ let compact: Value = serde_json::from_slice(&compacted.compact_json)
+ .expect("compaction preserves valid JSON");
+ if compacted.media.is_empty() {
+ // With no candidates, compaction must preserve arbitrary valid JSON.
+ prop_assert_eq!(compact, value);
+ }
+}
+}
diff --git a/packages/native/src/otel_media/provider_shapes.rs b/packages/native/src/otel_media/provider_shapes.rs
new file mode 100644
index 0000000000..5319341ddc
--- /dev/null
+++ b/packages/native/src/otel_media/provider_shapes.rs
@@ -0,0 +1,240 @@
+//! Recognize the provider media objects supported by TypeScript's `matchStructuredMedia`.
+//!
+//! A Data URI carries its own MIME type; raw base64 needs the surrounding fields:
+//! ```text
+//! "data:image/png;base64,..." scanner reads the URI alone
+//! {"type":"base64","media_type":"image/png", Anthropic shape supplies MIME
+//! "data":"..."} and identifies the body field
+//! ```
+//! A random string of base64 is not enough to identify media. The walk collects
+//! field ranges in `ProviderFields`; `structured_shape` selects the body and MIME
+//! when the object closes, so field order and duplicate keys are resolved first.
+//! `scanner` then validates and hashes that body's contents.
+
+use std::borrow::Cow;
+use std::ops::Range;
+
+use super::json::decode_json_string;
+use super::payload::MediaPayloadKind;
+
+macro_rules! shape_keys {
+ ($($variant:ident => $name:literal),+ $(,)?) => {
+ #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+ pub(super) enum ShapeKey {
+ $($variant,)+
+ }
+
+ impl ShapeKey {
+ const COUNT: usize = [$(Self::$variant),+].len();
+
+ pub(super) fn from_name(name: &str) -> Option<Self> {
+ match name {
+ $($name => Some(Self::$variant),)+
+ _ => None,
+ }
+ }
+
+ fn index(self) -> usize {
+ self as usize
+ }
+ }
+ };
+}
+
+shape_keys! {
+ Type => "type",
+ Data => "data",
+ MediaType => "media_type",
+ MimeType => "mime_type",
+ MimeTypeCamel => "mimeType",
+ MediaTypeCamel => "mediaType",
+ Content => "content",
+ Image => "image",
+ InlineData => "inline_data",
+ InlineDataCamel => "inlineData",
+}
+
+#[derive(Clone, Debug)]
+enum ShapeValue {
+ String(Range<usize>),
+ InlineObject {
+ fields: Box<InlineFields>,
+ range: Range<usize>,
+ },
+ Other(Range<usize>),
+}
+
+#[derive(Clone, Debug, Default)]
+struct InlineFields {
+ data: Option<ShapeValue>,
+ mime_type: Option<ShapeValue>,
+ mime_type_camel: Option<ShapeValue>,
+}
+
+impl InlineFields {
+ fn from_provider(fields: &ProviderFields) -> Self {
+ Self {
+ data: fields.get(ShapeKey::Data).map(to_inline_value),
+ mime_type: fields.get(ShapeKey::MimeType).map(to_inline_value),
+ mime_type_camel: fields.get(ShapeKey::MimeTypeCamel).map(to_inline_value),
+ }
+ }
+}
+
+fn to_inline_value(value: &ShapeValue) -> ShapeValue {
+ match value {
+ ShapeValue::String(range) => ShapeValue::String(range.clone()),
+ ShapeValue::InlineObject { range, .. } | ShapeValue::Other(range) => {
+ ShapeValue::Other(range.clone())
+ }
+ }
+}
+
+#[derive(Clone, Debug, Default)]
+pub(super) struct ProviderFields {
+ values: [Option<ShapeValue>; ShapeKey::COUNT],
+}
+
+impl ProviderFields {
+ pub(super) fn record(&mut self, key: ShapeKey, shape: ValueShape) {
+ let value = match shape {
+ ValueShape::String(range) => ShapeValue::String(range),
+ ValueShape::Object { range, fields }
+ if matches!(key, ShapeKey::InlineData | ShapeKey::InlineDataCamel) =>
+ {
+ match fields {
+ Some(fields) => ShapeValue::InlineObject {
+ fields: Box::new(InlineFields::from_provider(&fields)),
+ range,
+ },
+ None => ShapeValue::Other(range),
+ }
+ }
+ ValueShape::Object { range, .. } | ValueShape::Other(range) => ShapeValue::Other(range),
+ };
+ self.values[key.index()] = Some(value);
+ }
+
+ fn get(&self, key: ShapeKey) -> Option<&ShapeValue> {
+ self.values[key.index()].as_ref()
+ }
+}
+
+pub(super) enum ValueShape {
+ String(Range<usize>),
+ Object {
+ range: Range<usize>,
+ fields: Option<Box<ProviderFields>>,
+ },
+ Other(Range<usize>),
+}
+
+pub(super) fn structured_shape(
+ input: &[u8],
+ fields: &ProviderFields,
+) -> Option<StructuredCandidate> {
+ let Some(type_name) = fields
+ .get(ShapeKey::Type)
+ .and_then(|value| field_string(input, value))
+ else {
+ return structured_gemini_shape(input, fields);
+ };
+ let provider = match type_name.as_ref() {
+ "base64" => Some((
+ ShapeKey::MediaType,
+ fields.get(ShapeKey::Data),
+ MediaPayloadKind::Anthropic,
+ )),
+ "media" => Some((
+ ShapeKey::MimeType,
+ fields.get(ShapeKey::Data),
+ MediaPayloadKind::Vertex,
+ )),
+ "blob" => Some((
+ ShapeKey::MimeType,
+ fields.get(ShapeKey::Content),
+ MediaPayloadKind::AiSdkV7,
+ )),
+ "file" => {
+ let data = fields
+ .get(ShapeKey::Data)
+ .filter(|value| matches!(value, ShapeValue::String(_)))
+ .or_else(|| fields.get(ShapeKey::Image));
+ Some((ShapeKey::MediaTypeCamel, data, MediaPayloadKind::AiSdkV6))
+ }
+ _ => None,
+ };
+ if let Some((content_type_key, data_value, kind)) = provider {
+ if let (Some(data_range), Some(content_type)) = (
+ data_value.and_then(shape_string_range),
+ fields
+ .get(content_type_key)
+ .and_then(|value| field_string(input, value)),
+ ) {
+ return Some(StructuredCandidate {
+ token_range: data_range,
+ content_type: content_type.into_owned(),
+ kind,
+ });
+ }
+ }
+ structured_gemini_shape(input, fields)
+}
+
+fn structured_gemini_shape(input: &[u8], fields: &ProviderFields) -> Option<StructuredCandidate> {
+ for inline_key in [ShapeKey::InlineData, ShapeKey::InlineDataCamel] {
+ let Some(ShapeValue::InlineObject { fields: inline, .. }) = fields.get(inline_key) else {
+ continue;
+ };
+ let Some(data_range) = inline.data.as_ref().and_then(shape_string_range) else {
+ continue;
+ };
+ let snake_is_null = inline
+ .mime_type
+ .as_ref()
+ .is_some_and(|value| value_starts_with_null(input, value));
+ let selected_type = if inline.mime_type.is_some() && !snake_is_null {
+ inline.mime_type.as_ref()
+ } else {
+ inline.mime_type_camel.as_ref()
+ };
+ let Some(content_type) = selected_type.and_then(|value| field_string(input, value)) else {
+ continue;
+ };
+ return Some(StructuredCandidate {
+ token_range: data_range,
+ content_type: content_type.into_owned(),
+ kind: MediaPayloadKind::Gemini,
+ });
+ }
+ None
+}
+
+pub(super) struct StructuredCandidate {
+ pub(super) token_range: Range<usize>,
+ pub(super) content_type: String,
+ pub(super) kind: MediaPayloadKind,
+}
+
+fn shape_string_range(value: &ShapeValue) -> Option<Range<usize>> {
+ match value {
+ ShapeValue::String(range) => Some(range.clone()),
+ ShapeValue::InlineObject { .. } | ShapeValue::Other(_) => None,
+ }
+}
+
+fn field_string<'a>(input: &'a [u8], value: &ShapeValue) -> Option<Cow<'a, str>> {
+ match value {
+ ShapeValue::String(range) => decode_json_string(input, range.clone()),
+ ShapeValue::InlineObject { .. } | ShapeValue::Other(_) => None,
+ }
+}
+
+fn value_starts_with_null(input: &[u8], value: &ShapeValue) -> bool {
+ match value {
+ ShapeValue::Other(range) => input
+ .get(range.clone())
+ .is_some_and(|bytes| bytes.starts_with(b"null")),
+ ShapeValue::String(_) | ShapeValue::InlineObject { .. } => false,
+ }
+}
diff --git a/packages/native/src/otel_media/rules.rs b/packages/native/src/otel_media/rules.rs
new file mode 100644
index 0000000000..acdf10c305
--- /dev/null
+++ b/packages/native/src/otel_media/rules.rs
@@ -0,0 +1,211 @@
+//! Decide which OTLP fields to inspect and which media types are supported.
+//!
+//! `MediaScanMode` records where the walk is in the document. An OTLP attribute name
+//! must stay intact; the attribute's value can contain media. For example:
+//!
+//! ```text
+//! span Envelope
+//! `-- attributes[] Attributes
+//! |-- key: "attachment" Disabled (attribute name)
+//! `-- value AnyValue (OTLP value wrapper)
+//! `-- stringValue: "data:..." Payload (inspect for media)
+//! ```
+//!
+//! Inside a user payload, every field can contain media, even one named `key`.
+//! The marker checks cheaply select text worth scanning; the MIME allowlist limits
+//! supported content types. The scanner then validates the actual media encoding.
+
+use std::sync::LazyLock;
+
+use aho_corasick::{AhoCorasick, AhoCorasickBuilder, MatchKind};
+
+// Leave sub-KiB encoded candidates (including a Data URI header) for the later
+// media pass to limit per-occurrence descriptors and hash entries. The 1 KiB
+// cutoff favors measured replay gains for small attachments; escaped embedded
+// media can still retain more memory than leaving it inline.
+pub(super) const MIN_EARLY_MEDIA_BYTES: usize = 1024;
+
+pub(super) const DATA_URI_PREFIX: &str = "data:";
+pub(super) const BASE64_MARKER: &str = ";base64,";
+pub(super) const MEDIA_REFERENCE_PREFIX: &str = "@@@langfuseMedia:";
+pub(super) const MEDIA_REFERENCE_SUFFIX: &str = "@@@";
+static MEDIA_CANDIDATE_MARKERS: LazyLock<AhoCorasick> = LazyLock::new(|| {
+ // This predicate only asks whether any marker occurs. One matcher avoids
+ // rescanning marker-free input once for every literal. In local ARM64
+ // release runs (Sep 2026), 2 MiB marker-free text took 604–627 µs with
+ // `contains`, 207–223 µs with LeftmostFirst, and 2,394–2,483 µs with
+ // Standard (warm matchers, reversed-order rounds).
+ AhoCorasickBuilder::new()
+ .match_kind(MatchKind::LeftmostFirst)
+ .build([
+ DATA_URI_PREFIX,
+ MEDIA_REFERENCE_PREFIX,
+ "\\u",
+ "media_type",
+ "mime_type",
+ "mediaType",
+ "mimeType",
+ "inline_data",
+ "inlineData",
+ ])
+ .expect("media candidate markers are valid patterns")
+});
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(super) enum MediaScanMode {
+ /// A generic payload; candidates are eligible in every field.
+ Payload,
+ /// An OTLP KeyValue list; keys are metadata names and values contain data.
+ Attributes,
+ /// An OTLP AnyValue wrapper; map keys remain structural until a value is data.
+ AnyValue,
+ /// The OTLP envelope; only known payload-bearing descendants enter `Payload`.
+ Envelope,
+ /// A field whose strings are not eligible for extraction.
+ Disabled,
+}
+
+pub(super) fn is_otel_envelope_field(field: &str) -> bool {
+ matches!(
+ field,
+ "resourceSpans"
+ | "resourceLogs"
+ | "resourceMetrics"
+ | "scopeSpans"
+ | "scopeLogs"
+ | "scopeMetrics"
+ )
+}
+
+/// Select the scanning mode for one object field. Generic payload fields remain
+/// eligible; envelope fields are enabled only at known data-bearing boundaries.
+/// Structural fields and unknown envelope fields remain disabled.
+pub(super) fn media_scan_mode_for_field(parent: MediaScanMode, field: &str) -> MediaScanMode {
+ match parent {
+ MediaScanMode::Disabled => MediaScanMode::Disabled,
+ MediaScanMode::Payload => MediaScanMode::Payload,
+ MediaScanMode::Attributes => match field {
+ // OTLP KeyValue keys are metadata names, never media payloads.
+ "key" => MediaScanMode::Disabled,
+ "value" => MediaScanMode::AnyValue,
+ "values" => MediaScanMode::Attributes,
+ _ => MediaScanMode::Disabled,
+ },
+ MediaScanMode::AnyValue => match field {
+ "kvlistValue" => MediaScanMode::Attributes,
+ "arrayValue" | "values" => MediaScanMode::AnyValue,
+ "stringValue" | "bytesValue" => MediaScanMode::Payload,
+ _ => MediaScanMode::Disabled,
+ },
+ MediaScanMode::Envelope => match field {
+ // These fields contain envelope objects whose data-bearing children
+ // are classified by the branches below.
+ "resourceSpans" | "scopeSpans" | "spans" | "resource" | "scope" | "events"
+ | "links" | "resourceLogs" | "scopeLogs" | "logRecords" => MediaScanMode::Envelope,
+ // Attribute values and bodies contain user data.
+ "attributes" => MediaScanMode::Attributes,
+ "body" | "value" => MediaScanMode::AnyValue,
+ _ => MediaScanMode::Disabled,
+ },
+ }
+}
+
+pub(super) fn is_supported_content_type(value: &str) -> bool {
+ matches!(
+ value,
+ "image/png"
+ | "image/jpeg"
+ | "image/jpg"
+ | "image/webp"
+ | "image/gif"
+ | "image/svg+xml"
+ | "image/tiff"
+ | "image/bmp"
+ | "image/avif"
+ | "image/heic"
+ | "audio/mpeg"
+ | "audio/mp3"
+ | "audio/wav"
+ | "audio/ogg"
+ | "audio/oga"
+ | "audio/aac"
+ | "audio/mp4"
+ | "audio/flac"
+ | "audio/opus"
+ | "audio/webm"
+ | "video/mp4"
+ | "video/webm"
+ | "video/ogg"
+ | "video/mpeg"
+ | "video/quicktime"
+ | "video/x-msvideo"
+ | "video/x-matroska"
+ | "text/plain"
+ | "text/html"
+ | "text/css"
+ | "text/csv"
+ | "text/markdown"
+ | "text/x-python"
+ | "application/javascript"
+ | "text/x-typescript"
+ | "application/x-yaml"
+ | "application/pdf"
+ | "application/msword"
+ | "application/vnd.ms-excel"
+ | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+ | "application/octet-stream"
+ | "application/json"
+ | "application/xml"
+ | "application/zip"
+ | "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+ | "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+ | "application/rtf"
+ | "application/x-ndjson"
+ | "application/vnd.apache.parquet"
+ | "application/gzip"
+ | "application/x-tar"
+ | "application/x-7z-compressed"
+ )
+}
+
+pub(super) fn is_media_reference(value: &str) -> bool {
+ value.starts_with(MEDIA_REFERENCE_PREFIX) && value.ends_with(MEDIA_REFERENCE_SUFFIX)
+}
+
+pub(super) fn may_contain_serialized_media(value: &str) -> bool {
+ let has_data = value.contains("\"data\"");
+ let has_mime_type = value.contains("\"mime_type\"");
+ let has_provider_shape = (has_data && (value.contains("\"media_type\"") || has_mime_type))
+ || (value.contains("\"content\"") && has_mime_type)
+ || ((has_data || value.contains("\"image\"")) && value.contains("\"mediaType\""))
+ || (has_data
+ && (value.contains("\"inline_data\"") || value.contains("\"inlineData\""))
+ && (has_mime_type || value.contains("\"mimeType\"")));
+ // In JSON.stringify(JSON.stringify(metadata)), quotes in the metadata
+ // document are escaped, so the precise provider-key checks above do not
+ // match. The broad marker scan is safe for a quoted root and keeps this
+ // path from affecting ordinary object documents.
+ let has_quoted_root_candidate =
+ value.trim_start().starts_with('"') && may_contain_media_candidate(value);
+ has_provider_shape || has_quoted_root_candidate
+}
+
+/// Return true when a validated document might contain a media candidate.
+/// Unicode escapes are included because they can spell a marker after decoding.
+pub(super) fn may_contain_media_candidate(value: &str) -> bool {
+ // Broad fragments are intentional: false positives only select the full
+ // walk, while escaped nesting remains discoverable.
+ MEDIA_CANDIDATE_MARKERS.is_match(value)
+}
+
+pub(super) fn may_be_serialized_json(value: &str) -> bool {
+ match value.trim_start().as_bytes().first() {
+ Some(b'{' | b'[') => true,
+ // SDKs can JSON-encode a metadata value that is already JSON text or a
+ // string. It then arrives as a JSON string root. Limit this path to
+ // strings with media markers so ordinary quoted values do not trigger
+ // another validation and structural walk.
+ Some(b'"') => may_contain_media_candidate(value),
+ _ => false,
+ }
+}
diff --git a/packages/native/src/otel_media/scanner.rs b/packages/native/src/otel_media/scanner.rs
new file mode 100644
index 0000000000..2107a926fa
--- /dev/null
+++ b/packages/native/src/otel_media/scanner.rs
@@ -0,0 +1,479 @@
+//! Find media inside the strings selected by `structural_walk`.
+//!
+//! `ValidatedPayload::compact` calls `discover` with validated JSON bytes. The result
+//! is a `MediaManifest`: an edit plan containing source ranges and media metadata.
+//!
+//! ```text
+//! discover -> discover_inner
+//! |-- may_contain_media_candidate no markers -> empty edit plan
+//! |-- structural_walk::scan select quoted-string ranges
+//! |-- for each Candidate:
+//! | |-- String/Text -> discover_string_token
+//! | | |-- Jiter::next_str decode the selected JSON string
+//! | | `-- discover_string
+//! | | |-- try_discover_embedded_document
+//! | | | validate_json -> discover_inner -> translate_nested_entries
+//! | | `-- discover_data_uri_candidates
+//! | | data_uri::find_data_uri_candidates -> register_candidate
+//! | `-- Structured -> discover_structured
+//! | Jiter::next_str -> inspect provider body -> register_candidate
+//! `-- sort entries + validate_edit_plan return non-overlapping source ranges
+//! ```
+//!
+//! Media can appear inside JSON stored as a string. Decoding that string removes
+//! escapes, so offsets found in the inner document cannot be used to edit its
+//! parent. `translate_nested_entries` maps them back through each containing string;
+//! see `MediaDiscovery::map_string_boundaries` for the two-cursor algorithm and example.
+//! After `MAX_EMBEDDED_JSON_DEPTH`, only Data URI text is inspected. `payload`
+//! applies the resulting edits and retains the text needed for upload/restoration.
+
+use std::collections::HashMap;
+use std::ops::Range;
+use std::sync::Arc;
+
+use base64::Engine;
+use jiter::Jiter;
+
+use super::data_uri::{find_data_uri_candidates, parse_data_uri};
+use super::encoding::{hash_encoded_data, is_python_bytes_literal, is_valid_base64_syntax, BASE64};
+use super::payload::{
+ validate_edit_plan, EarlyMediaError, MediaEncoding, MediaManifest, MediaManifestEntry,
+ MediaMetadata, MediaPayloadKind, MediaSource,
+};
+use super::rules::{
+ is_media_reference, is_supported_content_type, may_be_serialized_json,
+ may_contain_media_candidate, may_contain_serialized_media, DATA_URI_PREFIX,
+ MIN_EARLY_MEDIA_BYTES,
+};
+use super::WalkStats;
+
+// Count JSON documents parsed from strings, excluding the outer input, not object/array depth.
+// After two embedded documents, stop interpreting further strings as structured documents;
+// still extract directly recognizable Data URIs from their text.
+const MAX_EMBEDDED_JSON_DEPTH: usize = 2;
+/// Content metadata shared by the outer document and JSON embedded in its strings.
+#[derive(Default)]
+struct ScanState {
+ metadata: HashMap<String, Arc<MediaMetadata>>,
+}
+
+/// Discover media in an already-validated source using an explicit stack.
+pub(super) fn discover(input: &[u8]) -> Result<MediaManifest, EarlyMediaError> {
+ discover_inner(
+ input,
+ 0,
+ &mut ScanState::default(),
+ &mut WalkStats::default(),
+ )
+}
+
+#[cfg(test)]
+pub(super) fn discover_measured(
+ input: &[u8],
+) -> Result<(MediaManifest, usize, usize, usize), EarlyMediaError> {
+ let mut state = ScanState::default();
+ let mut stats = WalkStats::default();
+ let manifest = discover_inner(input, 0, &mut state, &mut stats)?;
+ Ok((
+ manifest,
+ stats.bytes_walked,
+ stats.peak_index_bytes,
+ state.metadata.len(),
+ ))
+}
+
+fn discover_inner(
+ input: &[u8],
+ embedded_depth: usize,
+ state: &mut ScanState,
+ stats: &mut WalkStats,
+) -> Result<MediaManifest, EarlyMediaError> {
+ // Most payloads have no media markers. Avoid allocating the structural walk
+ // for those documents.
+ if std::str::from_utf8(input).is_ok_and(|text| !may_contain_media_candidate(text)) {
+ stats.add_bytes(input.len());
+ return Ok(MediaManifest {
+ entries: Vec::new(),
+ });
+ }
+
+ let candidates = super::structural_walk::scan(input, embedded_depth == 0, stats)?;
+ let mut entries = Vec::new();
+ let mut discovery = MediaDiscovery {
+ input,
+ state,
+ stats,
+ embedded_depth,
+ entries: &mut entries,
+ };
+ for candidate in candidates {
+ match candidate {
+ super::structural_walk::Candidate::String(token_range) => {
+ discovery.discover_string_token(token_range, true)?;
+ }
+ super::structural_walk::Candidate::Text(token_range) => {
+ discovery.discover_string_token(token_range, false)?;
+ }
+ super::structural_walk::Candidate::Structured {
+ token_range,
+ content_type,
+ kind,
+ } => discovery.discover_structured(token_range, &content_type, kind)?,
+ }
+ }
+
+ entries.sort_by_key(|entry| entry.edit_range.start);
+ validate_edit_plan(input, &entries)?;
+ Ok(MediaManifest { entries })
+}
+
+/// One document's scan. Entry offsets refer to `input` until a parent maps them back.
+struct MediaDiscovery<'a, 'state, 'stats> {
+ input: &'a [u8],
+ state: &'state mut ScanState,
+ stats: &'stats mut WalkStats,
+ embedded_depth: usize,
+ entries: &'stats mut Vec<MediaManifestEntry>,
+}
+
+impl MediaDiscovery<'_, '_, '_> {
+ fn discover_string_token(
+ &mut self,
+ token_range: Range<usize>,
+ allow_embedded_json: bool,
+ ) -> Result<(), EarlyMediaError> {
+ let input = self.input;
+ let mut decoder = Jiter::new(&input[token_range.clone()]);
+ let Ok(value) = decoder.next_str() else {
+ // RawValue accepts unpaired escapes such as "\ud800" as JSON syntax,
+ // but Jiter cannot decode them into Rust's Unicode-scalar `str`.
+ // Keep the entire string inline, including any media in it; other
+ // string candidates are still processed.
+ return Ok(());
+ };
+ self.discover_string(value, token_range, allow_embedded_json)
+ }
+
+ fn discover_string(
+ &mut self,
+ value: &str,
+ token_range: Range<usize>,
+ allow_embedded_json: bool,
+ ) -> Result<(), EarlyMediaError> {
+ if is_media_reference(value) {
+ return Ok(());
+ }
+
+ if self.try_discover_embedded_document(value, &token_range, allow_embedded_json)? {
+ return Ok(());
+ }
+
+ self.discover_data_uri_candidates(value, &token_range, allow_embedded_json)
+ }
+
+ fn try_discover_embedded_document(
+ &mut self,
+ value: &str,
+ token_range: &Range<usize>,
+ allow_embedded_json: bool,
+ ) -> Result<bool, EarlyMediaError> {
+ if !(allow_embedded_json
+ && may_be_serialized_json(value)
+ && self.embedded_depth < MAX_EMBEDDED_JSON_DEPTH
+ && (value.contains(DATA_URI_PREFIX)
+ || value.contains("\\u")
+ || may_contain_serialized_media(value))
+ && super::json::validate_json(value).is_ok())
+ {
+ return Ok(false);
+ }
+
+ let mut nested = discover_inner(
+ value.as_bytes(),
+ self.embedded_depth + 1,
+ self.state,
+ self.stats,
+ )?;
+ self.translate_nested_entries(value, token_range, &mut nested.entries)?;
+ self.entries.extend(nested.entries);
+ Ok(true)
+ }
+
+ fn discover_data_uri_candidates(
+ &mut self,
+ value: &str,
+ token_range: &Range<usize>,
+ allow_embedded_json: bool,
+ ) -> Result<(), EarlyMediaError> {
+ let text_only = !allow_embedded_json
+ || (self.embedded_depth >= MAX_EMBEDDED_JSON_DEPTH && may_be_serialized_json(value));
+ let candidates = find_data_uri_candidates(value)
+ .into_iter()
+ .filter(|(range, _)| value[range.clone()].len() >= MIN_EARLY_MEDIA_BYTES)
+ .collect::<Vec<_>>();
+ if candidates.is_empty() {
+ return Ok(());
+ }
+ self.entries.reserve(candidates.len());
+ let boundaries = candidates
+ .iter()
+ .flat_map(|(range, _)| [range.start, range.end])
+ .collect::<Vec<_>>();
+ let mapped = self.map_string_boundaries(token_range, value, &boundaries)?;
+ for (index, (range, content_type)) in candidates.into_iter().enumerate() {
+ let source_range = mapped[index * 2]..mapped[index * 2 + 1];
+ // Beyond the document/depth limit we have not parsed all string layers.
+ // In `data:image/png;name=\u00e9;base64,...`, the \u00e9 might be
+ // an inner JSON escape or literal text. Restoring it at the wrong layer
+ // changes the spelling or value. Keep escaped candidates inline here.
+ if text_only
+ && self
+ .input
+ .get(source_range.clone())
+ .is_some_and(|source| source.contains(&b'\\'))
+ {
+ continue;
+ }
+ self.register_candidate(
+ value[range].as_bytes(),
+ content_type,
+ MediaPayloadKind::DataUri,
+ MediaSource::Base64DataUri,
+ MediaEncoding::Base64DataUri,
+ source_range,
+ )?;
+ }
+ Ok(())
+ }
+
+ fn discover_structured(
+ &mut self,
+ token_range: Range<usize>,
+ content_type: &str,
+ kind: MediaPayloadKind,
+ ) -> Result<(), EarlyMediaError> {
+ let input = self.input;
+ let mut decoder = Jiter::new(&input[token_range.clone()]);
+ let Ok(content) = decoder.next_str() else {
+ return Ok(());
+ };
+ if content.starts_with(DATA_URI_PREFIX) {
+ let Some(candidate) = parse_data_uri(content, 0) else {
+ return Ok(());
+ };
+ let Some(uri_content_type) = candidate
+ .valid
+ .filter(|_| candidate.start == 0 && candidate.end == content.len())
+ else {
+ return Ok(());
+ };
+ return self.register_candidate(
+ content.as_bytes(),
+ uri_content_type,
+ MediaPayloadKind::DataUri,
+ MediaSource::Base64DataUri,
+ MediaEncoding::Base64DataUri,
+ token_range.start + 1..token_range.end - 1,
+ );
+ }
+ if !is_supported_content_type(content_type) {
+ return Ok(());
+ }
+ let (encoding, valid) = if is_python_bytes_literal(content) {
+ (MediaEncoding::PythonBytesLiteral, Some(()))
+ } else {
+ (
+ MediaEncoding::Base64,
+ is_valid_base64_syntax(content.as_bytes()).then_some(()),
+ )
+ };
+ if valid.is_none() {
+ return Ok(());
+ }
+
+ self.register_candidate(
+ content.as_bytes(),
+ content_type,
+ kind,
+ MediaSource::Bytes,
+ encoding,
+ token_range.start + 1..token_range.end - 1,
+ )
+ }
+
+ /// Map child edits into the parent source. Added escapes below the outer
+ /// input remain in the retained spelling and must be removed before upload.
+ fn translate_nested_entries(
+ &mut self,
+ decoded_document: &str,
+ containing_string: &Range<usize>,
+ entries: &mut [MediaManifestEntry],
+ ) -> Result<(), EarlyMediaError> {
+ let boundaries = entries
+ .iter()
+ .flat_map(|entry| [entry.edit_range.start, entry.edit_range.end])
+ .collect::<Vec<_>>();
+ let mapped =
+ self.map_string_boundaries(containing_string, decoded_document, &boundaries)?;
+ for (index, entry) in entries.iter_mut().enumerate() {
+ let parent_range = mapped[index * 2]..mapped[index * 2 + 1];
+ if self.embedded_depth > 0
+ && decoded_document.as_bytes().get(entry.edit_range.clone())
+ != self.input.get(parent_range.clone())
+ {
+ entry.json_decode_layers = entry.original_json_depth;
+ }
+ entry.edit_range = parent_range;
+ }
+ Ok(())
+ }
+
+ fn register_candidate(
+ &mut self,
+ encoded_data: &[u8],
+ content_type: &str,
+ kind: MediaPayloadKind,
+ source: MediaSource,
+ encoding: MediaEncoding,
+ source_range: Range<usize>,
+ ) -> Result<(), EarlyMediaError> {
+ if encoded_data.len() < MIN_EARLY_MEDIA_BYTES {
+ return Ok(());
+ }
+ let same_source_spelling = self
+ .input
+ .get(source_range.clone())
+ .is_some_and(|bytes| bytes == encoded_data);
+ let Some((reference, sha256_hash)) =
+ media_identity_from_encoded(encoded_data, content_type, source, encoding)
+ else {
+ return Ok(());
+ };
+ let metadata = if let Some(metadata) = self.state.metadata.get(&reference) {
+ Arc::clone(metadata)
+ } else {
+ let metadata = Arc::new(MediaMetadata {
+ source,
+ content_type: content_type.to_owned(),
+ sha256_hash,
+ });
+ self.state.metadata.insert(reference, Arc::clone(&metadata));
+ metadata
+ };
+ self.entries.push(MediaManifestEntry {
+ metadata,
+ original_json_depth: self.embedded_depth as u8,
+ kind,
+ encoding,
+ edit_range: source_range,
+ json_decode_layers: if same_source_spelling {
+ 0
+ } else {
+ self.embedded_depth as u8
+ },
+ });
+ Ok(())
+ }
+
+ /// Walk source and decoded text together until each requested byte offset.
+ /// Unescaped bytes advance both cursors equally. An escape advances the source
+ /// by 2 bytes (`\/`), 6 (`\u0061`), or 12 (a surrogate pair); the decoded cursor
+ /// advances by the corresponding character's UTF-8 length. Jiter has already
+ /// decoded/validated the character; this function only counts its source width.
+ ///
+ /// `memchr` skips a run without backslashes in one step. We save positions only
+ /// at the supplied starts/ends of media, rather than allocate a map per byte.
+ ///
+ /// With the opening quote at input byte 0:
+ /// ```text
+ /// source token: "x\u0061y" decoded text: xay
+ /// decoded range: 1..2 (a) -> source range: 2..8 (\u0061)
+ /// ```
+ /// The preceding `x` advances both cursors by one; `a` advances the decoded
+ /// cursor by one and the source cursor by six. The opening quote adds one.
+ fn map_string_boundaries(
+ &self,
+ token_range: &Range<usize>,
+ decoded: &str,
+ decoded_offsets: &[usize],
+ ) -> Result<Vec<usize>, EarlyMediaError> {
+ let invalid = |offset, message| EarlyMediaError::InvalidJson { offset, message };
+ let content_start = token_range.start + 1;
+ let content_end = token_range.end - 1;
+ let raw_content = self
+ .input
+ .get(content_start..content_end)
+ .ok_or_else(|| invalid(token_range.start, "invalid JSON string range"))?;
+ let mut boundaries = Vec::with_capacity(decoded_offsets.len());
+ let has_escapes = raw_content.contains(&b'\\');
+ let mut raw_cursor = content_start;
+ let mut decoded_cursor = 0usize;
+ let mut plain_run_end = None;
+ for &target in decoded_offsets {
+ if target < decoded_cursor || !decoded.is_char_boundary(target) {
+ return Err(invalid(raw_cursor, "invalid or unordered string boundary"));
+ }
+ if !has_escapes {
+ boundaries.push(content_start + target);
+ decoded_cursor = target;
+ continue;
+ }
+ while decoded_cursor < target {
+ if raw_cursor >= content_end {
+ return Err(invalid(raw_cursor, "invalid string boundary"));
+ }
+ if self.input[raw_cursor] == b'\\' {
+ let character = decoded
+ .get(decoded_cursor..)
+ .and_then(|text| text.chars().next())
+ .ok_or_else(|| invalid(raw_cursor, "invalid decoded string boundary"))?;
+ raw_cursor += if self.input.get(raw_cursor + 1) == Some(&b'u') {
+ 6 * character.len_utf16()
+ } else {
+ 2
+ };
+ decoded_cursor += character.len_utf8();
+ } else {
+ let run_end = *plain_run_end.get_or_insert_with(|| {
+ memchr::memchr(b'\\', &self.input[raw_cursor..content_end])
+ .map_or(content_end, |length| raw_cursor + length)
+ });
+ let amount = (target - decoded_cursor).min(run_end - raw_cursor);
+ raw_cursor += amount;
+ decoded_cursor += amount;
+ if raw_cursor == run_end {
+ plain_run_end = None;
+ }
+ }
+ }
+ if decoded_cursor != target || raw_cursor > content_end {
+ return Err(invalid(raw_cursor, "invalid string boundary"));
+ }
+ boundaries.push(raw_cursor);
+ }
+ Ok(boundaries)
+ }
+}
+
+pub(super) fn media_identity_from_encoded(
+ encoded_data: &[u8],
+ content_type: &str,
+ source: MediaSource,
+ encoding: MediaEncoding,
+) -> Option<(String, String)> {
+ let digest = hash_encoded_data(encoded_data, encoding).ok()?;
+ let sha256_hash = BASE64.encode(digest);
+ let media_id = sha256_hash
+ .replace('+', "-")
+ .replace('/', "_")
+ .chars()
+ .take(22)
+ .collect::<String>();
+ Some((
+ format!(
+ "@@@langfuseMedia:type={content_type}|id={media_id}|source={}@@@",
+ source.as_str()
+ ),
+ sha256_hash,
+ ))
+}
diff --git a/packages/native/src/otel_media/structural_walk.rs b/packages/native/src/otel_media/structural_walk.rs
new file mode 100644
index 0000000000..31a3f0eced
--- /dev/null
+++ b/packages/native/src/otel_media/structural_walk.rs
@@ -0,0 +1,506 @@
+//! Select media candidates while keeping the field context needed to interpret them.
+//!
+//! `scanner::discover_inner` calls `scan` with validated JSON. Token boundaries come
+//! from `json_cursor`; this module owns the container stack and candidate selection.
+//!
+//! ```text
+//! scan -> StructuralWalk::run
+//! |-- JsonCursor::advance / consume_scalar keys, delimiters, and value ranges
+//! |-- ObjectFrame::child_modes apply OTLP field rules
+//! |-- finish_object_field suppress duplicate keys; retain provider fields
+//! `-- close_frame -> provider_shapes recognize completed media objects
+//! scan -> apply_mask_operations -> Candidate emit only surviving string/body ranges
+//! ```
+//!
+//! Each open container has a `WalkFrame`; objects also have an `ObjectFrame` for
+//! duplicate keys and provider fields. Completed `ValueShape`s feed the parent.
+//! Candidates keep two eligibility bits: generic payload and OTLP envelope. The
+//! root selects one on close. Later fields can suppress earlier candidates, so
+//! masks are applied once after traversal. Returned ranges include JSON quotes.
+//!
+//! Selection here depends on surrounding fields; decoding/hashing belongs to
+//! `scanner`. The size/marker check avoids generic string candidates that cannot
+//! yield early media; provider bodies are selected from their surrounding fields.
+//! Neither selection establishes that a body is valid.
+
+use std::borrow::Cow;
+use std::collections::HashMap;
+use std::ops::Range;
+
+use jiter::Peek;
+
+use super::json::{decode_json_string, skip_whitespace};
+use super::json_cursor::{ContainerState, ContainerStep, JsonCursor};
+use super::payload::{EarlyMediaError, MediaPayloadKind};
+use super::provider_shapes::{structured_shape, ProviderFields, ShapeKey, ValueShape};
+use super::rules::{
+ is_otel_envelope_field, may_contain_media_candidate, media_scan_mode_for_field, MediaScanMode,
+ MIN_EARLY_MEDIA_BYTES,
+};
+use super::WalkStats;
+
+// Below this depth in embedded JSON, scan for Data URIs without deriving provider shapes or
+// retaining provider state for every nesting level.
+const MAX_STRUCTURAL_DEPTH: usize = 256;
+
+/// A candidate span selected by the structural walk for media interpretation.
+pub(super) enum Candidate {
+ String(Range<usize>),
+ Text(Range<usize>),
+ Structured {
+ token_range: Range<usize>,
+ content_type: String,
+ kind: MediaPayloadKind,
+ },
+}
+
+struct PendingCandidate {
+ /// Bit zero tracks generic-payload eligibility; bit one tracks envelope
+ /// eligibility. The root shape selects the active path when it closes.
+ mask: u8,
+ candidate: Candidate,
+}
+
+struct MaskOperation {
+ start: usize,
+ end: usize,
+ clear_mask: u8,
+}
+
+struct WalkFrame {
+ start: usize,
+ state: ContainerState,
+ candidate_start: usize,
+ modes: [MediaScanMode; 2],
+ is_envelope_decider: bool,
+ is_root_array: bool,
+}
+
+#[derive(Default)]
+struct ObjectFrame<'a> {
+ has_envelope_field: bool,
+ current_shape_key: Option<ShapeKey>,
+ current_key: Option<Cow<'a, str>>,
+ current_candidate_start: usize,
+ provider_fields: Option<Box<ProviderFields>>,
+ last_key_candidates: HashMap<String, Range<usize>>,
+}
+
+impl<'a> ObjectFrame<'a> {
+ fn child_modes(
+ &mut self,
+ input: &'a [u8],
+ key: Option<Range<usize>>,
+ modes: [MediaScanMode; 2],
+ candidate_start: usize,
+ ) -> [MediaScanMode; 2] {
+ self.current_key = key.and_then(|range| decode_json_string(input, range));
+ self.current_shape_key = self.current_key.as_deref().and_then(ShapeKey::from_name);
+ self.current_candidate_start = candidate_start;
+ self.has_envelope_field |= self
+ .current_key
+ .as_deref()
+ .is_some_and(is_otel_envelope_field);
+ modes.map(|mode| {
+ self.current_key
+ .as_deref()
+ .map_or(MediaScanMode::Disabled, |key| {
+ media_scan_mode_for_field(mode, key)
+ })
+ })
+ }
+
+ fn adopt(&mut self, shape: ValueShape) {
+ let Some(key) = self.current_shape_key.take() else {
+ return;
+ };
+ self.provider_fields
+ .get_or_insert_with(|| Box::new(ProviderFields::default()))
+ .record(key, shape);
+ }
+}
+
+struct StructuralWalk<'a, 'stats> {
+ input: &'a [u8],
+ allow_envelope: bool,
+ stats: &'stats mut WalkStats,
+ candidates: Vec<PendingCandidate>,
+ mask_operations: Vec<MaskOperation>,
+}
+
+impl<'a, 'stats> StructuralWalk<'a, 'stats> {
+ fn new(input: &'a [u8], allow_envelope: bool, stats: &'stats mut WalkStats) -> Self {
+ Self {
+ input,
+ allow_envelope,
+ stats,
+ candidates: Vec::new(),
+ mask_operations: Vec::new(),
+ }
+ }
+
+ fn run(&mut self) -> Result<usize, EarlyMediaError> {
+ let input = self.input;
+ let mut stack: Vec<WalkFrame> = Vec::new();
+ let mut object_states: Vec<ObjectFrame<'a>> = Vec::new();
+ let mut cursor = JsonCursor::new(input);
+ let root = cursor.peek(self.stats)?;
+ let mut next_value = Some((
+ [MediaScanMode::Payload; 2],
+ self.allow_envelope && root == Peek::Object,
+ self.allow_envelope && root == Peek::Array,
+ ));
+ let mut completed = None;
+
+ loop {
+ if let Some((mut modes, envelope_decider, is_root_array)) = next_value.take() {
+ let peek = cursor.peek(self.stats)?;
+ let start = cursor.position();
+ let is_envelope_decider = envelope_decider && peek == Peek::Object;
+ if is_envelope_decider {
+ modes = [MediaScanMode::Payload, MediaScanMode::Envelope];
+ }
+ match peek {
+ Peek::Object | Peek::Array => {
+ let frame = WalkFrame {
+ start,
+ state: ContainerState::new(peek),
+ modes,
+ is_envelope_decider,
+ is_root_array,
+ candidate_start: self.candidates.len(),
+ };
+ completed = self.enter_container(
+ &mut cursor,
+ frame,
+ &mut stack,
+ &mut object_states,
+ )?;
+ if completed.is_some() {
+ continue;
+ }
+ }
+ _ => {
+ completed = Some(self.scan_scalar(
+ &mut cursor,
+ peek,
+ payload_mask(modes),
+ false,
+ )?);
+ self.update_peak(&stack, &object_states);
+ }
+ }
+ }
+
+ if let Some(shape) = completed.take() {
+ let Some(parent) = stack.last() else {
+ return Ok(cursor.position());
+ };
+ if parent.state.is_object() {
+ let object = object_states.last_mut().expect("open object state");
+ self.finish_object_field(object, shape);
+ }
+ self.update_peak(&stack, &object_states);
+ }
+
+ let frame = stack
+ .last_mut()
+ .expect("open container after visiting a value");
+ match cursor.advance(&mut frame.state, self.stats)? {
+ ContainerStep::Child(key) => {
+ let modes = if frame.state.is_object() {
+ object_states
+ .last_mut()
+ .expect("open object state")
+ .child_modes(input, key, frame.modes, self.candidates.len())
+ } else {
+ frame.modes
+ };
+ next_value = Some((modes, frame.is_root_array, false));
+ self.update_peak(&stack, &object_states);
+ }
+ ContainerStep::Closed => {
+ let frame = stack.pop().expect("the current frame is on the stack");
+ completed =
+ Some(self.close_frame(frame, cursor.position(), &mut object_states));
+ }
+ }
+ }
+ }
+
+ fn enter_container(
+ &mut self,
+ cursor: &mut JsonCursor<'a>,
+ frame: WalkFrame,
+ stack: &mut Vec<WalkFrame>,
+ object_states: &mut Vec<ObjectFrame<'a>>,
+ ) -> Result<Option<ValueShape>, EarlyMediaError> {
+ // Keep outer OTLP semantics; deep embedded documents only need text scanning.
+ if !self.allow_envelope && stack.len() >= MAX_STRUCTURAL_DEPTH {
+ self.scan_deep_container(cursor, frame.state, payload_mask(frame.modes))?;
+ return Ok(Some(ValueShape::Other(frame.start..cursor.position())));
+ }
+ if frame.state.is_object() {
+ object_states.push(ObjectFrame::default());
+ }
+ stack.push(frame);
+ self.update_peak(stack, object_states);
+ Ok(None)
+ }
+
+ fn finish_object_field(&mut self, object: &mut ObjectFrame<'a>, shape: ValueShape) {
+ if let Some(key) = object.current_key.take() {
+ if let Some(previous) = object.last_key_candidates.remove(key.as_ref()) {
+ self.add_mask_operation(previous.start, previous.end, 0b11);
+ }
+ let range = object.current_candidate_start..self.candidates.len();
+ if !range.is_empty() {
+ object.last_key_candidates.insert(key.into_owned(), range);
+ }
+ }
+ object.adopt(shape);
+ }
+
+ /// Beyond the embedded structural-depth limit, keep only `ContainerState` per
+ /// open object/array (one byte), instead of full `WalkFrame`/`ObjectFrame` state.
+ /// Jiter still traverses every token; only string values are returned for URI
+ /// scanning. This limits stack growth for deeply nested embedded documents;
+ /// provider recognition and duplicate-key tracking stop at this boundary.
+ fn scan_deep_container(
+ &mut self,
+ cursor: &mut JsonCursor<'a>,
+ state: ContainerState,
+ mask: u8,
+ ) -> Result<(), EarlyMediaError> {
+ let mut stack = vec![state];
+ while let Some(state) = stack.last_mut() {
+ match cursor.advance(state, self.stats)? {
+ ContainerStep::Closed => {
+ stack.pop();
+ }
+ ContainerStep::Child(_) => {
+ let peek = cursor.peek(self.stats)?;
+ match peek {
+ Peek::Object | Peek::Array => {
+ stack.push(ContainerState::new(peek));
+ self.update_peak_from_capacities(
+ stack
+ .capacity()
+ .saturating_mul(std::mem::size_of::<ContainerState>()),
+ );
+ }
+ _ => {
+ self.scan_scalar(cursor, peek, mask, true)?;
+ self.update_peak_from_capacities(0);
+ }
+ }
+ }
+ }
+ }
+ Ok(())
+ }
+
+ fn scan_scalar(
+ &mut self,
+ cursor: &mut JsonCursor<'a>,
+ peek: Peek,
+ mask: u8,
+ text_only: bool,
+ ) -> Result<ValueShape, EarlyMediaError> {
+ let range = cursor.consume_scalar(peek, self.stats)?;
+ if peek == Peek::String {
+ self.record_string(range.clone(), mask, text_only);
+ Ok(ValueShape::String(range))
+ } else {
+ Ok(ValueShape::Other(range))
+ }
+ }
+
+ fn record_string(&mut self, range: Range<usize>, mask: u8, text_only: bool) {
+ let raw = &self.input[range.start + 1..range.end - 1];
+ self.stats.add_bytes(raw.len());
+ if mask != 0
+ && raw.len() >= MIN_EARLY_MEDIA_BYTES
+ && std::str::from_utf8(raw).is_ok_and(may_contain_media_candidate)
+ {
+ self.candidates.push(PendingCandidate {
+ mask,
+ candidate: if text_only {
+ Candidate::Text(range)
+ } else {
+ Candidate::String(range)
+ },
+ });
+ }
+ }
+
+ fn close_frame(
+ &mut self,
+ frame: WalkFrame,
+ end: usize,
+ object_states: &mut Vec<ObjectFrame<'_>>,
+ ) -> ValueShape {
+ let WalkFrame {
+ start,
+ candidate_start,
+ modes,
+ is_envelope_decider,
+ state,
+ ..
+ } = frame;
+ if !state.is_object() {
+ return ValueShape::Other(start..end);
+ }
+ let mut object = object_states
+ .pop()
+ .expect("every closed object frame has object state");
+ let candidate_end = self.candidates.len();
+ let provider_fields = object.provider_fields.as_deref();
+ let active = if is_envelope_decider {
+ let selected_bit = if object.has_envelope_field {
+ 0b10
+ } else {
+ 0b01
+ };
+ self.add_mask_operation(candidate_start, candidate_end, (!selected_bit) & 0b11);
+ if selected_bit == 0b01 {
+ selected_bit
+ } else {
+ 0
+ }
+ } else {
+ payload_mask(modes)
+ };
+ if active != 0 {
+ if let Some(shape) =
+ provider_fields.and_then(|fields| structured_shape(self.input, fields))
+ {
+ self.add_mask_operation(candidate_start, candidate_end, active);
+ self.candidates.push(PendingCandidate {
+ mask: active,
+ candidate: Candidate::Structured {
+ token_range: shape.token_range,
+ content_type: shape.content_type,
+ kind: shape.kind,
+ },
+ });
+ }
+ }
+ self.update_peak_from_capacities(0);
+ ValueShape::Object {
+ range: start..end,
+ fields: object.provider_fields.take(),
+ }
+ }
+
+ fn add_mask_operation(&mut self, start: usize, end: usize, clear_mask: u8) {
+ if start < end && clear_mask != 0 {
+ self.mask_operations.push(MaskOperation {
+ start,
+ end,
+ clear_mask,
+ });
+ }
+ }
+
+ fn update_peak(&mut self, stack: &Vec<WalkFrame>, object_states: &Vec<ObjectFrame<'_>>) {
+ #[cfg(test)]
+ {
+ let stack_bytes = stack
+ .capacity()
+ .saturating_mul(std::mem::size_of::<WalkFrame>());
+ let object_state_bytes = object_states
+ .capacity()
+ .saturating_mul(std::mem::size_of::<ObjectFrame>());
+ self.update_peak_from_capacities(stack_bytes.saturating_add(object_state_bytes));
+ }
+ #[cfg(not(test))]
+ let _ = (stack, object_states);
+ }
+
+ fn update_peak_from_capacities(&mut self, stack_bytes: usize) {
+ #[cfg(test)]
+ {
+ let candidate_bytes = self
+ .candidates
+ .capacity()
+ .saturating_mul(std::mem::size_of::<PendingCandidate>());
+ let operation_bytes = self
+ .mask_operations
+ .capacity()
+ .saturating_mul(std::mem::size_of::<MaskOperation>());
+ self.stats.update_peak(
+ stack_bytes
+ .saturating_add(candidate_bytes)
+ .saturating_add(operation_bytes),
+ );
+ }
+ #[cfg(not(test))]
+ let _ = stack_bytes;
+ }
+}
+
+fn payload_mask(modes: [MediaScanMode; 2]) -> u8 {
+ modes
+ .iter()
+ .enumerate()
+ .filter(|(_, mode)| **mode == MediaScanMode::Payload)
+ .fold(0, |mask, (index, _)| mask | (1 << index))
+}
+
+fn apply_mask_operations(
+ mut candidates: Vec<PendingCandidate>,
+ operations: &[MaskOperation],
+) -> Vec<PendingCandidate> {
+ let mut clear_payload = vec![0i32; candidates.len() + 1];
+ let mut clear_envelope = vec![0i32; candidates.len() + 1];
+ for operation in operations {
+ if operation.clear_mask & 0b01 != 0 {
+ clear_payload[operation.start] += 1;
+ clear_payload[operation.end] -= 1;
+ }
+ if operation.clear_mask & 0b10 != 0 {
+ clear_envelope[operation.start] += 1;
+ clear_envelope[operation.end] -= 1;
+ }
+ }
+ let (mut active_payload, mut active_envelope) = (0, 0);
+ for (index, candidate) in candidates.iter_mut().enumerate() {
+ active_payload += clear_payload[index];
+ active_envelope += clear_envelope[index];
+ if active_payload > 0 {
+ candidate.mask &= !0b01;
+ }
+ if active_envelope > 0 {
+ candidate.mask &= !0b10;
+ }
+ }
+ candidates
+}
+
+/// Find eligible JSON value spans before interpreting their contents as media.
+pub(super) fn scan(
+ input: &[u8],
+ allow_envelope: bool,
+ stats: &mut WalkStats,
+) -> Result<impl Iterator<Item = Candidate>, EarlyMediaError> {
+ let mut walk = StructuralWalk::new(input, allow_envelope, stats);
+ let root_end = walk.run()?;
+ let trailing_bytes = skip_whitespace(input, root_end);
+ if trailing_bytes != input.len() {
+ return Err(EarlyMediaError::TrailingBytes {
+ offset: trailing_bytes,
+ });
+ }
+
+ let StructuralWalk {
+ candidates,
+ mask_operations,
+ ..
+ } = walk;
+ let candidates = apply_mask_operations(candidates, &mask_operations);
+ Ok(candidates
+ .into_iter()
+ .filter(|candidate| candidate.mask != 0)
+ .map(|candidate| candidate.candidate))
+}
diff --git a/packages/native/src/otel_media/tests.rs b/packages/native/src/otel_media/tests.rs
new file mode 100644
index 0000000000..dc0d85c79b
--- /dev/null
+++ b/packages/native/src/otel_media/tests.rs
@@ -0,0 +1,1186 @@
+use super::encoding::BASE64;
+use super::payload::{EarlyMediaError, MediaEncoding, MediaPayloadKind, MediaSource};
+use super::rules::{may_contain_media_candidate, MEDIA_REFERENCE_PREFIX, MIN_EARLY_MEDIA_BYTES};
+use super::scanner::{discover_measured, media_identity_from_encoded};
+use super::{extract_media, validate};
+use base64::Engine;
+use proptest::prelude::*;
+use serde_json::{json, Value};
+
+fn validate_measured(
+ input: Vec<u8>,
+) -> Result<(super::ValidatedPayload, usize, usize, usize, usize), EarlyMediaError> {
+ let validated = validate(input.clone())?;
+ let (manifest, visited, index_bytes, unique) = discover_measured(&input)?;
+ let retained_bytes = validated.retained_bytes() + manifest.retained_bytes();
+ Ok((validated, visited, index_bytes, unique, retained_bytes))
+}
+
+pub(super) fn json_string_strategy() -> BoxedStrategy<String> {
+ prop::collection::vec(any::<char>(), 0..32)
+ .prop_map(|characters| characters.into_iter().collect())
+ .boxed()
+}
+
+pub(super) fn json_value_strategy(depth: u8) -> BoxedStrategy<Value> {
+ let scalar = prop_oneof![
+ Just(Value::Null),
+ any::<bool>().prop_map(Value::Bool),
+ any::<i64>().prop_map(|value| Value::Number(value.into())),
+ any::<u64>().prop_map(|value| Value::Number(value.into())),
+ any::<f64>().prop_filter_map("finite JSON number", |value| {
+ serde_json::Number::from_f64(value).map(Value::Number)
+ }),
+ json_string_strategy().prop_map(Value::String),
+ ]
+ .boxed();
+ if depth == 0 {
+ return scalar;
+ }
+
+ prop_oneof![
+ scalar,
+ prop::collection::vec(json_value_strategy(depth - 1), 0..5).prop_map(Value::Array),
+ prop::collection::vec(
+ (json_string_strategy(), json_value_strategy(depth - 1)),
+ 0..5,
+ )
+ .prop_map(|fields| {
+ let mut object = serde_json::Map::new();
+ for (key, value) in fields {
+ object.insert(key, value);
+ }
+ Value::Object(object)
+ }),
+ ]
+ .boxed()
+}
+
+pub(super) fn data_uri(payload: &[u8]) -> String {
+ format!("data:image/png;base64,{}", BASE64.encode(payload))
+}
+
+pub(super) fn large_data_uri(label: &[u8]) -> (String, Vec<u8>) {
+ let mut payload = vec![b'x'; MIN_EARLY_MEDIA_BYTES];
+ let copy_len = label.len().min(payload.len());
+ payload[..copy_len].copy_from_slice(&label[..copy_len]);
+ (data_uri(&payload), payload)
+}
+
+pub(super) fn large_base64(label: &[u8]) -> (String, Vec<u8>) {
+ let mut payload = vec![b'x'; MIN_EARLY_MEDIA_BYTES];
+ let copy_len = label.len().min(payload.len());
+ payload[..copy_len].copy_from_slice(&label[..copy_len]);
+ (BASE64.encode(&payload), payload)
+}
+
+#[test]
+fn leaves_small_data_uris_for_the_later_media_pass() {
+ let small = data_uri(&vec![b'x'; MIN_EARLY_MEDIA_BYTES / 2]);
+ let (large, large_body) = large_data_uri(b"large");
+ let input = format!(r#"{{"small":"{small}","large":"{large}"}}"#);
+
+ let result = extract_media(input.as_bytes()).expect("valid JSON");
+
+ assert_eq!(result.media.len(), 1);
+ assert_eq!(result.media[0].decode().unwrap(), large_body);
+ let compact = String::from_utf8(result.compact_json).unwrap();
+ assert!(compact.contains(&small));
+ assert!(compact.contains(&result.media[0].reference()));
+}
+
+#[test]
+fn early_extraction_uses_encoded_size_for_uri_and_provider_candidates() {
+ for size in [1023, 1024] {
+ let header = "data:image/png;name=a;base64,";
+ let uri = format!("{header}{}", "A".repeat(size - header.len()));
+ let provider = "A".repeat(size);
+ let input =
+ format!(r#"["{uri}",{{"type":"file","mediaType":"image/png","data":"{provider}"}}]"#);
+ let result = extract_media(input.as_bytes()).unwrap();
+ assert_eq!(result.media.len(), if size < 1024 { 0 } else { 2 });
+ if size < 1024 {
+ assert_eq!(result.compact_json, input.as_bytes());
+ }
+ }
+}
+
+#[test]
+fn validates_and_extracts_data_uri_without_parsing_a_value_tree() {
+ let (uri, body) = large_data_uri(b"image");
+ let input = format!(r#"{{"input":"before {uri} after"}}"#);
+ let result = extract_media(input.as_bytes()).expect("valid JSON");
+
+ assert_eq!(result.media.len(), 1);
+ assert!(String::from_utf8_lossy(&result.compact_json)
+ .contains("@@@langfuseMedia:type=image/png|id="));
+ assert_eq!(result.media[0].decode().unwrap(), body);
+ assert_eq!(result.media[0].original_value().unwrap(), uri);
+ assert_eq!(result.media[0].kind, MediaPayloadKind::DataUri);
+}
+
+#[test]
+fn nested_otlp_map_keys_stay_structural() {
+ let (uri, _) = large_data_uri(b"nested-map");
+ let attributes = json!([{"key": "metadata", "value": {"arrayValue": {"values": [
+ {"kvlistValue": {"values": [{"key": uri, "value": {"stringValue": uri}}]}}
+ ]}}}]);
+ let input = json!({"resourceSpans": [{"resource": {"attributes": attributes}}]});
+ let result = extract_media(&serde_json::to_vec(&input).unwrap()).unwrap();
+ assert_eq!(result.media.len(), 1);
+ let compact: Value = serde_json::from_slice(&result.compact_json).unwrap();
+ let entry = &compact["resourceSpans"][0]["resource"]["attributes"][0]["value"]["arrayValue"]
+ ["values"][0]["kvlistValue"]["values"][0];
+ assert_eq!(entry["key"], uri);
+ assert_eq!(entry["value"]["stringValue"], result.media[0].reference());
+}
+
+#[test]
+fn accepts_deep_otlp_structure_before_embedded_json_limit() {
+ let mut value = r#""leaf""#.to_owned();
+ for _ in 0..16 {
+ value = format!(r#"{{"nested":{value}}}"#);
+ }
+
+ let result = extract_media(value.as_bytes()).expect("deep OTLP JSON is valid");
+ assert!(result.media.is_empty());
+}
+
+#[test]
+fn validates_and_extracts_beyond_the_former_parser_depth_limit() {
+ let (uri, body) = large_data_uri(b"deep");
+ for depth in [128, 512, 4096] {
+ let array = format!("{}\"{uri}\"{}", "[".repeat(depth), "]".repeat(depth));
+ let object = format!("{}\"{uri}\"{}", "{\"x\":".repeat(depth), "}".repeat(depth));
+ for input in [array, object] {
+ let (validated, _, index_bytes, _, _) =
+ validate_measured(input.as_bytes().to_vec()).expect("deep JSON remains native");
+ // Arrays do not need object-only maps or provider state.
+ assert!(
+ index_bytes <= 24 * input.len(),
+ "{index_bytes} bytes for {} input bytes",
+ input.len()
+ );
+ let result = validated.compact().unwrap();
+ assert_eq!(result.media.len(), 1);
+ assert_eq!(result.media[0].decode().unwrap(), body);
+ }
+ }
+}
+
+#[test]
+fn deep_structural_scan_keeps_provider_objects_inline_but_finds_uri_text() {
+ let (uri, body) = large_data_uri(b"deep-uri");
+ let (provider_data, _) = large_base64(b"deep-provider");
+ let mut embedded = format!(
+ r#"{{"provider":{{"type":"base64","media_type":"image/png","data":"{provider_data}"}},"uri":"{uri}"}}"#
+ );
+ for _ in 0..300 {
+ embedded = format!(r#"{{"nested":{embedded}}}"#);
+ }
+ let input = format!(
+ r#"{{"text":{}}}"#,
+ serde_json::to_string(&embedded).unwrap()
+ );
+ let (_, _, index_bytes, _, _) = validate_measured(input.as_bytes().to_vec()).unwrap();
+ assert!(
+ index_bytes <= 256 * 1024,
+ "embedded walk retained {index_bytes} bytes"
+ );
+
+ let result = extract_media(input.as_bytes()).expect("deep JSON remains valid");
+ assert_eq!(result.media.len(), 1);
+ assert_eq!(result.media[0].decode().unwrap(), body);
+ let compact: Value = serde_json::from_slice(&result.compact_json).unwrap();
+ let compact_embedded = compact["text"].as_str().unwrap();
+ assert!(compact_embedded.contains(r#""type":"base64""#));
+ assert!(compact_embedded.contains(&provider_data));
+}
+
+#[test]
+fn bounded_text_scan_leaves_escaped_uri_spelling_inline() {
+ let plain_body = vec![b'p'; MIN_EARLY_MEDIA_BYTES];
+ let plain_uri = data_uri(&plain_body);
+ let escaped_body = vec![0xff; MIN_EARLY_MEDIA_BYTES];
+ let escaped_base64 = BASE64.encode(&escaped_body);
+ for escaped_uri in [
+ format!("data:image/png;base64,\\/\\/\\/\\/{}", &escaped_base64[4..]),
+ format!(r"data:image/png;name=C:\\img\\a.png;base64,{escaped_base64}"),
+ format!(r"data:image/png;name=snow\u2603;base64,{escaped_base64}"),
+ ] {
+ let mut embedded = format!(r#"{{"escaped":"{escaped_uri}","plain":"{plain_uri}"}}"#);
+ for _ in 0..3 {
+ embedded = format!(
+ r#"{{"embedded":{}}}"#,
+ serde_json::to_string(&embedded).unwrap()
+ );
+ }
+ let two_layer_input = format!(r#"{{"deep":{embedded}}}"#);
+ let mut deep = format!(r#"{{"escaped":"{escaped_uri}","plain":"{plain_uri}"}}"#);
+ for _ in 0..300 {
+ deep = format!(r#"{{"nested":{deep}}}"#);
+ }
+ let deep_input = format!(r#"{{"text":{}}}"#, serde_json::to_string(&deep).unwrap());
+
+ for input in [two_layer_input, deep_input] {
+ let result = extract_media(input.as_bytes()).expect("valid nested JSON");
+ assert_eq!(result.media.len(), 1);
+ assert_eq!(result.media[0].decode().unwrap(), plain_body);
+ let expected = input.replacen(&plain_uri, &result.media[0].reference(), 1);
+ assert_eq!(result.compact_json, expected.as_bytes());
+ }
+ }
+}
+
+#[test]
+fn preserves_json_escaping_and_scans_nested_stringified_json() {
+ let (encoded, body) = large_base64(b"nested");
+ let nested = format!(
+ r#"{{"type":"base64","media_type":"image/png","data":"{}"}}"#,
+ encoded
+ );
+ let encoded_nested = serde_json::to_string(&nested).expect("serialize nested JSON");
+ let input = format!(r#"{{"text":{encoded_nested}}}"#);
+ let result = extract_media(input.as_bytes()).expect("valid JSON");
+
+ assert_eq!(result.media.len(), 1);
+ let compact = String::from_utf8(result.compact_json).unwrap();
+ assert!(compact.contains("@@@langfuseMedia:type=image/png|id="));
+ assert_eq!(result.media[0].kind, MediaPayloadKind::Anthropic);
+ assert_eq!(result.media[0].original_value().unwrap(), encoded);
+ assert_eq!(result.media[0].decode().unwrap(), body);
+}
+
+#[test]
+fn scans_sdk_json_string_wrappers_within_the_embedded_json_budget() {
+ let (uri, uri_body) = large_data_uri(b"sdk-uri");
+ let (provider_data, provider_body) = large_base64(b"sdk-provider");
+ let uri_metadata = format!(r#"{{"image":"{uri}"}}"#);
+ let provider_metadata =
+ format!(r#"{{"type":"file","mediaType":"image/png","data":"{provider_data}"}}"#);
+ // The SDK JSON-encodes the metadata value, so stringValue contains a
+ // quoted JSON representation of either metadata JSON text or a raw string.
+ let uri_string_value = serde_json::to_string(&uri_metadata).unwrap();
+ let raw_uri_string_value = serde_json::to_string(&uri).unwrap();
+ let provider_string_value = serde_json::to_string(&provider_metadata).unwrap();
+ let input = serde_json::to_vec(&json!({
+ "resourceSpans": [{
+ "scopeSpans": [{
+ "spans": [{
+ "attributes": [
+ {
+ "key": "metadata.attachment",
+ "value": {"stringValue": uri_string_value}
+ },
+ {
+ "key": "metadata.raw-attachment",
+ "value": {"stringValue": raw_uri_string_value}
+ },
+ {
+ "key": "metadata.provider",
+ "value": {"stringValue": provider_string_value}
+ }
+ ]
+ }]
+ }]
+ }]
+ }))
+ .unwrap();
+
+ let result = extract_media(&input).expect("valid OTLP JSON");
+
+ assert_eq!(result.media.len(), 3);
+ assert_eq!(result.media[0].decode().unwrap(), uri_body);
+ assert_eq!(result.media[1].decode().unwrap(), uri_body);
+ assert_eq!(result.media[2].decode().unwrap(), provider_body);
+ let mut expected = String::from_utf8(input).unwrap();
+ expected = expected.replacen(&uri, &result.media[0].reference(), 1);
+ expected = expected.replacen(&uri, &result.media[1].reference(), 1);
+ expected = expected.replace(&provider_data, &result.media[2].reference());
+ assert_eq!(String::from_utf8(result.compact_json).unwrap(), expected);
+}
+
+#[test]
+fn limits_embedded_documents_without_losing_uri_text_or_siblings() {
+ let (provider_data, provider_body) = large_base64(b"provider");
+ let (deep_uri, deep_body) = large_data_uri(b"at-limit");
+ let (quoted_uri, quoted_body) = large_data_uri(b"quoted");
+ let (sibling_uri, sibling_body) = large_data_uri(b"sibling");
+ for layers in [2, 3, 10] {
+ let mut document = format!(
+ r#"{{"provider":{{"type":"base64","media_type":"image/png","data":"{provider_data}"}},"text":"{deep_uri} after","quoted":"{quoted_uri}"}}"#
+ );
+ for _ in 0..layers {
+ let encoded = serde_json::to_string(&document).unwrap();
+ document = format!(r#"{{"embedded":{encoded}}}"#);
+ }
+ let input = format!(r#"{{"deep":{document},"sibling":"{sibling_uri}","tail":"after"}}"#);
+ let result = extract_media(input.as_bytes()).expect("valid embedded documents");
+ let bodies = result
+ .media
+ .iter()
+ .map(|media| media.decode().unwrap())
+ .collect::<Vec<_>>();
+ let expected_bodies = if layers == 2 {
+ vec![
+ provider_body.clone(),
+ deep_body.clone(),
+ quoted_body.clone(),
+ sibling_body.clone(),
+ ]
+ } else if layers == 3 {
+ vec![deep_body.clone(), quoted_body.clone(), sibling_body.clone()]
+ } else {
+ // Further quoting leaves a backslash after the payload, which is not
+ // a valid URI terminator for text-only scanning.
+ vec![deep_body.clone(), sibling_body.clone()]
+ };
+ assert_eq!(bodies, expected_bodies, "embedded layers: {layers}");
+ let mut expected = input;
+ for media in &result.media {
+ expected = expected.replacen(&media.original_value().unwrap(), &media.reference(), 1);
+ }
+ assert_eq!(String::from_utf8(result.compact_json).unwrap(), expected);
+ }
+}
+
+#[test]
+fn scans_unicode_escaped_provider_keys_in_nested_json() {
+ let (encoded, body) = large_base64(b"unicode-key");
+ let nested = format!(r#"{{"type":"base64","media_\u0074ype":"image/png","data":"{encoded}"}}"#);
+ let encoded_nested = serde_json::to_string(&nested).expect("serialize nested JSON");
+ let input = format!(r#"{{"text":{encoded_nested}}}"#);
+
+ let result = extract_media(input.as_bytes()).expect("valid nested provider JSON");
+
+ assert_eq!(result.media.len(), 1);
+ assert_eq!(result.media[0].decode().unwrap(), body);
+}
+
+#[test]
+fn recognizes_provider_shapes_and_python_bytes() {
+ let (encoded, encoded_body) = large_base64(b"provider");
+ let mut python_body = vec![b'x'; MIN_EARLY_MEDIA_BYTES];
+ python_body[..4].copy_from_slice(b"abcd");
+ let python_literal = format!("b'{}'", String::from_utf8(python_body.clone()).unwrap());
+ let input = format!(
+ r#"[{{"type":"media","mime_type":"image/png","data":"{encoded}"}},{{"type":"file","mediaType":"image/png","data":"{python_literal}"}}]"#
+ );
+ let result = extract_media(input.as_bytes()).expect("valid JSON");
+ assert_eq!(result.media.len(), 2);
+ assert_eq!(result.media[0].kind, MediaPayloadKind::Vertex);
+ assert_eq!(result.media[1].kind, MediaPayloadKind::AiSdkV6);
+ assert_eq!(result.media[0].decode().unwrap(), encoded_body);
+ assert_eq!(result.media[1].decode().unwrap(), python_body);
+}
+
+#[test]
+fn data_uri_provider_fields_use_the_uri_metadata() {
+ let (uri, body) = large_data_uri(b"provider-uri");
+ for input in [
+ format!(r#"{{"type":"file","mediaType":"image/jpeg","data":"{uri}"}}"#),
+ format!(r#"{{"type":"base64","media_type":"image/jpeg","data":"{uri}"}}"#),
+ ] {
+ let result = extract_media(input.as_bytes()).expect("valid provider Data URI");
+
+ assert_eq!(result.media.len(), 1);
+ let media = &result.media[0];
+ assert_eq!(media.kind, MediaPayloadKind::DataUri);
+ assert_eq!(media.metadata.content_type, "image/png");
+ assert_eq!(media.metadata.source, MediaSource::Base64DataUri);
+ assert_eq!(media.decode().unwrap(), body);
+ }
+}
+
+#[test]
+fn nested_provider_original_value_preserves_inner_json_escapes() {
+ let (base64, base64_body) = large_base64(b"escaped");
+ let escaped_base64 = format!(
+ r#"data:image/png;base64,\u{:04x}{}"#,
+ base64.as_bytes()[0],
+ &base64[1..]
+ );
+ let slash_body = vec![0xff; MIN_EARLY_MEDIA_BYTES];
+ let slash_base64 = BASE64.encode(&slash_body);
+ let escaped_slashes = format!("data:image/png;base64,\\/\\/\\/\\/{}", &slash_base64[4..]);
+ let python_body = {
+ let mut body = vec![b'x'; MIN_EARLY_MEDIA_BYTES];
+ body[0] = b'"';
+ body
+ };
+ let python_source = format!("b'\\u0022{}'", "x".repeat(MIN_EARLY_MEDIA_BYTES - 1));
+ let cases = [
+ (
+ format!(r#"{{"type":"file","mediaType":"image/png","data":"{escaped_base64}"}}"#),
+ escaped_base64,
+ format!("data:image/png;base64,{}", base64),
+ base64_body,
+ ),
+ (
+ format!(r#"{{"type":"file","mediaType":"image/png","data":"{escaped_slashes}"}}"#),
+ escaped_slashes,
+ format!("data:image/png;base64,{}", slash_base64),
+ slash_body,
+ ),
+ (
+ format!(r#"{{"type":"file","mediaType":"text/plain","data":"{python_source}"}}"#),
+ python_source,
+ format!("b'{}'", String::from_utf8_lossy(&python_body)),
+ python_body,
+ ),
+ ];
+
+ for (nested, expected_original, expected_decoded, expected_body) in cases {
+ let encoded_nested = serde_json::to_string(&nested).expect("serialize nested JSON");
+ let input = format!(r#"{{"text":{encoded_nested}}}"#);
+ let result = extract_media(input.as_bytes()).expect("valid nested provider JSON");
+
+ assert_eq!(result.media.len(), 1, "nested source: {nested}");
+ assert_eq!(result.media[0].original_json_depth(), 1);
+ assert_eq!(
+ result.media[0].original_value().unwrap(),
+ expected_original,
+ "nested source: {nested}"
+ );
+ assert_eq!(
+ result.media[0].original_value_for_layers(Some(0)).unwrap(),
+ expected_decoded
+ );
+ assert_eq!(result.media[0].decode().unwrap(), expected_body);
+ }
+}
+
+#[test]
+fn nested_provider_source_spelling_survives_two_stringified_layers() {
+ let python_body = "x".repeat(MIN_EARLY_MEDIA_BYTES - 1);
+ let provider =
+ format!(r#"{{"type":"file","mediaType":"text/plain","data":"b'\u0022{python_body}'"}}"#);
+ let encoded_provider = serde_json::to_string(&provider)
+ .expect("serialize provider")
+ .replace("\\\"", "\\u0022");
+ let first_layer = format!(r#"{{"child":{}}}"#, encoded_provider);
+ let input = format!(
+ r#"{{"text":{}}}"#,
+ serde_json::to_string(&first_layer).expect("serialize first layer")
+ );
+ let result = extract_media(input.as_bytes()).expect("valid nested provider JSON");
+ assert_eq!(result.media.len(), 1);
+
+ let media = &result.media[0];
+ assert_eq!(media.original_json_depth(), 2);
+ let expected_original = format!(r#"b'\\u0022{}'"#, python_body);
+ assert_eq!(media.original_value().unwrap(), expected_original);
+ assert_eq!(
+ media.original_value_for_layers(Some(2)).unwrap(),
+ expected_original
+ );
+ assert_eq!(
+ media.original_value_for_layers(Some(1)).unwrap(),
+ format!(r#"b'\u0022{}'"#, python_body)
+ );
+ assert_eq!(
+ media.original_value_for_layers(Some(0)).unwrap(),
+ format!("b'\"{}'", python_body)
+ );
+ assert!(matches!(
+ media.original_value_for_layers(Some(17)),
+ Err(super::payload::MediaDecodeError::JsonLayerLimit)
+ ));
+
+ let compact: Value = serde_json::from_slice(&result.compact_json).unwrap();
+ let compact_first_layer = compact["text"].as_str().unwrap();
+ let reference = media.reference();
+ assert_eq!(
+ compact_first_layer.replace(&reference, &media.original_value().unwrap()),
+ first_layer
+ );
+}
+
+#[test]
+fn continues_to_the_next_gemini_shape_when_one_is_not_decodable() {
+ let (encoded, body) = large_base64(b"gemini");
+ let input = format!(
+ r#"{{"inline_data":{{"mime_type":1,"data":"{encoded}"}},"inlineData":{{"mimeType":"image/png","data":"{encoded}"}}}}"#
+ );
+ let result = extract_media(input.as_bytes()).expect("valid Gemini alternatives");
+
+ assert_eq!(result.media.len(), 1);
+ assert_eq!(result.media[0].kind, MediaPayloadKind::Gemini);
+ assert_eq!(result.media[0].decode().unwrap(), body);
+}
+
+#[test]
+fn keeps_embedded_provider_documents_in_payload_mode() {
+ let (encoded, body) = large_base64(b"embedded-provider");
+ let nested = format!(
+ r#"{{"scopeSpans":"provider field","type":"file","mediaType":"image/png","data":"{encoded}"}}"#
+ );
+ let encoded_nested = serde_json::to_string(&nested).expect("serialize nested JSON");
+ let input = format!(r#"{{"text":{encoded_nested}}}"#);
+
+ let result = extract_media(input.as_bytes()).expect("valid embedded provider JSON");
+
+ assert_eq!(result.media.len(), 1);
+ assert_eq!(result.media[0].decode().unwrap(), body);
+}
+
+#[test]
+fn classifies_each_root_array_object_before_discovery() {
+ let (provider_data, provider_body) = large_base64(b"provider-first");
+ let (envelope_uri, envelope_body) = large_data_uri(b"envelope-second");
+ let (structural_uri, _) = large_data_uri(b"structural-name");
+ let input = format!(
+ r#"[{{"type":"file","mediaType":"image/png","data":"{provider_data}"}},{{"scopeSpans":[{{"scope":{{"name":"{structural_uri}"}},"spans":[{{"attributes":[{{"key":"{structural_uri}","value":{{"stringValue":"{envelope_uri}"}}}}]}}]}}]}}]"#
+ );
+
+ let result = extract_media(input.as_bytes()).expect("valid mixed root array");
+
+ assert_eq!(result.media.len(), 2);
+ assert_eq!(result.media[0].decode().unwrap(), provider_body);
+ assert_eq!(result.media[1].decode().unwrap(), envelope_body);
+ let compact: Value = serde_json::from_slice(&result.compact_json).unwrap();
+ assert_eq!(compact[1]["scopeSpans"][0]["scope"]["name"], structural_uri);
+ assert_eq!(
+ compact[1]["scopeSpans"][0]["spans"][0]["attributes"][0]["key"],
+ structural_uri
+ );
+}
+
+#[test]
+fn extracts_repeated_small_nested_objects_without_a_resource_fallback() {
+ let (uri, body) = large_data_uri(b"deep");
+ let chain = (0..120).fold(format!("\"{uri}\""), |value, _| {
+ format!(r#"{{"x":{value}}}"#)
+ });
+ let input = format!(
+ "[{}]",
+ std::iter::repeat_n(chain, 32).collect::<Vec<_>>().join(",")
+ );
+ let (validated, scanned, index_bytes, _, _) =
+ validate_measured(input.as_bytes().to_vec()).expect("valid nested input stays native");
+ // Bound source revisits instead of relying on a wall-clock threshold.
+ assert!(
+ scanned <= 3 * input.len(),
+ "scanned {scanned} for {} source bytes",
+ input.len()
+ );
+ // Discovery state should scale with structure, not repeated siblings.
+ assert!(index_bytes <= 16 * input.len());
+ let result = validated.compact().unwrap();
+ assert_eq!(result.media.len(), 32);
+ assert!(result
+ .media
+ .iter()
+ .all(|media| media.decode().unwrap() == body));
+}
+
+#[test]
+fn indexed_subtrees_survive_mixed_siblings_and_provider_lookahead() {
+ let (uri, body) = large_data_uri(b"deep");
+ let (provider_data, provider_body) = large_base64(b"provider");
+ let chain = (0..118).fold(format!("\"{uri}\""), |value, level| {
+ if level % 2 == 0 {
+ format!(r#"{{"x":{value}}}"#)
+ } else {
+ format!("[{value}]")
+ }
+ });
+ let provider = format!(
+ r#"{{"inline_data":{{"mime_type":"image/png","data":"{provider_data}","other":[{{"x":[0]}}]}},"siblings":[{{}},[{{"x":[]}}]]}}"#
+ );
+ let payload = format!(r#"{{"first":[{chain},{provider}],"second":[{provider},{chain}]}}"#);
+ let envelope = format!(
+ r#"{{"resourceSpans":[{{"attributes":[{{"key":"input","value":{{"stringValue":{}}}}}]}}],"scopeSpans":[]}}"#,
+ serde_json::to_string(&payload).unwrap()
+ );
+ let embedded = serde_json::to_string(&payload).unwrap();
+ for (input, repetitions) in [
+ (payload.clone(), 1),
+ (embedded.clone(), 1),
+ (envelope.clone(), 1),
+ (format!("[{envelope},{payload}]"), 2),
+ (format!("[{payload},{envelope}]"), 2),
+ (format!(r#"{{"one":{embedded},"two":{embedded}}}"#), 2),
+ ] {
+ let (validated, scanned, index_bytes, _, _) =
+ validate_measured(input.as_bytes().to_vec()).unwrap();
+ assert!(
+ scanned <= 6 * input.len(),
+ "scanned {scanned} for {} source bytes",
+ input.len()
+ );
+ assert!(index_bytes <= 16 * input.len());
+ let result = validated.compact().unwrap();
+ let bodies = result
+ .media
+ .iter()
+ .map(|media| media.decode().unwrap())
+ .collect::<Vec<_>>();
+ assert_eq!(
+ bodies,
+ [
+ body.as_slice(),
+ provider_body.as_slice(),
+ provider_body.as_slice(),
+ body.as_slice()
+ ]
+ .repeat(repetitions)
+ );
+ }
+}
+
+#[test]
+fn existing_references_and_tiny_candidates_stay_inline_with_bounded_retention() {
+ let reference = format!(
+ "@@@langfuseMedia:type=image/png|id={}@@@",
+ "x".repeat(8 * 1024)
+ );
+ let references = (0..16_385)
+ .map(|index| format!("@@@langfuseMedia:type=image/png|id={index}@@@"))
+ .collect::<Vec<_>>();
+ let tiny_uri = data_uri(b"candidate");
+ let tiny_candidates = std::iter::repeat_n(tiny_uri.as_str(), 16 * 1024 + 1)
+ .collect::<Vec<_>>()
+ .join(" ");
+ for (text, retained_multiplier) in [
+ (reference, 3),
+ (references.join(" "), 3),
+ (tiny_candidates, 4),
+ ] {
+ let input = format!(r#"{{"existing":"{text}"}}"#);
+ let (validated, scanned, _, unique, retained_bytes) =
+ validate_measured(input.as_bytes().to_vec()).unwrap();
+ assert_eq!(unique, 0);
+ assert!(scanned <= 3 * input.len());
+ assert!(
+ retained_bytes <= retained_multiplier * input.len(),
+ "retained {retained_bytes} bytes for {} source bytes",
+ input.len()
+ );
+ let result = validated.compact().unwrap();
+ assert!(result.media.is_empty());
+ assert_eq!(result.compact_json, input.as_bytes());
+ }
+}
+
+#[test]
+fn unique_and_escaped_candidates_have_input_proportional_retention() {
+ let uris = (0..1_024u32)
+ .map(|value| {
+ let mut payload = vec![b'x'; MIN_EARLY_MEDIA_BYTES];
+ payload[..4].copy_from_slice(&value.to_le_bytes());
+ data_uri(&payload)
+ })
+ .collect::<Vec<_>>();
+ for escaped in [false, true] {
+ let values = uris
+ .iter()
+ .map(|uri| {
+ if escaped {
+ format!(
+ "\"{}\"",
+ uri.chars()
+ .map(|character| format!("\\u{:04x}", character as u32))
+ .collect::<String>()
+ )
+ } else {
+ serde_json::to_string(uri).unwrap()
+ }
+ })
+ .collect::<Vec<_>>()
+ .join(",");
+ let input = format!("[{values}]");
+ let (validated, scanned, _, unique, retained_bytes) =
+ validate_measured(input.as_bytes().to_vec()).unwrap();
+ assert_eq!(unique, uris.len());
+ assert!(scanned <= 3 * input.len());
+ // Escaped bodies may own decoded text, but must not retain a whole
+ // decoded document per entry.
+ assert!(retained_bytes <= 8 * input.len());
+ let result = validated.compact().unwrap();
+ assert_eq!(result.media.len(), uris.len());
+ }
+}
+
+#[test]
+fn validates_large_numbers_without_converting_them_to_floats_or_integers() {
+ let long_integer = "9".repeat(5_000);
+ let input = format!(
+ r#"{{"longInteger":{long_integer},"overflowingExponent":1e999999,"underflowingExponent":-1e-999999,"lexicalFloat":1.2300E+004}}"#
+ );
+
+ let result = extract_media(input.as_bytes()).expect("valid JSON number lexemes");
+ assert!(result.media.is_empty());
+ assert_eq!(result.compact_json, input.as_bytes());
+}
+
+#[test]
+fn structured_data_uri_must_occupy_the_entire_provider_field() {
+ let (uri, _) = large_data_uri(b"trailing");
+ let input = format!(r#"{{"type":"file","mediaType":"image/png","data":"{uri} trailing"}}"#);
+ let result = extract_media(input.as_bytes()).expect("valid JSON");
+ assert!(result.media.is_empty());
+ assert_eq!(result.compact_json, input.as_bytes());
+}
+
+#[test]
+fn matches_data_uri_parameter_validation() {
+ let (encoded, _) = large_base64(b"parameter");
+ let valid = format!(
+ r#"{{"type":"file","mediaType":"image/png","data":"data:image/png;charset=utf-8;base64,{encoded}"}}"#
+ );
+ let result = extract_media(valid.as_bytes()).expect("valid JSON");
+ assert_eq!(result.media.len(), 1);
+
+ let invalid = format!(
+ r#"{{"type":"file","mediaType":"image/png","data":"data:image/png;charset=not valid;base64,{encoded}"}}"#
+ );
+ let result = extract_media(invalid.as_bytes()).expect("valid JSON");
+ assert!(result.media.is_empty());
+ assert_eq!(result.compact_json, invalid.as_bytes());
+}
+
+#[test]
+fn leaves_invalid_python_bytes_literals_inline_like_typescript() {
+ for input in [
+ br#"{"type":"file","mediaType":"image/png","data":"b'text\u00e9'"}"#.as_slice(),
+ br#"{"type":"file","mediaType":"image/png","data":"b'abc\\'"}"#,
+ br#"{"type":"file","mediaType":"image/png","data":"b\"abc\\\""}"#,
+ ] {
+ let input = String::from_utf8_lossy(input)
+ .replace(
+ "text",
+ &format!("{}text", "x".repeat(MIN_EARLY_MEDIA_BYTES)),
+ )
+ .replace("abc", &"abc".repeat(MIN_EARLY_MEDIA_BYTES));
+ let result = extract_media(input.as_bytes()).expect("valid JSON");
+ assert!(result.media.is_empty(), "invalid literal extracted");
+ assert_eq!(result.compact_json, input.as_bytes());
+ }
+}
+
+#[test]
+fn leaves_invalid_and_unsupported_candidates_inline() {
+ let (valid, _) = large_data_uri(b"valid");
+ let prefix = "A".repeat(MIN_EARLY_MEDIA_BYTES);
+ let input = format!(
+ r#"{{"valid":"{valid}","invalid":"data:image/png;base64,{prefix}not#base64","invalid_padding":"data:image/png;base64,{prefix}AAAA===","unsupported":"data:application/x-unknown;base64,{prefix}aGk=","provider":{{"type":"base64","media_type":"image/png","data":"{prefix}AAAA==="}}}}"#
+ );
+ let result = extract_media(input.as_bytes()).expect("valid JSON");
+ assert_eq!(result.media.len(), 1);
+ let compact = String::from_utf8(result.compact_json).unwrap();
+ assert!(compact.contains("not#base64"));
+ assert!(compact.contains("AAAA==="));
+ assert!(compact.contains("application/x-unknown"));
+}
+
+#[test]
+fn never_rewrites_media_like_object_keys() {
+ let (uri, _) = large_data_uri(b"object-key");
+ let input = format!(r#"{{"{uri}":"ordinary value"}}"#);
+ let result = extract_media(input.as_bytes()).expect("valid JSON");
+ assert!(result.media.is_empty());
+ assert_eq!(result.compact_json, input.as_bytes());
+}
+
+#[test]
+fn extracts_user_payload_values_named_name_or_key() {
+ let (name_uri, _) = large_data_uri(b"payload-name");
+ let (key_uri, _) = large_data_uri(b"payload-key");
+ let (nested_uri, _) = large_data_uri(b"nested-name");
+ let input = serde_json::json!({
+ "type": 1,
+ "name": name_uri,
+ "payload": { "type": "file", "mediaType": 42, "key": key_uri },
+ "scope": { "name": nested_uri },
+ });
+ let source = serde_json::to_vec(&input).expect("serialize payload");
+ let result = extract_media(&source).expect("valid JSON");
+ let compact: Value = serde_json::from_slice(&result.compact_json).expect("compact JSON");
+
+ assert_eq!(result.media.len(), 3);
+ assert!(compact["name"]
+ .as_str()
+ .is_some_and(|value| value.starts_with(MEDIA_REFERENCE_PREFIX)));
+ assert!(compact["payload"]["key"]
+ .as_str()
+ .is_some_and(|value| value.starts_with(MEDIA_REFERENCE_PREFIX)));
+ assert!(compact["scope"]["name"]
+ .as_str()
+ .is_some_and(|value| value.starts_with(MEDIA_REFERENCE_PREFIX)));
+}
+
+#[test]
+fn does_not_extract_structural_otlp_strings_or_attribute_keys() {
+ let (uri, _) = large_data_uri(b"structural");
+ let input = serde_json::json!({
+ "resourceSpans": [{
+ "scopeSpans": [{
+ "scope": { "name": uri, "version": "1" },
+ "spans": [{
+ "name": uri,
+ "traceId": uri,
+ "data": uri,
+ "attributes": [{
+ "key": uri,
+ "value": { "stringValue": uri }
+ }]
+ }]
+ }]
+ }]
+ });
+ let source = serde_json::to_vec(&input).expect("serialize OTLP envelope");
+ let result = extract_media(&source).expect("valid JSON");
+
+ assert_eq!(result.media.len(), 1);
+ let compact: Value = serde_json::from_slice(&result.compact_json).expect("compact JSON");
+ assert_eq!(
+ compact["resourceSpans"][0]["scopeSpans"][0]["scope"]["name"],
+ uri
+ );
+ assert_eq!(
+ compact["resourceSpans"][0]["scopeSpans"][0]["spans"][0]["name"],
+ uri
+ );
+ assert_eq!(
+ compact["resourceSpans"][0]["scopeSpans"][0]["spans"][0]["traceId"],
+ uri
+ );
+ assert_eq!(
+ compact["resourceSpans"][0]["scopeSpans"][0]["spans"][0]["data"],
+ uri
+ );
+ assert_eq!(
+ compact["resourceSpans"][0]["scopeSpans"][0]["spans"][0]["attributes"][0]["key"],
+ uri
+ );
+ assert!(
+ compact["resourceSpans"][0]["scopeSpans"][0]["spans"][0]["attributes"][0]["value"]
+ ["stringValue"]
+ .as_str()
+ .is_some_and(|value| value.starts_with(MEDIA_REFERENCE_PREFIX))
+ );
+}
+
+#[test]
+fn recognizes_a_top_level_resource_span_array_as_an_otlp_envelope() {
+ let (uri, _) = large_data_uri(b"array-envelope");
+ let input = serde_json::json!([{
+ "scopeSpans": [{
+ "scope": { "name": uri },
+ "spans": [{
+ "name": uri,
+ "attributes": [{
+ "key": uri,
+ "value": { "stringValue": uri }
+ }]
+ }]
+ }]
+ }]);
+ let source = serde_json::to_vec(&input).expect("serialize OTLP envelope");
+ let result = extract_media(&source).expect("valid JSON");
+ let compact: Value = serde_json::from_slice(&result.compact_json).expect("compact JSON");
+
+ assert_eq!(result.media.len(), 1);
+ assert_eq!(compact[0]["scopeSpans"][0]["scope"]["name"], uri);
+ assert_eq!(compact[0]["scopeSpans"][0]["spans"][0]["name"], uri);
+ assert_eq!(
+ compact[0]["scopeSpans"][0]["spans"][0]["attributes"][0]["key"],
+ uri
+ );
+ assert!(
+ compact[0]["scopeSpans"][0]["spans"][0]["attributes"][0]["value"]["stringValue"]
+ .as_str()
+ .is_some_and(|value| value.starts_with(MEDIA_REFERENCE_PREFIX))
+ );
+}
+
+#[test]
+fn leaves_lone_surrogate_strings_inline_and_extracts_siblings() {
+ let (uri, body) = large_data_uri(b"sibling");
+ for text in [r"\ud800", r"\udc00", r"\ud800\u0061"] {
+ let input = format!(r#"{{"note":"{text}","image":"{uri}"}}"#);
+ let result = extract_media(input.as_bytes()).expect("raw surrogate escape is valid JSON");
+ assert_eq!(result.media.len(), 1);
+ assert_eq!(result.media[0].decode().unwrap(), body);
+ assert!(String::from_utf8(result.compact_json)
+ .unwrap()
+ .contains(text));
+ }
+ let input = br#"{"value":"\ud83d\ude80"}"#;
+ assert_eq!(extract_media(input).unwrap().compact_json, input);
+ for input in [br#"{"x":"\q"}"#.as_slice(), br#"{"x":"\ud800\uZZZZ"}"#] {
+ assert!(matches!(
+ extract_media(input),
+ Err(EarlyMediaError::InvalidJson { .. })
+ ));
+ }
+}
+
+#[test]
+fn malformed_utf8_is_replaced_before_discovery() {
+ let (uri, body) = large_data_uri(b"abc");
+ let mut input = b"{\"note\":\"".to_vec();
+ input.extend([0xff, 0xe2, 0x82]);
+ input.extend_from_slice(format!(r#"","image":"{uri}"}}"#).as_bytes());
+ let result = extract_media(&input).unwrap();
+ let compact: Value = serde_json::from_slice(&result.compact_json).unwrap();
+ assert_eq!(compact["note"], "��");
+ assert_eq!(result.media[0].decode().unwrap(), body);
+ assert_eq!(result.media[0].original_value().unwrap(), uri);
+}
+
+#[test]
+fn embedded_json_keeps_surrogate_strings_and_extracts_sibling_fields() {
+ let (uri, body) = large_data_uri(b"embedded");
+ let nested = format!(r#"{{"note":"\ud800","image":"{uri}"}}"#);
+ let input = serde_json::to_string(&nested).unwrap();
+ let result = extract_media(input.as_bytes()).expect("embedded surrogate remains inline");
+ assert_eq!(result.media.len(), 1);
+ assert_eq!(result.media[0].decode().unwrap(), body);
+ let expected = input.replace(&uri, &result.media[0].reference());
+ assert_eq!(String::from_utf8(result.compact_json).unwrap(), expected);
+}
+
+#[test]
+fn undecodable_keys_leave_their_values_inline_including_shadowed_values() {
+ // Undecodable keys cannot participate in last-key-wins resolution. Preserve
+ // their values while still extracting ordinary siblings.
+ let (uri, body) = large_data_uri(b"sibling");
+ let object = format!(r#"{{"\ud800":"{uri}","\uD800":"{uri}","ok":"{uri}"}}"#);
+ for input in [object.to_owned(), serde_json::to_string(&object).unwrap()] {
+ let result = extract_media(input.as_bytes()).unwrap();
+ assert_eq!(result.media.len(), 1);
+ assert_eq!(result.media[0].decode().unwrap(), body);
+ let restored = String::from_utf8(result.compact_json).unwrap().replace(
+ &result.media[0].reference(),
+ &result.media[0].original_value().unwrap(),
+ );
+ assert_eq!(restored, input);
+ }
+}
+
+#[test]
+fn rejects_raw_controls_at_any_position_in_a_string() {
+ for control in 0u8..=0x1f {
+ for prefix_len in [0, 1, 127, 1023, 1024, 4095] {
+ let mut input = br#"{"value":""#.to_vec();
+ input.extend(std::iter::repeat_n(b'x', prefix_len));
+ input.push(control);
+ input.extend_from_slice("tail🔥\\\"".as_bytes());
+ input.extend_from_slice(br#""}"#);
+
+ assert!(matches!(
+ validate(input),
+ Err(EarlyMediaError::InvalidJson { .. })
+ ));
+ }
+ }
+}
+
+#[test]
+fn malformed_envelope_takes_precedence_over_nested_media_ambiguity() {
+ let encoded = BASE64.encode(b"abc");
+ let embedded = format!(
+ r#"[{{"type":"file","mediaType":"image/png","data":"{encoded}"}},{{"type":"file","mediaType":"image/png","data":"b'abc'"}}]"#
+ );
+ let envelope = json!({
+ "resourceSpans": [{
+ "scopeSpans": [{
+ "spans": [{
+ "attributes": [{
+ "key": "input",
+ "value": {"stringValue": embedded},
+ }],
+ }],
+ }],
+ }],
+ });
+ let mut input = serde_json::to_string(&envelope).unwrap();
+ input.pop();
+ input.push_str(r#", "malformed":}"#);
+
+ assert!(matches!(
+ extract_media(input.as_bytes()),
+ Err(EarlyMediaError::InvalidJson { .. })
+ ));
+}
+
+#[test]
+fn existing_public_references_are_preserved_beside_new_occurrences() {
+ let (uri, _) = large_data_uri(b"collision");
+ let (reference, _) = media_identity_from_encoded(
+ uri.as_bytes(),
+ "image/png",
+ MediaSource::Base64DataUri,
+ MediaEncoding::Base64DataUri,
+ )
+ .unwrap();
+ let (encoded, _) = large_base64(b"structured");
+ let (structured_reference, _) = media_identity_from_encoded(
+ encoded.as_bytes(),
+ "image/png",
+ MediaSource::Bytes,
+ MediaEncoding::Base64,
+ )
+ .unwrap();
+ let nested = format!(r#"{{"existing":"\u0040{}"}}"#, &reference[1..]);
+ let encoded_nested = serde_json::to_string(&nested).unwrap();
+ for (input, expected_reference) in [
+ (
+ format!(r#"{{"input":"{uri}","existing":"{reference}"}}"#),
+ reference.clone(),
+ ),
+ (
+ format!(
+ r#"{{"type":"base64","media_type":"image/png","data":"{encoded}","other":"{structured_reference}"}}"#
+ ),
+ structured_reference.clone(),
+ ),
+ (
+ format!(
+ r#"{{"inline_data":{{"mime_type":"image/png","data":"{encoded}","other":"{structured_reference}"}}}}"#
+ ),
+ structured_reference,
+ ),
+ (
+ format!(r#"{{"input":"{uri}","nested":{encoded_nested}}}"#),
+ reference,
+ ),
+ ] {
+ let result = extract_media(input.as_bytes()).unwrap();
+ assert_eq!(result.media.len(), 1);
+ let pending = result.media[0].reference();
+ assert_ne!(pending, expected_reference);
+ let restored = String::from_utf8(result.compact_json)
+ .unwrap()
+ .replace(&pending, &result.media[0].original_value().unwrap());
+ assert_eq!(restored, input);
+ }
+}
+
+proptest! {
+ #[test]
+ fn same_content_occurrences_keep_unique_references_and_each_spelling(
+ body in prop::collection::vec(
+ prop::sample::select(b"abcdefghijklmnopqrstuvwxyz0123456789".to_vec()),
+ MIN_EARLY_MEDIA_BYTES..=MIN_EARLY_MEDIA_BYTES + 32,
+ ),
+ ) {
+ let encoded = BASE64.encode(&body);
+ let python_literal = format!("b'{}'", String::from_utf8(body.clone()).unwrap());
+ for (first, second) in [
+ (python_literal.as_str(), python_literal.as_str()),
+ (encoded.as_str(), python_literal.as_str()),
+ ] {
+ let input = format!(
+ r#"[{{"type":"file","mediaType":"image/png","data":"{first}"}},{{"type":"file","mediaType":"image/png","data":"{second}"}}]"#
+ );
+ let result = extract_media(input.as_bytes()).expect("valid duplicate providers");
+ prop_assert_eq!(result.media.len(), 2);
+ let first_media = &result.media[0];
+ let second_media = &result.media[1];
+ let first_reference = first_media.reference();
+ let second_reference = second_media.reference();
+ prop_assert_ne!(first_reference.as_str(), second_reference.as_str());
+ prop_assert_eq!(
+ &first_media.metadata.sha256_hash,
+ &second_media.metadata.sha256_hash
+ );
+ prop_assert_eq!(first_media.original_value().unwrap(), first);
+ prop_assert_eq!(second_media.original_value().unwrap(), second);
+ let first_decoded = first_media.decode().unwrap();
+ let second_decoded = second_media.decode().unwrap();
+ prop_assert_eq!(first_decoded.as_slice(), body.as_slice());
+ prop_assert_eq!(second_decoded.as_slice(), body.as_slice());
+ let expected = input
+ .replacen(first, &first_reference, 1)
+ .replacen(second, &second_reference, 1);
+ prop_assert_eq!(String::from_utf8(result.compact_json).unwrap(), expected);
+ }
+ }
+
+ #[test]
+ fn structural_work_stays_proportional_across_depth_width_and_embedded_json(
+ depth in 0usize..120,
+ width in 1usize..32,
+ embedded in any::<bool>(),
+ object_root in any::<bool>(),
+ body in prop_oneof![
+ prop::collection::vec(any::<u8>(), 1..24),
+ prop::collection::vec(any::<u8>(), MIN_EARLY_MEDIA_BYTES..=MIN_EARLY_MEDIA_BYTES + 32),
+ ],
+ ) {
+ let uri = data_uri(&body);
+ let chain = (0..depth).fold(format!("\"{uri}\""), |value, level| {
+ if level % 2 == 0 { format!(r#"{{"x":{value}}}"#) } else { format!("[{value}]") }
+ });
+ let mut input = format!("[{}]", std::iter::repeat_n(chain, width).collect::<Vec<_>>().join(","));
+ if object_root { input = format!(r#"{{"items":{input}}}"#); }
+ if embedded { input = serde_json::to_string(&input).unwrap(); }
+ let (validated, scanned, index_bytes, unique, _) =
+ validate_measured(input.as_bytes().to_vec()).unwrap();
+ // Embedded documents are validated separately, but each structural pass
+ // remains linear in that document's source size.
+ prop_assert!(scanned <= 6 * input.len(), "{} syntax bytes for {} input bytes", scanned, input.len());
+ // The walk retains open frames and candidates, not closed containers.
+ // Allow fixed initial capacities as well as depth and result growth.
+ prop_assert!(index_bytes <= 4096 + 512 * (depth + 3 + width), "{} index bytes", index_bytes);
+ let should_extract = uri.len() >= MIN_EARLY_MEDIA_BYTES;
+ prop_assert_eq!(unique, usize::from(should_extract));
+ let result = validated.compact().unwrap();
+ prop_assert_eq!(result.media.len(), if should_extract { width } else { 0 });
+ if !should_extract {
+ prop_assert_eq!(result.compact_json, input.as_bytes());
+ return Ok(());
+ }
+ for media in result.media { let decoded = media.decode().unwrap();
+ prop_assert_eq!(decoded.as_slice(), body.as_slice()); }
+ }
+
+ #[test]
+ fn media_prefilter_matches_substring_contract(
+ prefix in json_string_strategy(),
+ marker in prop::option::of(prop::sample::select(vec![
+ "data:", "@@@langfuseMedia:", "\\u", "media_type", "mime_type",
+ "mediaType", "mimeType", "inline_data", "inlineData",
+ ])),
+ suffix in json_string_strategy(),
+ ) {
+ let value = format!("{prefix}{}{suffix}", marker.unwrap_or(""));
+ let candidate = [
+ "data:", "@@@langfuseMedia:", "\\u", "media_type", "mime_type",
+ "mediaType", "mimeType", "inline_data", "inlineData",
+ ].iter().any(|marker| value.contains(marker));
+ prop_assert_eq!(may_contain_media_candidate(&value), candidate);
+ }
+
+ #[test]
+ fn valid_json_with_a_trailing_token_is_rejected(
+ value in json_value_strategy(6),
+ ) {
+ let mut source = serde_json::to_vec(&value).expect("serialize generated JSON");
+ let validated = validate(source.clone()).expect("generated JSON validates");
+ prop_assert_eq!(validated.into_source(), source.as_slice());
+ source.push(b'x');
+ let mut directed = br#"{"traceId":{"type":"Buffer","data":[1,2,3]},"text":"plain"}"#.to_vec();
+ directed.push(b'x');
+ let directed_rejected = matches!(
+ validate(directed),
+ Err(EarlyMediaError::TrailingBytes { .. })
+ );
+ prop_assert!(directed_rejected);
+ let validation_rejected = matches!(
+ validate(source.clone()),
+ Err(EarlyMediaError::TrailingBytes { .. })
+ | Err(EarlyMediaError::InvalidJson { .. })
+ );
+ prop_assert!(validation_rejected);
+ let rejected = matches!(
+ extract_media(&source),
+ Err(EarlyMediaError::TrailingBytes { .. })
+ | Err(EarlyMediaError::InvalidJson { .. })
+ );
+ prop_assert!(rejected);
+ }
+}
diff --git a/packages/native/src/otel_media_task.rs b/packages/native/src/otel_media_task.rs
new file mode 100644
index 0000000000..8a719da9ce
--- /dev/null
+++ b/packages/native/src/otel_media_task.rs
@@ -0,0 +1,59 @@
+//! Run OTEL media work with stage-level native instrumentation.
+
+use std::time::Instant;
+
+use napi::bindgen_prelude::*;
+
+use crate::native_task::{NativeResult, OwnedTask};
+
+const TIMED_MEDIA_OPERATIONS: [&str; 2] = ["validate", "extract"];
+
+pub struct OtelMediaTask<T> {
+ operation: &'static str,
+ inner: OwnedTask<T>,
+}
+
+impl<T: Send + ToNapiValue + TypeName + 'static> OtelMediaTask<T> {
+ pub(crate) fn run(
+ operation: &'static str,
+ work: impl FnOnce() -> NativeResult<T> + Send + 'static,
+ ) -> AsyncTask<Self> {
+ AsyncTask::new(Self {
+ operation,
+ inner: OwnedTask::new(work),
+ })
+ }
+}
+
+impl<T: Send + ToNapiValue + TypeName + 'static> Task for OtelMediaTask<T> {
+ type Output = NativeResult<T>;
+ type JsValue = T;
+
+ fn compute(&mut self) -> Result<Self::Output> {
+ let started = TIMED_MEDIA_OPERATIONS
+ .contains(&self.operation)
+ .then(Instant::now);
+ let _span = tracing::debug_span!("otel_media", operation = self.operation).entered();
+ let result = self.inner.compute()?;
+ if result
+ .as_ref()
+ .is_err_and(|error| error.status == "ERR_NATIVE_PANIC")
+ {
+ tracing::error!(operation = self.operation, "native task panicked");
+ }
+ if let Some(started) = started {
+ metrics::counter!("langfuse.native.otel_media.operations",
+ "operation" => self.operation,
+ "outcome" => result.as_ref().err().map_or("success", |error| error.status)
+ )
+ .increment(1);
+ metrics::histogram!("langfuse.native.otel_media.duration_ms", "operation" => self.operation)
+ .record(started.elapsed().as_secs_f64() * 1000.0);
+ }
+ Ok(result)
+ }
+
+ fn resolve(&mut self, env: Env, output: Self::Output) -> Result<T> {
+ self.inner.resolve(env, output)
+ }
+}
diff --git a/packages/shared/src/server/media/MediaPayloadProcessor.fixtures.ts b/packages/shared/src/server/media/MediaPayloadProcessor.fixtures.ts
new file mode 100644
index 0000000000..8cdfc69b68
--- /dev/null
+++ b/packages/shared/src/server/media/MediaPayloadProcessor.fixtures.ts
@@ -0,0 +1,94 @@
+// Payload examples shared by the TypeScript golden tests and the direct native
+// comparison. Raw duplicate-key cases live in the native suite because building
+// those through JavaScript objects would erase the input that needs testing.
+export const MEDIA_ID = "test-media-id";
+
+export const PNG_BYTES = Buffer.from("test-image");
+export const PNG_BASE64 = PNG_BYTES.toString("base64");
+export const DATA_URI = `data:image/png;base64,${PNG_BASE64}`;
+
+export const TEXT_BASE64 = Buffer.from("hello").toString("base64");
+export const TEXT_DATA_URI = `data:text/plain;charset=utf-8;base64,${TEXT_BASE64}`;
+
+export const DATA_URI_PUNCTUATIONS = [".", ";", "?", "!"] as const;
+export const REPEATED_DATA_PREFIX = "data:".repeat(256_000);
+export const REPEATED_DATA_URI_VALUE = `${REPEATED_DATA_PREFIX}${DATA_URI}`;
+
+export const providerMediaCases = [
+ {
+ name: "anthropic",
+ value: { type: "base64", media_type: "image/png", data: PNG_BASE64 },
+ referencePath: "data",
+ },
+ {
+ name: "vertex",
+ value: { type: "media", mime_type: "image/png", data: PNG_BASE64 },
+ referencePath: "data",
+ },
+ {
+ name: "gemini",
+ value: { inline_data: { mime_type: "image/png", data: PNG_BASE64 } },
+ referencePath: "inline_data.data",
+ },
+ {
+ name: "ai_sdk_v6",
+ value: { type: "file", mediaType: "image/png", data: PNG_BASE64 },
+ referencePath: "data",
+ },
+ {
+ name: "ai_sdk_v7",
+ value: { type: "blob", mime_type: "image/png", content: PNG_BASE64 },
+ referencePath: "content",
+ },
+] as const;
+
+export const MIXED_STRINGIFIED_VALUE = JSON.stringify({
+ image: DATA_URI,
+ document: providerMediaCases[0].value,
+});
+
+export const PYTHON_BYTES = Buffer.from([
+ 0xff,
+ 0xd8,
+ 0xff,
+ 0xe0,
+ ...Buffer.from("test\nquote'slash\\"),
+ 0x00,
+]);
+const PYTHON_BYTES_LITERAL =
+ "b'\\xff\\xd8\\xff\\xe0test\\nquote\\'slash\\\\\\x00'";
+export const PYTHON_STRINGIFIED_VALUE = JSON.stringify({
+ inline_data: {
+ mime_type: "image/jpeg",
+ data: PYTHON_BYTES_LITERAL,
+ },
+});
+export const MALFORMED_PYTHON_VALUE = {
+ inline_data: {
+ mime_type: "image/jpeg",
+ data: "b'\\xff\\x0g'",
+ },
+};
+
+function asJsonCase(name: string, value: unknown) {
+ return { name, json: JSON.stringify(value) };
+}
+
+export const mediaPayloadCases: { name: string; json: string }[] = [
+ asJsonCase("data_uri", DATA_URI),
+ ...DATA_URI_PUNCTUATIONS.map((punctuation) =>
+ asJsonCase(
+ `embedded_data_uri_${punctuation}`,
+ `media: ${DATA_URI}${punctuation}`,
+ ),
+ ),
+ asJsonCase("data_uri_with_parameters", TEXT_DATA_URI),
+ asJsonCase("repeated_data_prefix", REPEATED_DATA_URI_VALUE),
+ asJsonCase("repeated_prefix_without_media", "data: ".repeat(256_000)),
+ ...providerMediaCases.map(({ name, value }) =>
+ asJsonCase(`provider_${name}`, value),
+ ),
+ asJsonCase("mixed_stringified_json", MIXED_STRINGIFIED_VALUE),
+ asJsonCase("python_bytes", PYTHON_STRINGIFIED_VALUE),
+ asJsonCase("malformed_python_bytes", MALFORMED_PYTHON_VALUE),
+];
diff --git a/packages/shared/src/server/media/MediaPayloadProcessor.test.ts b/packages/shared/src/server/media/MediaPayloadProcessor.test.ts
index fc179708ef..c5e4363d8a 100644
--- a/packages/shared/src/server/media/MediaPayloadProcessor.test.ts
+++ b/packages/shared/src/server/media/MediaPayloadProcessor.test.ts
@@ -1,10 +1,20 @@
import { describe, expect, it, vi } from "vitest";
import { transformMediaPayload } from "./MediaPayloadProcessor";
-
-const PNG_BASE64 = Buffer.from("test-image").toString("base64");
-const MEDIA_REFERENCE =
- "@@@langfuseMedia:type=image/png|id=test-media-id|source=base64_data_uri@@@";
+import {
+ DATA_URI,
+ DATA_URI_PUNCTUATIONS,
+ MEDIA_ID,
+ MIXED_STRINGIFIED_VALUE,
+ PNG_BASE64,
+ REPEATED_DATA_PREFIX,
+ REPEATED_DATA_URI_VALUE,
+ TEXT_BASE64,
+ TEXT_DATA_URI,
+ providerMediaCases,
+} from "./MediaPayloadProcessor.fixtures";
+
+const MEDIA_REFERENCE = `@@@langfuseMedia:type=image/png|id=${MEDIA_ID}|source=base64_data_uri@@@`;
describe("transformMediaPayload", () => {
it("does not inspect ordinary text containing data prefixes", async () => {
@@ -51,8 +61,8 @@ describe("transformMediaPayload", () => {
it("scans adversarial repeated data prefixes in linear time", async () => {
const processCandidate = vi.fn().mockResolvedValue(MEDIA_REFERENCE);
const onDetectionPath = vi.fn();
- const repeatedPrefixes = "data:".repeat(256_000);
- const value = `${repeatedPrefixes}data:image/png;base64,${PNG_BASE64}`;
+ const repeatedPrefixes = REPEATED_DATA_PREFIX;
+ const value = REPEATED_DATA_URI_VALUE;
const startedAt = performance.now();
const transformed = await transformMediaPayload(value, {
@@ -76,7 +86,7 @@ describe("transformMediaPayload", () => {
it("processes each embedded data URI occurrence independently", async () => {
const processCandidate = vi.fn().mockResolvedValue(MEDIA_REFERENCE);
const onDetectionPath = vi.fn();
- const dataUri = `data:image/png;base64,${PNG_BASE64}`;
+ const dataUri = DATA_URI;
const transformed = await transformMediaPayload(
`${dataUri} between ${dataUri}`,
@@ -99,11 +109,11 @@ describe("transformMediaPayload", () => {
);
});
- it.each([".", ";", "?", "!"])(
+ it.each(DATA_URI_PUNCTUATIONS)(
"processes an embedded Data URI followed by %s",
async (punctuation) => {
const processCandidate = vi.fn().mockResolvedValue(MEDIA_REFERENCE);
- const dataUri = `data:image/png;base64,${PNG_BASE64}`;
+ const dataUri = DATA_URI;
const transformed = await transformMediaPayload(
`media: ${dataUri}${punctuation}`,
@@ -122,8 +132,7 @@ describe("transformMediaPayload", () => {
it("processes Data URIs with media type parameters", async () => {
const processCandidate = vi.fn().mockResolvedValue(MEDIA_REFERENCE);
- const textBase64 = Buffer.from("hello").toString("base64");
- const dataUri = `data:text/plain;charset=utf-8;base64,${textBase64}`;
+ const dataUri = TEXT_DATA_URI;
const transformed = await transformMediaPayload(`file: ${dataUri}`, {
processCandidate,
@@ -134,7 +143,7 @@ describe("transformMediaPayload", () => {
expect(transformed.value).toBe(`file: ${MEDIA_REFERENCE}`);
expect(processCandidate).toHaveBeenCalledWith({
- encodedData: textBase64,
+ encodedData: TEXT_BASE64,
encoding: "base64",
contentType: "text/plain",
kind: "data_uri",
@@ -146,15 +155,7 @@ describe("transformMediaPayload", () => {
const onDetectionPath = vi.fn();
await transformMediaPayload(
- JSON.stringify(
- {
- type: "base64",
- media_type: "image/png",
- data: PNG_BASE64,
- },
- null,
- 2,
- ),
+ JSON.stringify(providerMediaCases[0].value, null, 2),
{
processCandidate: vi.fn().mockResolvedValue(MEDIA_REFERENCE),
onInvalidCandidate: vi.fn(),
@@ -172,15 +173,7 @@ describe("transformMediaPayload", () => {
it("processes Data URIs and raw base64 shapes in the same stringified JSON", async () => {
const processCandidate = vi.fn().mockResolvedValue(MEDIA_REFERENCE);
- const dataUri = `data:image/png;base64,${PNG_BASE64}`;
- const value = JSON.stringify({
- image: dataUri,
- document: {
- type: "base64",
- media_type: "image/png",
- data: PNG_BASE64,
- },
- });
+ const value = MIXED_STRINGIFIED_VALUE;
const transformed = await transformMediaPayload(value, {
processCandidate,
@@ -225,9 +218,7 @@ describe("transformMediaPayload", () => {
it("processes structured normalized payloads without serializing them first", async () => {
const onDetectionPath = vi.fn();
- const value = {
- messages: [{ type: "base64", media_type: "image/png", data: PNG_BASE64 }],
- };
+ const value = { messages: [structuredClone(providerMediaCases[0].value)] };
const transformed = await transformMediaPayload(value, {
processCandidate: vi.fn().mockResolvedValue(MEDIA_REFERENCE),
diff --git a/packages/shared/src/server/otel/OtelMediaProcessor.test.ts b/packages/shared/src/server/otel/OtelMediaProcessor.test.ts
index 0428070f88..1015dac9be 100644
--- a/packages/shared/src/server/otel/OtelMediaProcessor.test.ts
+++ b/packages/shared/src/server/otel/OtelMediaProcessor.test.ts
@@ -10,6 +10,16 @@ vi.mock("../logger", () => ({
import type { MediaField } from "../../domain/media";
import { recordDistribution, recordIncrement } from "../instrumentation";
+import {
+ DATA_URI,
+ MEDIA_ID,
+ PNG_BYTES,
+ PNG_BASE64,
+ PYTHON_BYTES,
+ PYTHON_STRINGIFIED_VALUE,
+ MALFORMED_PYTHON_VALUE,
+ providerMediaCases,
+} from "../media/MediaPayloadProcessor.fixtures";
import {
processOtelMedia,
type OtelMediaPayload,
@@ -19,19 +29,6 @@ import {
const TRACE_ID = "0123456789abcdef0123456789abcdef";
const SPAN_ID = "0123456789abcdef";
-const MEDIA_ID = "test-media-id";
-const PNG_BYTES = Buffer.from("test-image");
-const PNG_BASE64 = PNG_BYTES.toString("base64");
-const PYTHON_BYTES = Buffer.from([
- 0xff,
- 0xd8,
- 0xff,
- 0xe0,
- ...Buffer.from("test\nquote'slash\\"),
- 0x00,
-]);
-const PYTHON_BYTES_LITERAL =
- "b'\\xff\\xd8\\xff\\xe0test\\nquote\\'slash\\\\\\x00'";
const MEDIA_REFERENCE = `@@@langfuseMedia:type=image/png|id=${MEDIA_ID}|source=base64_data_uri@@@`;
function createEvent(params: { value: unknown; field?: MediaField }): {
@@ -73,7 +70,7 @@ async function processEvents(
describe("processOtelMedia", () => {
it("uploads a normalized observation Data URI and replaces it after success", async () => {
- const dataUri = `data:image/png;base64,${PNG_BASE64}`;
+ const dataUri = DATA_URI;
const { event, body } = createEvent({ value: dataUri });
const uploadMedia = createUploadMock();
@@ -126,7 +123,7 @@ describe("processOtelMedia", () => {
});
it("tags reused media byte length separately from uploaded media", async () => {
- const dataUri = `data:image/png;base64,${PNG_BASE64}`;
+ const dataUri = DATA_URI;
const { event } = createEvent({ value: dataUri });
await processEvents([event], createUploadMock("reused"));
@@ -143,7 +140,7 @@ describe("processOtelMedia", () => {
});
it("processes every normalized media field and ignores unrelated fields", async () => {
- const dataUri = `data:image/png;base64,${PNG_BASE64}`;
+ const dataUri = DATA_URI;
const body = {
input: dataUri,
output: dataUri,
@@ -185,7 +182,7 @@ describe("processOtelMedia", () => {
});
it("replaces an embedded Data URI in a normalized string", async () => {
- const dataUri = `data:image/png;base64,${PNG_BASE64}`;
+ const dataUri = DATA_URI;
const { event, body } = createEvent({ value: `image: ${dataUri}` });
await processEvents([event]);
@@ -193,35 +190,9 @@ describe("processOtelMedia", () => {
expect(body.input).toBe(`image: ${MEDIA_REFERENCE}`);
});
- it.each([
- [
- "anthropic",
- { type: "base64", media_type: "image/png", data: PNG_BASE64 },
- "data",
- ],
- [
- "vertex",
- { type: "media", mime_type: "image/png", data: PNG_BASE64 },
- "data",
- ],
- [
- "gemini",
- { inline_data: { mime_type: "image/png", data: PNG_BASE64 } },
- "inline_data.data",
- ],
- [
- "ai_sdk_v6",
- { type: "file", mediaType: "image/png", data: PNG_BASE64 },
- "data",
- ],
- [
- "ai_sdk_v7",
- { type: "blob", mime_type: "image/png", content: PNG_BASE64 },
- "content",
- ],
- ])(
- "processes %s media in normalized structured values",
- async (_, mediaValue, referencePath) => {
+ it.each(providerMediaCases)(
+ "processes $name media in normalized structured values",
+ async ({ value: mediaValue, referencePath }) => {
const value = [structuredClone(mediaValue)];
const { event } = createEvent({ value });
const uploadMedia = createUploadMock();
@@ -256,12 +227,7 @@ describe("processOtelMedia", () => {
it("processes Gemini media serialized as a Python bytes literal", async () => {
const { event, body } = createEvent({
- value: JSON.stringify({
- inline_data: {
- mime_type: "image/jpeg",
- data: PYTHON_BYTES_LITERAL,
- },
- }),
+ value: PYTHON_STRINGIFIED_VALUE,
});
const uploadMedia = createUploadMock();
@@ -286,12 +252,7 @@ describe("processOtelMedia", () => {
});
it("leaves malformed Python bytes literals unchanged", async () => {
- const value = {
- inline_data: {
- mime_type: "image/jpeg",
- data: "b'\\xff\\x0g'",
- },
- };
+ const value = structuredClone(MALFORMED_PYTHON_VALUE);
const { event, body } = createEvent({ value });
const uploadMedia = createUploadMock();
@@ -304,7 +265,7 @@ describe("processOtelMedia", () => {
});
it("leaves normalized values unchanged when upload fails", async () => {
- const dataUri = `data:image/png;base64,${PNG_BASE64}`;
+ const dataUri = DATA_URI;
const { event, body } = createEvent({ value: dataUri });
const uploadMedia = vi.fn().mockRejectedValue(new Error("upload failed"));
@@ -372,7 +333,7 @@ describe("processOtelMedia", () => {
});
it("links trace-level media without an observation id", async () => {
- const dataUri = `data:image/png;base64,${PNG_BASE64}`;
+ const dataUri = DATA_URI;
const body = { input: dataUri };
const uploadMedia = createUploadMock();
diff --git a/worker/src/__tests__/nativeOtelMedia.unit.test.ts b/worker/src/__tests__/nativeOtelMedia.unit.test.ts
new file mode 100644
index 0000000000..1c51ba99c6
--- /dev/null
+++ b/worker/src/__tests__/nativeOtelMedia.unit.test.ts
@@ -0,0 +1,595 @@
+import { createHash } from "node:crypto";
+import { describe, expect, it, vi } from "vitest";
+import fc from "fast-check";
+import { validateOtelJson } from "@langfuse/native";
+import { MediaContentType } from "@langfuse/shared";
+import {
+ mediaPayloadCases,
+ PNG_BASE64,
+ TEXT_BASE64,
+} from "../../../packages/shared/src/server/media/MediaPayloadProcessor.fixtures";
+import { getMediaId } from "../../../packages/shared/src/server/media/mediaService";
+import { processOtelMedia } from "../../../packages/shared/src/server/otel/OtelMediaProcessor";
+
+vi.mock("../../../packages/shared/src/server/instrumentation", () => ({
+ recordDistribution: vi.fn(),
+ recordIncrement: vi.fn(),
+}));
+
+type MediaBody = { contentType: string; bytes: Buffer };
+
+const MEDIA_BODY = Buffer.from("hi".repeat(2048));
+const MEDIA_BASE64 = MEDIA_BODY.toString("base64");
+const MEDIA_URI = `data:image/png;base64,${MEDIA_BASE64}`;
+
+// These shared fixtures use tiny bodies. Enlarge their literal contents without
+// parsing their JSON: duplicate keys and escape spelling are part of the test.
+function extractionSizedFixture(json: string): string {
+ for (const encoded of [PNG_BASE64, TEXT_BASE64, "YWJj", "ZGVm", "aGk="]) {
+ json = json.replaceAll(encoded, "A".repeat(4096) + encoded);
+ }
+ return json.replace(/b'(?=[^'])/g, `b'${"a".repeat(4096)}`);
+}
+
+// Compare occurrences as a multiset: TS handles Data URIs before provider objects
+// in stringified JSON, while Rust visits their source order. The compact payload
+// separately verifies that every replacement occupies the right field.
+function sortedBodies(bodies: MediaBody[]): MediaBody[] {
+ return bodies.sort(
+ (a, b) =>
+ a.contentType.localeCompare(b.contentType) ||
+ Buffer.compare(a.bytes, b.bytes),
+ );
+}
+
+/**
+ * Native extraction keeps an occurrence-specific pending id until the upload
+ * adapter runs. Compare the resulting document with the TypeScript detector's
+ * public id without teaching this boundary test about the pending-id format.
+ */
+function canonicalizeNativeReferences(
+ value: unknown,
+ media: ReadonlyArray<{ reference: string; sha256Hash: string }>,
+): unknown {
+ if (typeof value === "string") {
+ return media.reduce(
+ (result, entry) =>
+ result
+ .split(entry.reference)
+ .join(
+ entry.reference.replace(
+ /\|id=[^|@]+/,
+ `|id=${getMediaId(entry.sha256Hash)}`,
+ ),
+ ),
+ value,
+ );
+ }
+ if (Array.isArray(value)) {
+ return value.map((item) => canonicalizeNativeReferences(item, media));
+ }
+ if (value !== null && typeof value === "object") {
+ return Object.fromEntries(
+ Object.entries(value).map(([key, item]) => [
+ key,
+ canonicalizeNativeReferences(item, media),
+ ]),
+ );
+ }
+ return value;
+}
+
+async function expectMediaParity(json: string): Promise<void> {
+ json = extractionSizedFixture(json);
+ const payload = { input: JSON.parse(json) as unknown };
+ const expectedBodies: MediaBody[] = [];
+ // Use the production TS detector and decoder; only the external upload is
+ // replaced. This branch never sees the native result.
+ await processOtelMedia({
+ targets: [{ traceId: "trace", observationId: "span", payload }],
+ projectId: "native-media-contract",
+ writePath: "direct",
+ mediaBucket: "test",
+ mediaPrefix: "test/",
+ uploadMedia: async ({ contentType, contentBytes }) => {
+ expectedBodies.push({ contentType, bytes: contentBytes });
+ return {
+ mediaId: getMediaId(
+ createHash("sha256").update(contentBytes).digest("base64"),
+ ),
+ outcome: "uploaded",
+ };
+ },
+ });
+
+ const validated = await validateOtelJson(Buffer.from(json));
+ try {
+ const batch = await validated.extract(true);
+ try {
+ // Assert at the NAPI boundary. Running the late TS detector here could
+ // repair a missed extraction and let a broken native implementation pass.
+ const compact = (await batch.takeJsonBuffer()).toString("utf8");
+ expect(
+ canonicalizeNativeReferences(JSON.parse(compact), batch.media),
+ ).toEqual(payload.input);
+ if (batch.media.length === 0) expect(compact).toBe(json);
+ const actualBodies: MediaBody[] = [];
+ for (const media of batch.media) {
+ const bytes = await batch.mediaBody(media.index);
+ expect(media.sha256Hash).toBe(
+ createHash("sha256").update(bytes).digest("base64"),
+ );
+ actualBodies.push({ contentType: media.contentType, bytes });
+ }
+ expect(sortedBodies(actualBodies)).toEqual(sortedBodies(expectedBodies));
+ } finally {
+ await batch.dispose();
+ }
+ } finally {
+ await validated.dispose();
+ }
+}
+
+describe(
+ "native media matches the TypeScript payload contract",
+ { retry: 0 },
+ () => {
+ it.each(mediaPayloadCases)("$name", ({ json }) => expectMediaParity(json));
+
+ it.each([
+ '{"type":"file","mediaType":"image/png","data":"YWJj","data":"ZGVm"}',
+ '{"type":"other","type":"file","mediaType":"text/plain","mediaType":"image/png","data":"ZGVm"}',
+ '{"inline_data":{"mime_type":"image/png","data":"YWJj"},"inline_data":{"mime_type":"image/png","data":"YWJj","data":"ZGVm"}}',
+ '{"inline_data":{"mime_type":"image/png","mimeType":"text/plain","data":"ZGVm"}}',
+ '{"inline_data":{"mime_type":null,"mimeType":"image/png","data":"ZGVm"}}',
+ '{"inlineData":{"mime_type":null,"mimeType":"image/png","data":"ZGVm"}}',
+ '{"type":1,"payload":{"type":"file","mediaType":42,"input":"data:image/png;base64,aGk="}}',
+ '{"type":"file","mediaType":42,"data":"aGk="}',
+ '{"type":"file","mediaType":"image/png","data":42,"image":"aGk="}',
+ '{"type":"file","mediaType":"image/png","data":"YWJj","image":"aGk="}',
+ JSON.stringify({ type: "file", mediaType: "image/png", data: "b''" }),
+ JSON.stringify("data:image/png;name=a\u00a0b;base64,aGk="),
+ JSON.stringify({
+ type: "file",
+ mediaType: "image/png",
+ data: "b'abc\\'",
+ }),
+ ])("preserves raw provider field semantics: %s", expectMediaParity);
+
+ it("extracts media from SDK JSON-string-wrapped OTLP metadata", async () => {
+ const providerBody = Buffer.from("provider attachment ".repeat(256));
+ const uriMetadata = JSON.stringify({ image: MEDIA_URI });
+ const rawUriMetadata = MEDIA_URI;
+ const providerMetadata = JSON.stringify({
+ type: "file",
+ mediaType: "image/png",
+ data: providerBody.toString("base64"),
+ });
+ const input = JSON.stringify({
+ resourceSpans: [
+ {
+ scopeSpans: [
+ {
+ spans: [
+ {
+ attributes: [
+ {
+ key: "metadata.attachment",
+ value: { stringValue: JSON.stringify(uriMetadata) },
+ },
+ {
+ key: "metadata.raw-attachment",
+ value: { stringValue: JSON.stringify(rawUriMetadata) },
+ },
+ {
+ key: "metadata.provider",
+ value: {
+ stringValue: JSON.stringify(providerMetadata),
+ },
+ },
+ ],
+ },
+ ],
+ },
+ ],
+ },
+ ],
+ });
+ const validated = await validateOtelJson(Buffer.from(input));
+ const batch = await validated.extract(true);
+ try {
+ expect(batch.media).toHaveLength(3);
+ expect(batch.media.map((media) => media.contentType)).toEqual([
+ "image/png",
+ "image/png",
+ "image/png",
+ ]);
+ await expect(batch.mediaBody(0)).resolves.toEqual(MEDIA_BODY);
+ await expect(batch.mediaBody(1)).resolves.toEqual(MEDIA_BODY);
+ await expect(batch.mediaBody(2)).resolves.toEqual(providerBody);
+
+ const compact = JSON.parse(
+ (await batch.takeJsonBuffer()).toString("utf8"),
+ ) as {
+ resourceSpans: Array<{
+ scopeSpans: Array<{
+ spans: Array<{
+ attributes: Array<{ value: { stringValue: string } }>;
+ }>;
+ }>;
+ }>;
+ };
+ const attributes =
+ compact.resourceSpans[0]!.scopeSpans[0]!.spans[0]!.attributes;
+ expect(
+ JSON.parse(JSON.parse(attributes[0]!.value.stringValue)),
+ ).toEqual({
+ image: batch.media[0]!.reference,
+ });
+ expect(JSON.parse(attributes[1]!.value.stringValue)).toBe(
+ batch.media[1]!.reference,
+ );
+ expect(
+ JSON.parse(JSON.parse(attributes[2]!.value.stringValue)),
+ ).toMatchObject({ data: batch.media[2]!.reference });
+ await expect(
+ batch.originalMedia(0, batch.media[0]!.originalJsonDepth),
+ ).resolves.toBe(MEDIA_URI);
+ await expect(
+ batch.originalMedia(1, batch.media[1]!.originalJsonDepth),
+ ).resolves.toBe(MEDIA_URI);
+ await expect(
+ batch.originalMedia(2, batch.media[2]!.originalJsonDepth),
+ ).resolves.toBe(providerBody.toString("base64"));
+ } finally {
+ await batch.dispose();
+ await validated.dispose();
+ }
+ });
+
+ it.each(["data:malformed@", "data:broken ", "data:bad,", "data:"])(
+ "finds a valid URI after %s",
+ (prefix) =>
+ expectMediaParity(
+ JSON.stringify(`${prefix}data:image/png;base64,aGk=`),
+ ),
+ );
+
+ it("matches Node decoding at Base64 length and padding boundaries", async () => {
+ for (let length = 0; length <= 20; length++) {
+ for (let padding = 0; padding <= 3; padding++) {
+ const data = "A".repeat(4096 + length) + "=".repeat(padding);
+ await expectMediaParity(
+ JSON.stringify([
+ `data:image/png;base64,${data}`,
+ { type: "file", mediaType: "image/png", data },
+ ]),
+ );
+ }
+ }
+ });
+
+ it("compares generated media spellings without canonicalizing raw JSON", async () => {
+ const encoded = fc
+ .array(
+ fc.constantFrom(
+ ..."ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/",
+ ),
+ {
+ minLength: 1,
+ maxLength: 48,
+ },
+ )
+ .map((parts) => parts.join(""));
+ await fc.assert(
+ fc.asyncProperty(
+ encoded,
+ fc.integer({ min: 0, max: 3 }),
+ fc.oneof(
+ fc.constantFrom("", "data:malformed@", "data:broken "),
+ // Keep both identifier boundaries and multibyte predecessors in
+ // the differential contract. Lone surrogates are covered by the
+ // separate intentionally-inline test below.
+ fc.constantFrom("a", "Z", "0", "-", "_", "é", "€", "😀"),
+ ),
+ async (body, padding, prefix) => {
+ const data = "A".repeat(4096) + body + "=".repeat(padding);
+ // Keep repeated keys in the source. Building a JS object first would
+ // erase the last-value-wins behavior this boundary needs to preserve.
+ await expectMediaParity(
+ `[{"type":"file","mediaType":"text/plain","mediaType":"image/png","data":"aGk=","data":${JSON.stringify(data)}},${JSON.stringify(`${prefix}data:image/png;base64,${data}`)}]`,
+ );
+ },
+ ),
+ { numRuns: 256 },
+ );
+ });
+
+ it.each(["deep objects", "many tiny media"] as const)(
+ "handles %s entirely through the native API",
+ async (shape) => {
+ const uri =
+ shape === "deep objects" ? MEDIA_URI : "data:image/png;base64,aGk=";
+ const count = shape === "deep objects" ? 32 : 16_385;
+ let value = JSON.stringify(uri);
+ if (shape === "deep objects") {
+ for (let depth = 0; depth < 200; depth++) value = `{"x":${value}}`;
+ }
+ const source = `[${Array.from({ length: count }, () => value).join(",")}]`;
+ const validated = await validateOtelJson(Buffer.from(source));
+ const batch = await validated.extract(true);
+ try {
+ const media = batch.media;
+ const compact = (await batch.takeJsonBuffer()).toString("utf8");
+ if (shape === "many tiny media") {
+ expect(media).toHaveLength(0);
+ expect(compact).toBe(source);
+ return;
+ }
+ expect(media).toHaveLength(count);
+ expect(compact).not.toContain(uri);
+ expect(compact.match(/@@@langfuseMedia:/g)).toHaveLength(count);
+ for (const index of [0, count - 1]) {
+ expect(await batch.mediaBody(index)).toEqual(MEDIA_BODY);
+ expect(await batch.originalMedia(index)).toBe(uri);
+ }
+ } finally {
+ await batch.dispose();
+ await validated.dispose();
+ }
+ },
+ );
+
+ it("sanitizes malformed UTF-8 before recording media offsets", async () => {
+ for (const sequence of [
+ [0xff],
+ [0xe2, 0x82],
+ [0xed, 0xa0, 0x80],
+ [0xf0, 0x28, 0x8c, 0x28],
+ ]) {
+ const bytes = Buffer.concat([
+ Buffer.from('{"note":"'),
+ Buffer.from(sequence),
+ Buffer.from(`","input":"${MEDIA_URI}"}`),
+ ]);
+ const validated = await validateOtelJson(bytes);
+ const normalized = Buffer.from(bytes.toString("utf8"));
+ expect(validated.normalizedBytes()).toEqual(normalized);
+ const batch = await validated.extract(true);
+ try {
+ expect(
+ JSON.parse((await batch.takeJsonBuffer()).toString("utf8")).note,
+ ).toBe(JSON.parse(normalized.toString("utf8")).note);
+ expect(batch.media).toHaveLength(1);
+ expect(await batch.mediaBody(0)).toEqual(MEDIA_BODY);
+ expect(await batch.originalMedia(0)).toBe(MEDIA_URI);
+ } finally {
+ await batch.dispose();
+ await validated.dispose();
+ }
+ }
+ });
+
+ it("leaves a surrogate-containing string inline while scanning siblings", async () => {
+ const embedded = JSON.stringify({
+ type: "file",
+ mediaType: "image/png",
+ data: MEDIA_BASE64,
+ note: "\ud800",
+ });
+ const input = JSON.stringify({
+ input: embedded,
+ sibling: MEDIA_URI,
+ });
+
+ const validated = await validateOtelJson(Buffer.from(input));
+ const batch = await validated.extract(true);
+ try {
+ expect(batch.media).toHaveLength(2);
+ const compact = JSON.parse(
+ (await batch.takeJsonBuffer()).toString("utf8"),
+ ) as {
+ input: string;
+ sibling: string;
+ };
+ expect(JSON.parse(compact.input)).toEqual({
+ type: "file",
+ mediaType: "image/png",
+ data: batch.media[0]?.reference,
+ note: "\ud800",
+ });
+ expect(compact.sibling).toBe(batch.media[1]?.reference);
+ for (const media of batch.media) {
+ await expect(batch.mediaBody(media.index)).resolves.toEqual(
+ MEDIA_BODY,
+ );
+ }
+ } finally {
+ await batch.dispose();
+ await validated.dispose();
+ }
+ });
+
+ it.each([
+ [
+ "embedded media ambiguity",
+ JSON.stringify({
+ input: JSON.stringify([
+ { type: "file", mediaType: "image/png", data: "YQ==" },
+ { type: "file", mediaType: "image/png", data: "b'a'" },
+ ]),
+ }),
+ ],
+ [
+ "embedded surrogate",
+ JSON.stringify({
+ input: JSON.stringify({
+ type: "file",
+ mediaType: "image/png",
+ data: "YQ==",
+ note: "\ud800",
+ }),
+ }),
+ ],
+ ] as const)(
+ "validates %s without media discovery",
+ async (_name, input) => {
+ const validated = await validateOtelJson(Buffer.from(input));
+ const batch = await validated.extract(false);
+ try {
+ expect(batch.media).toHaveLength(0);
+ expect((await batch.takeJsonBuffer()).toString("utf8")).toBe(input);
+ } finally {
+ await batch.dispose();
+ await validated.dispose();
+ }
+ },
+ );
+ },
+);
+
+it(
+ "extracts every MIME type supported by the TypeScript media service",
+ { retry: 0 },
+ async () => {
+ const contentTypes = Object.values(MediaContentType);
+ const validated = await validateOtelJson(
+ Buffer.from(
+ JSON.stringify(
+ contentTypes.map((type) => `data:${type};base64,${MEDIA_BASE64}`),
+ ),
+ ),
+ );
+ const batch = await validated.extract(true);
+ try {
+ expect(batch.media.map((media) => media.contentType)).toEqual(
+ contentTypes,
+ );
+ expect(
+ JSON.parse((await batch.takeJsonBuffer()).toString("utf8")),
+ ).toEqual(batch.media.map((media) => media.reference));
+ } finally {
+ await batch.dispose();
+ await validated.dispose();
+ }
+ },
+);
+
+it(
+ "owns input snapshots and in-flight media reads across handle disposal",
+ { retry: 0 },
+ async () => {
+ const uri = MEDIA_URI;
+ const source = Buffer.from(JSON.stringify({ input: uri }));
+ const validation = validateOtelJson(source);
+ source.fill(0); // JS retains a mutable Buffer; the async validator must own its snapshot.
+ const validated = await validation;
+ const pendingExtraction = validated.extract(true);
+ await validated.dispose();
+ const batch = await pendingExtraction;
+ try {
+ await expect(validated.extract(true)).rejects.toMatchObject({
+ code: "ERR_OTEL_CLOSED",
+ });
+ const [media] = batch.media;
+ const copied = await batch.copyJsonBuffer();
+ expect(Buffer.isBuffer(copied)).toBe(true);
+ expect(JSON.parse(copied.toString("utf8"))).toEqual({
+ input: media.reference,
+ });
+ const compact = batch.takeJsonBuffer();
+ expect(Buffer.isBuffer(compact)).toBe(true);
+ expect(JSON.parse(compact.toString("utf8"))).toEqual({
+ input: media.reference,
+ });
+ await expect(batch.copyJsonBuffer()).rejects.toMatchObject({
+ code: "ERR_OTEL_JSON_CONSUMED",
+ });
+ expect(() => batch.takeJsonBuffer()).toThrowError(
+ expect.objectContaining({ code: "ERR_OTEL_JSON_CONSUMED" }),
+ );
+ expect(media.sha256Hash).toBe(
+ createHash("sha256").update(MEDIA_BODY).digest("base64"),
+ );
+ await expect(batch.mediaBody(1)).rejects.toThrow("unknown media index");
+
+ const body = batch.mediaBody(media.index);
+ const original = batch.originalMedia(media.index);
+ await batch.dispose();
+ expect(compact.toString("utf8")).toContain(media.reference);
+ await expect(body).resolves.toEqual(MEDIA_BODY);
+ await expect(original).resolves.toBe(uri);
+ await expect(batch.copyJsonBuffer()).rejects.toMatchObject({
+ code: "ERR_OTEL_CLOSED",
+ });
+ expect(() => batch.takeJsonBuffer()).toThrowError(
+ expect.objectContaining({ code: "ERR_OTEL_CLOSED" }),
+ );
+ expect(() => batch.media).toThrowError(
+ expect.objectContaining({ code: "ERR_OTEL_CLOSED" }),
+ );
+ await expect(batch.mediaBody(0)).rejects.toMatchObject({
+ code: "ERR_OTEL_CLOSED",
+ });
+ await expect(batch.originalMedia(0)).rejects.toMatchObject({
+ code: "ERR_OTEL_CLOSED",
+ });
+
+ const copyValidated = await validateOtelJson(
+ Buffer.from(JSON.stringify({ input: uri })),
+ );
+ const copyBatch = await copyValidated.extract(true);
+ try {
+ const copyReference = copyBatch.media[0]!.reference;
+ const pendingCopy = copyBatch.copyJsonBuffer();
+ await copyBatch.dispose();
+ await copyValidated.dispose();
+ const copiedAfterDispose = await pendingCopy;
+ expect(JSON.parse(copiedAfterDispose.toString("utf8"))).toEqual({
+ input: copyReference,
+ });
+ } finally {
+ await copyBatch.dispose();
+ await copyValidated.dispose();
+ }
+ } finally {
+ await batch.dispose();
+ await validated.dispose();
+ }
+ },
+);
+
+it(
+ "pages large media descriptor registries with stable bounds",
+ { retry: 0 },
+ async () => {
+ const count = 4_097;
+ const uri = MEDIA_URI;
+ const validated = await validateOtelJson(
+ Buffer.from(JSON.stringify(Array.from({ length: count }, () => uri))),
+ );
+ const batch = await validated.extract(true);
+ try {
+ expect(batch.mediaCount()).toBe(count);
+ expect(batch.mediaPage(0, 2).map((entry) => entry.index)).toEqual([0, 1]);
+ expect(batch.mediaPage(4_095, 2).map((entry) => entry.index)).toEqual([
+ 4_095, 4_096,
+ ]);
+ expect(batch.mediaPage(count, 1)).toEqual([]);
+ expect(() => batch.mediaPage(0, 0)).toThrow(/media page limit/);
+ expect(() => batch.mediaPage(0, 4_097)).toThrow(/media page limit/);
+ expect(() => batch.mediaPage(count + 1, 1)).toThrow(/offset/);
+
+ await batch.dispose();
+ expect(() => batch.mediaCount()).toThrowError(
+ expect.objectContaining({ code: "ERR_OTEL_CLOSED" }),
+ );
+ expect(() => batch.mediaPage(0, 1)).toThrowError(
+ expect.objectContaining({ code: "ERR_OTEL_CLOSED" }),
+ );
+ } finally {
+ await batch.dispose();
+ await validated.dispose();
+ }
+ },
+);