Skip to main content

mutil_ai/
headers.rs

1use std::collections::BTreeMap;
2use std::fmt;
3use std::sync::Arc;
4use std::sync::atomic::{AtomicU64, Ordering};
5use std::time::Duration;
6
7use async_trait::async_trait;
8use reqwest::header::{
9    ACCEPT, AUTHORIZATION, CONTENT_LENGTH, CONTENT_TYPE, HOST, HeaderMap, HeaderName, HeaderValue,
10    USER_AGENT,
11};
12
13use crate::audit::{AuditConfig, AuditContext, AuditRequestMeta, AuditSink, ProfileAuditSnapshot};
14use crate::cancel::CancellationToken;
15use crate::error::{Error, Result};
16use crate::profile::ProviderRequestOptions;
17use crate::security::ResponseLimits;
18use crate::stream::StreamReconnectPolicy;
19use crate::transform::RequestTransform;
20
21/// Default `User-Agent` value, e.g. `mutil-ai/0.1.0`.
22pub const SDK_USER_AGENT: &str = concat!("mutil-ai/", env!("CARGO_PKG_VERSION"));
23
24const IDEMPOTENCY_KEY: &str = "idempotency-key";
25
26/// Product identity attached to requests.
27#[derive(Debug, Clone, PartialEq, Eq)]
28pub struct ClientInfo {
29    /// Application name; sanitized to a valid HTTP product token.
30    pub name: String,
31    /// Application version; sanitized to a valid HTTP product token.
32    pub version: String,
33    /// Optional per-deployment identifier, sent as `x-client-instance-id`.
34    pub instance_id: Option<String>,
35}
36
37impl ClientInfo {
38    /// Creates client identity from an application name and version.
39    pub fn new(name: impl Into<String>, version: impl Into<String>) -> Self {
40        Self {
41            name: name.into(),
42            version: version.into(),
43            instance_id: None,
44        }
45    }
46
47    /// Sets an optional per-deployment instance identifier.
48    pub fn instance_id(mut self, instance_id: impl Into<String>) -> Self {
49        self.instance_id = Some(instance_id.into());
50        self
51    }
52
53    /// Builds the combined `User-Agent` value:
54    /// `<name>/<version> <sdk-user-agent>`.
55    ///
56    /// # Errors
57    ///
58    /// Returns an error if the resulting value is not a valid HTTP header
59    /// value.
60    pub fn user_agent(&self) -> Result<HeaderValue> {
61        HeaderValue::from_str(&format!(
62            "{}/{} {}",
63            sanitize_product_token(&self.name),
64            sanitize_product_token(&self.version),
65            SDK_USER_AGENT
66        ))
67        .map_err(Error::from)
68    }
69}
70
71/// Per-request context. It is intentionally not automatically mapped to
72/// provider-specific headers such as `x-sessionid`.
73#[derive(Debug, Clone, Default, PartialEq, Eq)]
74pub struct RequestContext {
75    /// Correlation identifier for a single logical request.
76    pub request_id: Option<String>,
77    /// Session identifier, kept provider-neutral (not auto-mapped to
78    /// `x-sessionid`).
79    pub session_id: Option<String>,
80    /// Identifier grouping messages into one conversation.
81    pub conversation_id: Option<String>,
82    /// Multi-tenant identifier forwarded to header injectors.
83    pub tenant_id: Option<String>,
84    /// Distributed tracing identifier.
85    pub trace_id: Option<String>,
86    /// Free-form key/value pairs exposed to [`HeaderInjector::inject`].
87    pub attributes: BTreeMap<String, String>,
88}
89
90impl RequestContext {
91    /// Creates an empty context.
92    pub fn new() -> Self {
93        Self::default()
94    }
95
96    /// Sets the request correlation identifier.
97    pub fn request_id(mut self, request_id: impl Into<String>) -> Self {
98        self.request_id = Some(request_id.into());
99        self
100    }
101
102    /// Sets the session identifier.
103    pub fn session_id(mut self, session_id: impl Into<String>) -> Self {
104        self.session_id = Some(session_id.into());
105        self
106    }
107
108    /// Sets the tenant identifier.
109    pub fn tenant_id(mut self, tenant_id: impl Into<String>) -> Self {
110        self.tenant_id = Some(tenant_id.into());
111        self
112    }
113
114    /// Sets the distributed tracing identifier.
115    pub fn trace_id(mut self, trace_id: impl Into<String>) -> Self {
116        self.trace_id = Some(trace_id.into());
117        self
118    }
119
120    /// Sets one free-form attribute.
121    pub fn attribute(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
122        self.attributes.insert(key.into(), value.into());
123        self
124    }
125}
126
127/// Per-request transport options.
128#[derive(Clone, Default)]
129pub struct RequestOptions {
130    /// Request-level headers, subject to [`HeaderPolicy`] protection checks.
131    pub headers: HeaderMap,
132    /// Per-request `User-Agent` override.
133    pub user_agent: Option<HeaderValue>,
134    /// Correlation identifiers and attributes exposed to header injectors.
135    pub context: RequestContext,
136    /// Adds an `idempotency-key` header and enables automatic replay of
137    /// idempotent requests.
138    pub idempotency_key: Option<String>,
139    /// Total request timeout covering the whole exchange.
140    pub timeout: Option<Duration>,
141    /// Maximum time between bytes while reading an SSE stream.
142    pub idle_timeout: Option<Duration>,
143    /// Additional query parameters appended to the endpoint URL.
144    ///
145    /// Duplicate names are preserved. Protocol-reserved names are validated by
146    /// the adapter before the request is sent.
147    pub extra_query: Vec<(String, String)>,
148    /// Opt-in reconnect policy for a stream after it has started.
149    pub stream_reconnect: Option<StreamReconnectPolicy>,
150    /// Cooperative cancellation shared by all attempts and stream reads.
151    pub cancellation: Option<CancellationToken>,
152    /// Optional transform applied once before capability gating and
153    /// normalization.
154    pub request_transform: Option<Arc<dyn RequestTransform>>,
155    /// Typed provider request switches for this logical request.
156    pub provider_request: ProviderRequestOptions,
157    /// Per-request override for transport audit switches.
158    pub audit_config: Option<AuditConfig>,
159    /// Decoded response budgets shared across attempts and reconnects.
160    pub response_limits: ResponseLimits,
161}
162
163impl fmt::Debug for RequestOptions {
164    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
165        formatter
166            .debug_struct("RequestOptions")
167            .field("header_names", &self.headers.keys().collect::<Vec<_>>())
168            .field("user_agent", &self.user_agent)
169            .field("context", &"<redacted>")
170            .field(
171                "idempotency_key",
172                &self.idempotency_key.as_ref().map(|_| "<redacted>"),
173            )
174            .field("timeout", &self.timeout)
175            .field("idle_timeout", &self.idle_timeout)
176            .field(
177                "extra_query_names",
178                &self
179                    .extra_query
180                    .iter()
181                    .map(|(name, _)| name)
182                    .collect::<Vec<_>>(),
183            )
184            .field("stream_reconnect", &self.stream_reconnect)
185            .field("cancellation", &self.cancellation)
186            .field(
187                "request_transform",
188                &self.request_transform.as_ref().map(|_| "<configured>"),
189            )
190            .field("provider_request", &"<redacted>")
191            .field("audit_config", &self.audit_config)
192            .field("response_limits", &self.response_limits)
193            .finish()
194    }
195}
196
197impl RequestOptions {
198    /// Creates empty per-request options.
199    pub fn new() -> Self {
200        Self::default()
201    }
202
203    /// Replaces response byte/event budgets and raw/progress settings.
204    pub fn response_limits(mut self, limits: ResponseLimits) -> Self {
205        self.response_limits = limits;
206        self
207    }
208
209    /// Adds one request-level header, replacing any existing value with the
210    /// same name.
211    ///
212    /// # Errors
213    ///
214    /// Returns an error if the name is not a valid [`HeaderName`], the value
215    /// is not a valid [`HeaderValue`], or the value contains non-ASCII bytes.
216    pub fn header(mut self, name: impl AsRef<str>, value: impl AsRef<str>) -> Result<Self> {
217        let name = HeaderName::from_bytes(name.as_ref().as_bytes())?;
218        let value = HeaderValue::from_str(value.as_ref())?;
219        ensure_ascii_header_value(name.as_str(), value.as_bytes())?;
220        self.headers.insert(name, value);
221        Ok(self)
222    }
223
224    /// Merge a set of request-level headers.
225    ///
226    /// This is an alias for callers that already build a [`HeaderMap`]. Header
227    /// policy and protected-header validation are still applied when the
228    /// request is sent.
229    pub fn extra_headers(mut self, headers: HeaderMap) -> Self {
230        self.headers.extend(headers);
231        self
232    }
233
234    /// Append one query parameter without rewriting the endpoint URL.
235    pub fn extra_query(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
236        self.extra_query.push((name.into(), value.into()));
237        self
238    }
239
240    /// Enables opt-in reconnect for the stream after it has started.
241    pub fn stream_reconnect(mut self, policy: StreamReconnectPolicy) -> Self {
242        self.stream_reconnect = Some(policy);
243        self
244    }
245
246    /// Attaches a cooperative cancellation token shared by all attempts and
247    /// stream reads.
248    pub fn cancellation(mut self, token: CancellationToken) -> Self {
249        self.cancellation = Some(token);
250        self
251    }
252
253    /// Alias for [`RequestOptions::cancellation`].
254    pub fn cancellation_token(self, token: CancellationToken) -> Self {
255        self.cancellation(token)
256    }
257
258    /// Installs a request transform applied once before capability gating and
259    /// normalization.
260    pub fn request_transform(mut self, transform: impl RequestTransform + 'static) -> Self {
261        self.request_transform = Some(Arc::new(transform));
262        self
263    }
264
265    /// Replaces the typed provider request switches for this logical request.
266    pub fn provider_request(mut self, provider_request: ProviderRequestOptions) -> Self {
267        self.provider_request = provider_request;
268        self
269    }
270
271    /// Overrides the transport-level audit switches for this request.
272    pub fn audit_config(mut self, audit_config: AuditConfig) -> Self {
273        self.audit_config = Some(audit_config);
274        self
275    }
276
277    /// Overrides the `User-Agent` for this request.
278    ///
279    /// # Errors
280    ///
281    /// Returns an error if the value is not a valid [`HeaderValue`] or
282    /// contains non-ASCII bytes.
283    pub fn user_agent(mut self, user_agent: impl AsRef<str>) -> Result<Self> {
284        let user_agent = HeaderValue::from_str(user_agent.as_ref())?;
285        ensure_ascii_header_value("user-agent", user_agent.as_bytes())?;
286        self.user_agent = Some(user_agent);
287        Ok(self)
288    }
289
290    /// Replaces the per-request context.
291    pub fn context(mut self, context: RequestContext) -> Self {
292        self.context = context;
293        self
294    }
295
296    /// Sets the idempotency key sent as `idempotency-key`.
297    pub fn idempotency_key(mut self, key: impl Into<String>) -> Self {
298        self.idempotency_key = Some(key.into());
299        self
300    }
301
302    /// Sets the total request timeout.
303    pub fn timeout(mut self, timeout: Duration) -> Self {
304        self.timeout = Some(timeout);
305        self
306    }
307
308    /// Sets the maximum time between bytes while reading an SSE stream.
309    pub fn idle_timeout(mut self, idle_timeout: Duration) -> Self {
310        self.idle_timeout = Some(idle_timeout);
311        self
312    }
313
314    pub(crate) fn validate_query(&self, protocol: &'static str, reserved: &[&str]) -> Result<()> {
315        for (name, _) in &self.extra_query {
316            if reserved.contains(&name.as_str()) {
317                return Err(Error::ReservedExtraQuery {
318                    protocol,
319                    parameter: name.clone(),
320                });
321            }
322        }
323        Ok(())
324    }
325}
326
327/// Header names that an application must explicitly opt into overriding.
328#[derive(Debug, Clone)]
329pub struct HeaderPolicy {
330    protected: Vec<HeaderName>,
331    allow_override: Vec<HeaderName>,
332}
333
334impl Default for HeaderPolicy {
335    fn default() -> Self {
336        Self {
337            protected: vec![
338                AUTHORIZATION,
339                CONTENT_TYPE,
340                CONTENT_LENGTH,
341                HOST,
342                ACCEPT,
343                HeaderName::from_static("x-api-key"),
344                HeaderName::from_static("x-goog-api-key"),
345            ],
346            allow_override: Vec::new(),
347        }
348    }
349}
350
351impl HeaderPolicy {
352    /// Creates the default policy (standard sensitive headers protected).
353    pub fn new() -> Self {
354        Self::default()
355    }
356
357    /// Adds `name` to the protected set; requests may not override it unless
358    /// it is also explicitly allowed via [`Self::allow_override`].
359    pub fn protect(mut self, name: HeaderName) -> Self {
360        self.protected.push(name);
361        self
362    }
363
364    /// Explicitly allows overriding one protected header name.
365    pub fn allow_override(mut self, name: HeaderName) -> Self {
366        self.allow_override.push(name);
367        self
368    }
369
370    /// Returns whether `name` is protected and not open for override.
371    pub fn is_protected(&self, name: &HeaderName) -> bool {
372        self.protected.iter().any(|protected| protected == name)
373    }
374
375    /// Returns whether `name` was explicitly allowed to override protection.
376    pub fn can_override(&self, name: &HeaderName) -> bool {
377        self.allow_override.iter().any(|allowed| allowed == name)
378    }
379}
380
381/// Shared transport defaults for an adapter.
382#[derive(Clone)]
383pub struct TransportConfig {
384    /// Default `User-Agent` used when a request does not set its own.
385    pub user_agent: HeaderValue,
386    /// Static headers applied to every request from this transport.
387    pub default_headers: HeaderMap,
388    /// Optional client identity reported via `x-client-*` headers.
389    pub client_info: Option<ClientInfo>,
390    /// Policy deciding which headers applications may override.
391    pub header_policy: HeaderPolicy,
392    /// Trusted dynamic header provider (e.g. token refresh), applied by
393    /// [`TransportConfig::apply_to_async`].
394    pub header_injector: Option<Arc<dyn HeaderInjector>>,
395    /// Sink receiving audit events for this transport.
396    pub audit_sink: Option<Arc<dyn AuditSink>>,
397    /// Default audit switches, overridable per request.
398    pub audit_config: AuditConfig,
399    /// Shared sampler backing the `sample_every` audit setting.
400    audit_sample_counter: Arc<AtomicU64>,
401}
402
403impl fmt::Debug for TransportConfig {
404    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
405        formatter
406            .debug_struct("TransportConfig")
407            .field("user_agent", &self.user_agent)
408            .field(
409                "default_header_names",
410                &self.default_headers.keys().collect::<Vec<_>>(),
411            )
412            .field("client_info", &self.client_info)
413            .field("header_policy", &self.header_policy)
414            .field(
415                "header_injector",
416                &self.header_injector.as_ref().map(|_| "<injector>"),
417            )
418            .field(
419                "audit_sink",
420                &self.audit_sink.as_ref().map(|_| "<audit-sink>"),
421            )
422            .field("audit_config", &self.audit_config)
423            .finish()
424    }
425}
426
427impl Default for TransportConfig {
428    fn default() -> Self {
429        Self {
430            user_agent: HeaderValue::from_static(SDK_USER_AGENT),
431            default_headers: HeaderMap::new(),
432            client_info: None,
433            header_policy: HeaderPolicy::default(),
434            header_injector: None,
435            audit_sink: None,
436            audit_config: AuditConfig::default(),
437            audit_sample_counter: Arc::new(AtomicU64::new(0)),
438        }
439    }
440}
441
442impl TransportConfig {
443    /// Creates the default transport configuration.
444    pub fn new() -> Self {
445        Self::default()
446    }
447
448    /// Replaces the default `User-Agent`.
449    ///
450    /// # Errors
451    ///
452    /// Returns an error if the value is not a valid [`HeaderValue`] or
453    /// contains non-ASCII bytes.
454    pub fn user_agent(mut self, user_agent: impl AsRef<str>) -> Result<Self> {
455        let user_agent = HeaderValue::from_str(user_agent.as_ref())?;
456        ensure_ascii_header_value("user-agent", user_agent.as_bytes())?;
457        self.user_agent = user_agent;
458        Ok(self)
459    }
460
461    /// Adds one static default header applied to every request.
462    ///
463    /// # Errors
464    ///
465    /// Returns an error if the name is not a valid [`HeaderName`], the value
466    /// is not a valid [`HeaderValue`], or the value contains non-ASCII bytes.
467    pub fn header(mut self, name: impl AsRef<str>, value: impl AsRef<str>) -> Result<Self> {
468        let name = HeaderName::from_bytes(name.as_ref().as_bytes())?;
469        let value = HeaderValue::from_str(value.as_ref())?;
470        ensure_ascii_header_value(name.as_str(), value.as_bytes())?;
471        self.default_headers.insert(name, value);
472        Ok(self)
473    }
474
475    /// Attaches client identity reported via `x-client-*` headers.
476    pub fn client_info(mut self, client_info: ClientInfo) -> Self {
477        self.client_info = Some(client_info);
478        self
479    }
480
481    /// Replaces the header protection policy.
482    pub fn header_policy(mut self, header_policy: HeaderPolicy) -> Self {
483        self.header_policy = header_policy;
484        self
485    }
486
487    /// Installs a trusted dynamic header provider.
488    pub fn header_injector(mut self, header_injector: Arc<dyn HeaderInjector>) -> Self {
489        self.header_injector = Some(header_injector);
490        self
491    }
492
493    /// Installs the audit sink receiving request and stream events.
494    pub fn audit_sink(mut self, audit_sink: Arc<dyn AuditSink>) -> Self {
495        self.audit_sink = Some(audit_sink);
496        self
497    }
498
499    /// Replaces the transport-level audit switches.
500    pub fn audit_config(mut self, audit_config: AuditConfig) -> Self {
501        self.audit_config = audit_config;
502        self
503    }
504
505    pub(crate) fn audit_context(
506        &self,
507        provider: &'static str,
508        protocol: &'static str,
509        model: &str,
510        options: &RequestOptions,
511        profile: Option<ProfileAuditSnapshot>,
512        request_body_bytes: u64,
513    ) -> Option<AuditContext> {
514        let config = options.audit_config.unwrap_or(self.audit_config);
515        if !config.enabled {
516            return None;
517        }
518        let sample = self.audit_sample_counter.fetch_add(1, Ordering::Relaxed) + 1;
519        if config.sample_every > 1 && !sample.is_multiple_of(config.sample_every) {
520            return None;
521        }
522        self.audit_sink.clone().map(|sink| {
523            AuditContext::new(
524                sink,
525                config,
526                options,
527                AuditRequestMeta {
528                    provider,
529                    protocol,
530                    model,
531                    profile,
532                    request_body_bytes,
533                },
534            )
535        })
536    }
537
538    /// Apply static header layers.
539    ///
540    /// This does not call [`Self::header_injector`]. Built-in adapters use
541    /// [`Self::apply_to_async`] so dynamic headers are included.
542    pub fn apply_to(&self, headers: &mut HeaderMap, options: &RequestOptions) -> Result<()> {
543        headers
544            .entry(USER_AGENT)
545            .or_insert_with(|| self.user_agent.clone());
546
547        if let Some(client_info) = &self.client_info {
548            headers.insert(
549                HeaderName::from_static("x-client-name"),
550                HeaderValue::from_str(&sanitize_product_token(&client_info.name))?,
551            );
552            headers.insert(
553                HeaderName::from_static("x-client-version"),
554                HeaderValue::from_str(&sanitize_product_token(&client_info.version))?,
555            );
556            if let Some(instance_id) = &client_info.instance_id {
557                let value = HeaderValue::from_str(instance_id)?;
558                ensure_ascii_header_value("x-client-instance-id", value.as_bytes())?;
559                headers.insert(HeaderName::from_static("x-client-instance-id"), value);
560            }
561        }
562
563        apply_headers(headers, &self.default_headers, &self.header_policy)?;
564
565        if let Some(user_agent) = &options.user_agent {
566            headers.insert(USER_AGENT, user_agent.clone());
567        }
568        apply_headers(headers, &options.headers, &self.header_policy)?;
569
570        if let Some(idempotency_key) = &options.idempotency_key {
571            if idempotency_key.trim().is_empty() {
572                return Err(Error::InvalidRequest(
573                    "idempotency key must not be empty".into(),
574                ));
575            }
576            let value = HeaderValue::from_str(idempotency_key)?;
577            ensure_ascii_header_value(IDEMPOTENCY_KEY, value.as_bytes())?;
578            headers.insert(HeaderName::from_static(IDEMPOTENCY_KEY), value);
579        }
580
581        Ok(())
582    }
583
584    /// Apply static headers, then trusted dynamic headers.
585    ///
586    /// Dynamic headers are allowed to set protected headers such as
587    /// `Authorization`; the injector is part of the trusted transport
588    /// configuration.
589    pub async fn apply_to_async(
590        &self,
591        headers: &mut HeaderMap,
592        options: &RequestOptions,
593    ) -> Result<()> {
594        self.apply_to(headers, options)?;
595        let idempotency_key = headers
596            .get(HeaderName::from_static(IDEMPOTENCY_KEY))
597            .cloned();
598        if let Some(injector) = &self.header_injector {
599            let injected = injector.inject(&options.context).await?;
600            apply_trusted_headers(headers, &injected);
601        }
602        if let Some(idempotency_key) = idempotency_key {
603            headers.insert(HeaderName::from_static(IDEMPOTENCY_KEY), idempotency_key);
604        }
605        Ok(())
606    }
607}
608
609/// Dynamic header provider for authentication refresh and request-specific
610/// routing.
611#[async_trait]
612pub trait HeaderInjector: Send + Sync {
613    /// Returns the headers to inject for this request.
614    ///
615    /// Injected headers are trusted: they may set protected headers such as
616    /// `Authorization`.
617    ///
618    /// # Errors
619    ///
620    /// Returns an error if dynamic header computation fails (for example a
621    /// token refresh could not be completed).
622    async fn inject(&self, context: &RequestContext) -> Result<HeaderMap>;
623}
624
625/// Merges one header layer into `target`, enforcing the [`HeaderPolicy`].
626///
627/// # Errors
628///
629/// Returns [`Error::ProtectedHeader`] if the layer tries to set a protected
630/// header that is not allowed to be overridden.
631pub fn apply_headers(
632    target: &mut HeaderMap,
633    layer: &HeaderMap,
634    policy: &HeaderPolicy,
635) -> Result<()> {
636    for (name, value) in layer {
637        if policy.is_protected(name) && !policy.can_override(name) {
638            return Err(Error::ProtectedHeader(name.to_string()));
639        }
640        target.insert(name.clone(), value.clone());
641    }
642    Ok(())
643}
644
645fn apply_trusted_headers(target: &mut HeaderMap, layer: &HeaderMap) {
646    for (name, value) in layer {
647        target.insert(name.clone(), value.clone());
648    }
649}
650
651fn ensure_ascii_header_value(name: &str, value: &[u8]) -> Result<()> {
652    if value.is_ascii() {
653        Ok(())
654    } else {
655        Err(Error::NonAsciiHeaderValue {
656            name: name.to_string(),
657        })
658    }
659}
660
661fn sanitize_product_token(value: &str) -> String {
662    value
663        .chars()
664        .filter(|character| {
665            character.is_ascii_alphanumeric() || matches!(character, '.' | '-' | '_' | '+' | '~')
666        })
667        .collect()
668}