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
21pub const SDK_USER_AGENT: &str = concat!("mutil-ai/", env!("CARGO_PKG_VERSION"));
23
24const IDEMPOTENCY_KEY: &str = "idempotency-key";
25
26#[derive(Debug, Clone, PartialEq, Eq)]
28pub struct ClientInfo {
29 pub name: String,
31 pub version: String,
33 pub instance_id: Option<String>,
35}
36
37impl ClientInfo {
38 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 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 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#[derive(Debug, Clone, Default, PartialEq, Eq)]
74pub struct RequestContext {
75 pub request_id: Option<String>,
77 pub session_id: Option<String>,
80 pub conversation_id: Option<String>,
82 pub tenant_id: Option<String>,
84 pub trace_id: Option<String>,
86 pub attributes: BTreeMap<String, String>,
88}
89
90impl RequestContext {
91 pub fn new() -> Self {
93 Self::default()
94 }
95
96 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 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 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 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 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#[derive(Clone, Default)]
129pub struct RequestOptions {
130 pub headers: HeaderMap,
132 pub user_agent: Option<HeaderValue>,
134 pub context: RequestContext,
136 pub idempotency_key: Option<String>,
139 pub timeout: Option<Duration>,
141 pub idle_timeout: Option<Duration>,
143 pub extra_query: Vec<(String, String)>,
148 pub stream_reconnect: Option<StreamReconnectPolicy>,
150 pub cancellation: Option<CancellationToken>,
152 pub request_transform: Option<Arc<dyn RequestTransform>>,
155 pub provider_request: ProviderRequestOptions,
157 pub audit_config: Option<AuditConfig>,
159 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 pub fn new() -> Self {
200 Self::default()
201 }
202
203 pub fn response_limits(mut self, limits: ResponseLimits) -> Self {
205 self.response_limits = limits;
206 self
207 }
208
209 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 pub fn extra_headers(mut self, headers: HeaderMap) -> Self {
230 self.headers.extend(headers);
231 self
232 }
233
234 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 pub fn stream_reconnect(mut self, policy: StreamReconnectPolicy) -> Self {
242 self.stream_reconnect = Some(policy);
243 self
244 }
245
246 pub fn cancellation(mut self, token: CancellationToken) -> Self {
249 self.cancellation = Some(token);
250 self
251 }
252
253 pub fn cancellation_token(self, token: CancellationToken) -> Self {
255 self.cancellation(token)
256 }
257
258 pub fn request_transform(mut self, transform: impl RequestTransform + 'static) -> Self {
261 self.request_transform = Some(Arc::new(transform));
262 self
263 }
264
265 pub fn provider_request(mut self, provider_request: ProviderRequestOptions) -> Self {
267 self.provider_request = provider_request;
268 self
269 }
270
271 pub fn audit_config(mut self, audit_config: AuditConfig) -> Self {
273 self.audit_config = Some(audit_config);
274 self
275 }
276
277 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 pub fn context(mut self, context: RequestContext) -> Self {
292 self.context = context;
293 self
294 }
295
296 pub fn idempotency_key(mut self, key: impl Into<String>) -> Self {
298 self.idempotency_key = Some(key.into());
299 self
300 }
301
302 pub fn timeout(mut self, timeout: Duration) -> Self {
304 self.timeout = Some(timeout);
305 self
306 }
307
308 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#[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 pub fn new() -> Self {
354 Self::default()
355 }
356
357 pub fn protect(mut self, name: HeaderName) -> Self {
360 self.protected.push(name);
361 self
362 }
363
364 pub fn allow_override(mut self, name: HeaderName) -> Self {
366 self.allow_override.push(name);
367 self
368 }
369
370 pub fn is_protected(&self, name: &HeaderName) -> bool {
372 self.protected.iter().any(|protected| protected == name)
373 }
374
375 pub fn can_override(&self, name: &HeaderName) -> bool {
377 self.allow_override.iter().any(|allowed| allowed == name)
378 }
379}
380
381#[derive(Clone)]
383pub struct TransportConfig {
384 pub user_agent: HeaderValue,
386 pub default_headers: HeaderMap,
388 pub client_info: Option<ClientInfo>,
390 pub header_policy: HeaderPolicy,
392 pub header_injector: Option<Arc<dyn HeaderInjector>>,
395 pub audit_sink: Option<Arc<dyn AuditSink>>,
397 pub audit_config: AuditConfig,
399 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 pub fn new() -> Self {
445 Self::default()
446 }
447
448 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 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 pub fn client_info(mut self, client_info: ClientInfo) -> Self {
477 self.client_info = Some(client_info);
478 self
479 }
480
481 pub fn header_policy(mut self, header_policy: HeaderPolicy) -> Self {
483 self.header_policy = header_policy;
484 self
485 }
486
487 pub fn header_injector(mut self, header_injector: Arc<dyn HeaderInjector>) -> Self {
489 self.header_injector = Some(header_injector);
490 self
491 }
492
493 pub fn audit_sink(mut self, audit_sink: Arc<dyn AuditSink>) -> Self {
495 self.audit_sink = Some(audit_sink);
496 self
497 }
498
499 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 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 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#[async_trait]
612pub trait HeaderInjector: Send + Sync {
613 async fn inject(&self, context: &RequestContext) -> Result<HeaderMap>;
623}
624
625pub 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}