feat(pipeline): add v0.5 output format selection

Add setUseV05() to WasmSpanState so the single trace exporter can emit the
v0.5 wire format (/v0.5/traces) instead of the default v0.4. The flag is read
once, at the lazy exporter build on first send, then fixed; callers must set
it before the first flush.

v0.5 uses a fixed 12-field schema with no slots for meta_struct, span_events,
or span_links, so libdatadog's v0.5 serializer silently drops them. This
mirrors dd-trace-js master's v0.5 encoder and is intentional \u2014 there is no
guard and no dual exporter. libdatadog does not downgrade V05 (unlike V1), so
the caller (dd-trace-js) is responsible for only enabling this after the agent
advertises /v0.5/traces via /info.

Author: bengl

crates/pipeline/src/lib.rs

@@ -1,6 +1,8 @@
 use libdatadog_nodejs_capabilities::WasmCapabilities;
 use libdd_data_pipeline::trace_exporter::agent_response::AgentResponse;
-use libdd_data_pipeline::trace_exporter::{TraceExporter, TraceExporterBuilder};
+use libdd_data_pipeline::trace_exporter::{
+    TraceExporter, TraceExporterBuilder, TraceExporterOutputFormat,
+};
 use libdd_shared_runtime::LocalRuntime;
 use std::cell::{Cell, RefCell, UnsafeCell};
 use std::ffi::CStr;
@@ -168,6 +170,16 @@ pub struct WasmSpanState {
     /// alias across the await (UB). The guard makes a re-entrant call return
     /// an error instead.
     sending: Cell<bool>,
+    /// When true, the lazily-built exporter is configured for v0.5 output
+    /// (`/v0.5/traces`) instead of the default v0.4. v0.5 is a smaller, fixed
+    /// 12-field schema with NO slots for `meta_struct`/`span_events`/`span_links`,
+    /// so libdatadog's v0.5 serializer silently drops them — this mirrors
+    /// dd-trace-js master's v0.5 encoder and is intentional. Caller (dd-trace-js)
+    /// must only enable this after confirming the agent advertises `/v0.5/traces`
+    /// (libdd does NOT downgrade V05 the way it does V1). The output format is
+    /// fixed once the exporter is built on the first send, so `setUseV05` only
+    /// takes effect if called before then.
+    use_v05: Cell<bool>,
 }
 
 /// Clears an in-flight flag on drop, so an early return or a dropped future
@@ -256,9 +268,22 @@ impl WasmSpanState {
             stats_collector: RefCell::new(stats_collector),
             prepared_spans: RefCell::new(None),
             sending: Cell::new(false),
+            use_v05: Cell::new(false),
         })
     }
 
+    /// Select v0.5 output for the trace exporter. Must be called before the
+    /// first `sendPreparedChunk` (the exporter is built lazily on first send and
+    /// the output format is fixed at build time; later calls have no effect).
+    ///
+    /// v0.5 silently drops `meta_struct` (and top-level `span_events`/`span_links`)
+    /// because the v0.5 wire schema has no slots for them — the caller is
+    /// responsible for only enabling this when the agent supports `/v0.5/traces`.
+    #[wasm_bindgen(js_name = "setUseV05")]
+    pub fn set_use_v05(&self, v: bool) {
+        self.use_v05.set(v);
+    }
+
     #[wasm_bindgen]
     pub fn change_queue_ptr(&self) -> *const u8 {
         self.change_queue.as_ptr()
@@ -373,9 +398,16 @@ impl WasmSpanState {
             // First send: build the exporter asynchronously. `build` is not
             // available on wasm (it needs a blocking runtime), so we drive
             // `build_async` here where we already have an async context.
-            let builder = unsafe { &mut *self.builder.get() }
+            let mut builder = unsafe { &mut *self.builder.get() }
                 .take()
                 .ok_or_else(|| JsValue::from_str("exporter builder already consumed"))?;
+            // Output format is decided here, at first build, and then fixed.
+            // v0.5 drops meta_struct/span_events/span_links by design (the v0.5
+            // schema has no slots for them); dd-trace-js only enables this after
+            // confirming agent `/v0.5/traces` support via `/info`.
+            if self.use_v05.get() {
+                builder.set_output_format(TraceExporterOutputFormat::V05);
+            }
             let built = builder
                 .build_async::<WasmCapabilities>()
                 .await

test/pipeline.js

@@ -781,6 +781,54 @@ describe('pipeline', () => {
     })
   })
 
+  describe('v0.5 output format', () => {
+    // Spin up a mock agent that records the request path, so we can assert the
+    // exporter targets /v0.4/traces by default and /v0.5/traces after
+    // setUseV05(true). (v0.5 itself drops meta_struct/span_events by design;
+    // here we only verify endpoint routing, which is the observable behavior.)
+    async function flushAndCapturePath (useV05) {
+      const http = require('node:http')
+      const seen = []
+      const server = http.createServer((req, res) => {
+        req.on('data', () => {})
+        req.on('end', () => {
+          seen.push({ method: req.method, url: req.url })
+          res.writeHead(200, { 'content-type': 'application/json' })
+          res.end('{}')
+        })
+      })
+      await new Promise(resolve => server.listen(0, '127.0.0.1', resolve))
+      const { port } = server.address()
+      const ns = new NativeSpansInterface({ agentUrl: `http://127.0.0.1:${port}` })
+      if (useV05) ns.state.setUseV05(true)
+      const span = ns.createSpan()
+      span.name = 'v05-span'
+      span.service = 'test-service'
+      span.resource = 'test-resource'
+      span.type = 'web'
+      span.duration = 1000000n
+      try {
+        await ns.flushSpans(span)
+        return seen.find(r => r.method === 'POST')
+      } finally {
+        server.closeAllConnections?.()
+        server.close()
+      }
+    }
+
+    it('targets /v0.4/traces by default', async () => {
+      const req = await flushAndCapturePath(false)
+      assert.ok(req, 'agent received a POST')
+      assert.strictEqual(req.url, '/v0.4/traces')
+    })
+
+    it('targets /v0.5/traces after setUseV05(true)', async () => {
+      const req = await flushAndCapturePath(true)
+      assert.ok(req, 'agent received a POST')
+      assert.strictEqual(req.url, '/v0.5/traces')
+    })
+  })
+
   describe('client-side stats', () => {
     it('aggregates and flushes stats to /v0.6/stats', async () => {
       const http = require('node:http')