WIP feat: agent-level HTTP client

Cargo.toml

@@ -51,6 +51,7 @@ members = [
   "libdd-tinybytes",
   "libdd-dogstatsd-client",
   "libdd-http-client",
+  "libdd-agent-client",
   "libdd-log",
   "libdd-log-ffi",
 ]

libdd-agent-client/Cargo.toml

@@ -0,0 +1,27 @@
+# Copyright 2026-Present Datadog, Inc. https://www.datadoghq.com/
+# SPDX-License-Identifier: Apache-2.0
+
+[package]
+name = "libdd-agent-client"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+authors.workspace = true
+description = "Datadog-agent-specialized HTTP client: language metadata injection, per-endpoint send methods, retry, and compression"
+homepage = "https://github.com/DataDog/libdatadog/tree/main/libdd-agent-client"
+repository = "https://github.com/DataDog/libdatadog/tree/main/libdd-agent-client"
+
+[lib]
+bench = false
+
+[dependencies]
+bytes = "1.4"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+thiserror = "2"
+tokio = { version = "1.23", features = ["rt"] }
+libdd-http-client = { path = "../libdd-http-client" }
+
+[dev-dependencies]
+tokio = { version = "1.23", features = ["rt", "macros"] }

libdd-agent-client/src/agent_info.rs

@@ -0,0 +1,30 @@
+// Copyright 2026-Present Datadog, Inc. https://www.datadoghq.com/
+// SPDX-License-Identifier: Apache-2.0
+
+//! Types for [`crate::AgentClient::agent_info`].
+
+/// Parsed response from a `GET /info` probe.
+///
+/// Returned by [`crate::AgentClient::agent_info`]. Contains agent capabilities and headers.
+#[derive(Debug, Clone)]
+pub struct AgentInfo {
+    /// Available agent endpoints, e.g. `["/v0.4/traces", "/v0.5/traces"]`.
+    pub endpoints: Vec<String>,
+    /// Whether the agent supports client-side P0 dropping.
+    pub client_drop_p0s: bool,
+    /// Raw agent configuration block.
+    pub config: serde_json::Value,
+    /// Agent version string, if reported.
+    pub version: Option<String>,
+    /// Parsed from the `Datadog-Container-Tags-Hash` response header.
+    ///
+    /// Used by dd-trace-py to compute the base tag hash (`agent.py:17-23`).
+    pub container_tags_hash: Option<String>,
+    /// Value of the `Datadog-Agent-State` response header from the last `/info` fetch.
+    ///
+    /// The agent updates this opaque token whenever its internal state changes (e.g. a
+    /// configuration reload). Clients that poll `/info` periodically can skip re-parsing
+    /// the response body by comparing this value to the one returned by the previous call
+    /// and only acting when it differs.
+    pub state_hash: Option<String>,
+}

libdd-agent-client/src/builder.rs

@@ -0,0 +1,193 @@
+// Copyright 2026-Present Datadog, Inc. https://www.datadoghq.com/
+// SPDX-License-Identifier: Apache-2.0
+
+//! Builder for [`crate::AgentClient`].
+
+use std::collections::HashMap;
+use std::time::Duration;
+
+use libdd_http_client::RetryConfig;
+
+use crate::{error::BuildError, language_metadata::LanguageMetadata, AgentClient};
+
+/// Default timeout for agent requests.
+pub const DEFAULT_TIMEOUT_MS: u64 = 2_000;
+
+/// Default retry configuration: 2 retries (3 total attempts), 100 ms initial delay,
+/// exponential backoff with full jitter.
+pub fn default_retry_config() -> RetryConfig {
+    todo!()
+}
+
+/// Transport configuration for the agent client.
+///
+/// Determines how the client connects to the Datadog agent.
+/// Set via [`AgentClientBuilder::transport`] or the convenience helpers
+/// [`AgentClientBuilder::http`], [`AgentClientBuilder::unix_socket`], etc.
+#[derive(Debug, Clone)]
+pub enum AgentTransport {
+    /// HTTP over TCP.
+    Http {
+        /// Hostname or IP address.
+        host: String,
+        /// Port number.
+        port: u16,
+    },
+    /// Unix Domain Socket.
+    ///
+    /// HTTP requests are still formed with `Host: localhost`. The socket path governs only the
+    /// transport layer.
+    #[cfg(unix)]
+    UnixSocket {
+        /// Filesystem path to the socket file.
+        path: std::path::PathBuf,
+    },
+    /// Windows Named Pipe.
+    #[cfg(windows)]
+    NamedPipe {
+        /// Named pipe path, e.g. `\\.\pipe\DD_APM_DRIVER`.
+        path: std::ffi::OsString,
+    },
+    /// Probe at build time: use UDS if the socket file exists, otherwise fall back to HTTP.
+    #[cfg(unix)]
+    AutoDetect {
+        /// UDS path to probe.
+        uds_path: std::path::PathBuf,
+        /// Fallback host when the socket is absent.
+        fallback_host: String,
+        /// Fallback port when the socket is absent (typically 8126).
+        fallback_port: u16,
+    },
+}
+
+impl Default for AgentTransport {
+    fn default() -> Self {
+        todo!()
+    }
+}
+
+/// Builder for [`AgentClient`].
+///
+/// Obtain via [`AgentClient::builder`].
+///
+/// # Required fields
+///
+/// - Transport: set via [`AgentClientBuilder::transport`] or a convenience method
+///   ([`AgentClientBuilder::http`], [`AgentClientBuilder::unix_socket`],
+///   [`AgentClientBuilder::windows_named_pipe`], [`AgentClientBuilder::auto_detect`]).
+/// - [`AgentClientBuilder::language_metadata`].
+///
+/// # Test tokens
+///
+/// Call [`AgentClientBuilder::test_agent_session_token`] to inject
+/// `x-datadog-test-session-token` on every request.
+#[derive(Debug, Default)]
+pub struct AgentClientBuilder {
+    transport: Option<AgentTransport>,
+    test_token: Option<String>,
+    timeout: Option<Duration>,
+    language: Option<LanguageMetadata>,
+    retry: Option<RetryConfig>,
+    keep_alive: bool,
+    extra_headers: HashMap<String, String>,
+}
+
+impl AgentClientBuilder {
+    /// Create a new builder with default settings.
+    pub fn new() -> Self {
+        todo!()
+    }
+
+    /// Set the transport configuration.
+    pub fn transport(self, transport: AgentTransport) -> Self {
+        todo!()
+    }
+
+    /// Convenience: HTTP over TCP.
+    pub fn http(self, host: impl Into<String>, port: u16) -> Self {
+        todo!()
+    }
+
+    /// Convenience: Unix Domain Socket.
+    #[cfg(unix)]
+    pub fn unix_socket(self, path: impl Into<std::path::PathBuf>) -> Self {
+        todo!()
+    }
+
+    /// Convenience: Windows Named Pipe.
+    #[cfg(windows)]
+    pub fn windows_named_pipe(self, path: impl Into<std::ffi::OsString>) -> Self {
+        todo!()
+    }
+
+    /// Convenience: auto-detect transport (UDS if socket file exists, else HTTP).
+    #[cfg(unix)]
+    pub fn auto_detect(
+        self,
+        uds_path: impl Into<std::path::PathBuf>,
+        fallback_host: impl Into<String>,
+        fallback_port: u16,
+    ) -> Self {
+        todo!()
+    }
+
+    /// Set the test session token.
+    ///
+    /// When set, `x-datadog-test-session-token: <token>` is injected on every request.
+    pub fn test_agent_session_token(self, token: impl Into<String>) -> Self {
+        todo!()
+    }
+
+    /// Set the request timeout.
+    ///
+    /// Defaults to [`DEFAULT_TIMEOUT_MS`] (2 000 ms) when not set.
+    pub fn timeout(self, timeout: Duration) -> Self {
+        todo!()
+    }
+
+    /// Read the timeout from `DD_TRACE_AGENT_TIMEOUT_SECONDS`, falling back to
+    /// [`DEFAULT_TIMEOUT_MS`] if the variable is unset or unparseable.
+    pub fn timeout_from_env(self) -> Self {
+        todo!()
+    }
+
+    /// Override the default retry configuration.
+    ///
+    /// Defaults to [`default_retry_config`].
+    pub fn retry(self, config: RetryConfig) -> Self {
+        todo!()
+    }
+
+    /// Set the language/runtime metadata injected into every request. Required.
+    pub fn language_metadata(self, meta: LanguageMetadata) -> Self {
+        todo!()
+    }
+
+    /// Enable or disable HTTP keep-alive. Defaults to `false`.
+    ///
+    /// The Datadog agent has a low keep-alive timeout that causes "pipe closed" errors on every
+    /// second connection when keep-alive is enabled. The default of `false` is correct for all
+    /// periodic-flush writers (traces, stats, data streams). Set to `true` only for
+    /// high-frequency continuous senders (e.g. a streaming profiling exporter).
+    pub fn use_keep_alive(mut self, enabled: bool) -> Self {
+        self.keep_alive = enabled;
+        self
+    }
+
+    // Compression
+    //
+    // Not exposed in this libv1. Gzip compression (level 6, matching dd-trace-py's trace writer at
+    // `writer.py:490`) will be added in a follow-up once the core send paths are stable.
+    // Per-method defaults (e.g. unconditional gzip for `send_pipeline_stats`) are already
+    // baked in; only the opt-in client-level `gzip(level)` builder knob is deferred.
+
+    /// Additional custom headers to inject.
+    pub fn extra_headers(self, headers: HashMap<String, String>) -> Self {
+        todo!()
+    }
+
+    /// Build the [`AgentClient`].
+    pub fn build(self) -> Result<AgentClient, BuildError> {
+        todo!()
+    }
+}

libdd-agent-client/src/client.rs

@@ -0,0 +1,98 @@
+// Copyright 2026-Present Datadog, Inc. https://www.datadoghq.com/
+// SPDX-License-Identifier: Apache-2.0
+
+//! [`AgentClient`] and its send methods.
+
+use bytes::Bytes;
+
+use crate::{
+    agent_info::AgentInfo,
+    builder::AgentClientBuilder,
+    error::SendError,
+    telemetry::TelemetryRequest,
+    traces::{AgentResponse, TraceFormat, TraceSendOptions},
+};
+
+/// A Datadog-agent-specialized HTTP client.
+///
+/// Wraps a configured [`libdd_http_client::HttpClient`] and injects Datadog-specific headers
+/// automatically on every request:
+///
+/// - Language metadata headers (`Datadog-Meta-Lang`, `Datadog-Meta-Lang-Version`,
+///   `Datadog-Meta-Lang-Interpreter`, `Datadog-Meta-Tracer-Version`) from the [`LanguageMetadata`]
+///   supplied when creating the client.
+/// - `User-Agent` derived from [`LanguageMetadata::user_agent`].
+/// - Container/entity-ID headers (`Datadog-Container-Id`, `Datadog-Entity-ID`,
+///   `Datadog-External-Env`) read from `/proc/self/cgroup` at startup.
+/// - `x-datadog-test-session-token` when a test token was set.
+/// - Any extra headers registered via [`AgentClientBuilder::extra_headers`].
+///
+/// Obtain via [`AgentClient::builder`].
+///
+/// [`LanguageMetadata`]: crate::LanguageMetadata
+pub struct AgentClient {
+    // Opaque — fields are an implementation detail.
+}
+
+impl AgentClient {
+    /// Create a new [`AgentClientBuilder`].
+    pub fn builder() -> AgentClientBuilder {
+        todo!()
+    }
+
+    /// Send a serialised trace payload to the agent with automatically injected headers.
+    ///
+    /// # Returns
+    ///
+    /// An [`AgentResponse`] with the HTTP status and the parsed `rate_by_service` sampling
+    /// rates from the agent response body.
+    pub async fn send_traces(
+        &self,
+        payload: Bytes,
+        trace_count: usize,
+        format: TraceFormat,
+        opts: TraceSendOptions,
+    ) -> Result<AgentResponse, SendError> {
+        todo!()
+    }
+
+    /// Send span stats (APM concentrator buckets) to `/v0.6/stats`.
+    pub async fn send_stats(&self, payload: Bytes) -> Result<(), SendError> {
+        todo!()
+    }
+
+    /// Send data-streams pipeline stats to `/v0.1/pipeline_stats`.
+    ///
+    /// The payload is **always** gzip-compressed regardless of the client-level compression
+    /// setting. This is a protocol requirement of the data-streams endpoint.
+    pub async fn send_pipeline_stats(&self, payload: Bytes) -> Result<(), SendError> {
+        todo!()
+    }
+
+    /// Send a telemetry event to the agent's telemetry proxy (`telemetry/proxy/api/v2/apmtelemetry`).
+    pub async fn send_telemetry(&self, req: TelemetryRequest) -> Result<(), SendError> {
+        todo!()
+    }
+
+    /// Send an event via the agent's EVP (Event Platform) proxy.
+    ///
+    /// The agent forwards the request to `<subdomain>.datadoghq.com<path>`. `subdomain`
+    /// controls the target intake (injected as `X-Datadog-EVP-Subdomain`); `path` is the
+    /// endpoint on that intake (e.g. `/api/v2/exposures`).
+    pub async fn send_evp_event(
+        &self,
+        subdomain: &str,
+        path: &str,
+        payload: Bytes,
+        content_type: &str,
+    ) -> Result<(), SendError> {
+        todo!()
+    }
+
+    /// Probe `GET /info` and return parsed agent capabilities.
+    ///
+    /// Returns `Ok(None)` when the agent returns 404 (remote-config / info not supported).
+    pub async fn agent_info(&self) -> Result<Option<AgentInfo>, SendError> {
+        todo!()
+    }
+}