Skip to main content

acosmi/core/
transport.rs

1//! HTTP injection without SDK-owned connections or redirect handling.
2use crate::shared::errors::{Error, NetworkError, Result};
3use async_trait::async_trait;
4use bytes::Bytes;
5use futures::{Stream, StreamExt};
6use http::{header::HeaderMap, Method, StatusCode};
7use serde::{de::DeserializeOwned, Serialize};
8use std::{fmt, pin::Pin, sync::Arc, time::Duration};
9use tokio_util::sync::CancellationToken;
10use url::Url;
11
12/// Diagnostic metadata, never an authorization grant.
13#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14pub enum HttpPurpose {
15    Api,
16    Model,
17    OAuthDiscovery,
18    OAuthRegistration,
19    OAuthToken,
20    OAuthRevocation,
21    Transfer,
22}
23
24#[derive(Debug, Clone, Copy, PartialEq, Eq)]
25pub enum HttpResponseMode {
26    Buffered,
27    Streaming,
28}
29
30/// Buffered timeout covers headers and body; streaming timeout covers headers
31/// only. Streaming body lifetime is controlled by cancellation, never this timer.
32#[derive(Debug, Clone, Copy)]
33pub struct HttpContext {
34    pub purpose: HttpPurpose,
35    pub response_mode: HttpResponseMode,
36    pub timeout: Duration,
37}
38impl HttpContext {
39    pub fn buffered(purpose: HttpPurpose, timeout_ms: u64) -> Self {
40        Self {
41            purpose,
42            response_mode: HttpResponseMode::Buffered,
43            timeout: Duration::from_millis(timeout_ms),
44        }
45    }
46    pub fn streaming(purpose: HttpPurpose, headers_timeout_ms: u64) -> Self {
47        Self {
48            purpose,
49            response_mode: HttpResponseMode::Streaming,
50            timeout: Duration::from_millis(headers_timeout_ms),
51        }
52    }
53}
54impl Default for HttpContext {
55    fn default() -> Self {
56        Self::buffered(HttpPurpose::Api, super::http::DEFAULT_JSON_TIMEOUT_MS)
57    }
58}
59
60/// Owned request, including potentially sensitive headers and JSON/form body.
61/// The transport owns redirect authorization at every hop, credential stripping,
62/// DNS/TLS/connection policy and any stricter budgets. It MUST NOT silently retry
63/// non-idempotent requests. A returned redirect is not followed by the SDK.
64/// Body bytes owned by this value are zeroized on drop. Taking ownership of the
65/// bytes transfers that responsibility to the transport. HeaderMap allocations
66/// and copies made by HTTP libraries cannot be guaranteed zeroized.
67pub struct HttpRequest {
68    pub method: Method,
69    pub url: Url,
70    pub headers: HeaderMap,
71    pub body: Vec<u8>,
72    pub context: HttpContext,
73}
74impl Drop for HttpRequest {
75    fn drop(&mut self) {
76        zeroize::Zeroize::zeroize(&mut self.body);
77    }
78}
79impl fmt::Debug for HttpRequest {
80    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
81        f.debug_struct("HttpRequest")
82            .field("context", &self.context)
83            .finish_non_exhaustive()
84    }
85}
86
87/// Closed, payload-free transport failures. Do not put backend error strings,
88/// request URLs, response bytes, credentials or panic payloads into errors.
89#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
90pub enum TransportError {
91    #[error("http_transport_cancelled")]
92    Cancelled,
93    #[error("http_transport_timeout")]
94    Timeout,
95    #[error("http_transport_connection_failed")]
96    Connection,
97    #[error("http_transport_rejected")]
98    Rejected,
99    #[error("http_transport_invalid_request")]
100    InvalidRequest,
101    #[error("http_transport_body_failed")]
102    Body,
103    #[error("http_transport_unsupported_body")]
104    UnsupportedBody,
105    #[error("http_transport_unsupported_websocket")]
106    UnsupportedWebSocket,
107}
108impl From<TransportError> for Error {
109    fn from(value: TransportError) -> Self {
110        let mut error = NetworkError::new("HTTP transport", "", value.to_string());
111        error.timeout = value == TransportError::Timeout;
112        error.eof = value == TransportError::Connection;
113        Error::Network(error)
114    }
115}
116pub type HttpBody = Pin<Box<dyn Stream<Item = std::result::Result<Bytes, TransportError>> + Send>>;
117
118/// Headers arrive before any body polling. Dropping the body must release the
119/// transport's connection/driver; implementations must also honor cancellation.
120pub struct HttpResponse {
121    pub status: StatusCode,
122    pub headers: HeaderMap,
123    pub body: HttpBody,
124}
125impl fmt::Debug for HttpResponse {
126    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
127        f.debug_struct("HttpResponse")
128            .field("status", &self.status)
129            .finish_non_exhaustive()
130    }
131}
132
133#[async_trait]
134pub trait HttpTransport: Send + Sync {
135    async fn execute(
136        &self,
137        request: HttpRequest,
138        cancel: CancellationToken,
139    ) -> std::result::Result<HttpResponse, TransportError>;
140}
141
142/// HTTP handle for the `*_with_transport` OAuth free functions. Clones share the
143/// transport. This handle never falls back to direct networking in custom mode.
144#[derive(Clone)]
145enum Backend {
146    Custom(Arc<dyn HttpTransport>),
147    #[cfg(feature = "native-http")]
148    Native(reqwest::Client),
149}
150
151#[derive(Clone)]
152pub struct HttpClient {
153    backend: Backend,
154    signal: Option<CancellationToken>,
155}
156impl HttpClient {
157    pub fn new(transport: Arc<dyn HttpTransport>) -> Self {
158        Self {
159            backend: Backend::Custom(transport),
160            signal: None,
161        }
162    }
163    pub fn with_cancellation(&self, signal: Option<CancellationToken>) -> Self {
164        Self {
165            signal,
166            ..self.clone()
167        }
168    }
169    #[cfg(feature = "native-http")]
170    pub(crate) fn legacy(builder: reqwest::Client) -> Self {
171        Self {
172            backend: Backend::Native(builder),
173            signal: None,
174        }
175    }
176    #[cfg(feature = "notifications-ws")]
177    pub(crate) fn is_custom(&self) -> bool {
178        matches!(self.backend, Backend::Custom(_))
179    }
180    pub(crate) fn request(&self, method: Method, url: &str) -> HttpRequestBuilder {
181        let inner = match &self.backend {
182            Backend::Custom(_) => RequestKind::Custom(
183                Url::parse(url)
184                    .map(|url| HttpRequest {
185                        method,
186                        url,
187                        headers: HeaderMap::new(),
188                        body: Vec::new(),
189                        context: HttpContext::default(),
190                    })
191                    .map_err(|_| TransportError::InvalidRequest),
192            ),
193            #[cfg(feature = "native-http")]
194            Backend::Native(client) => RequestKind::Native(client.request(method, url)),
195        };
196        HttpRequestBuilder {
197            inner,
198            client: self.clone(),
199            context: HttpContext::default(),
200        }
201    }
202    pub(crate) fn get(&self, url: &str) -> HttpRequestBuilder {
203        self.request(Method::GET, url)
204    }
205    pub(crate) fn post(&self, url: &str) -> HttpRequestBuilder {
206        self.request(Method::POST, url)
207    }
208}
209enum RequestKind {
210    Custom(std::result::Result<HttpRequest, TransportError>),
211    #[cfg(feature = "native-http")]
212    Native(reqwest::RequestBuilder),
213}
214enum PreparedRequest {
215    Custom(HttpRequest),
216    #[cfg(feature = "native-http")]
217    Native(reqwest::Request),
218}
219pub(crate) struct HttpRequestBuilder {
220    inner: RequestKind,
221    client: HttpClient,
222    context: HttpContext,
223}
224impl HttpRequestBuilder {
225    pub(crate) fn context(mut self, context: HttpContext) -> Self {
226        self.context = context;
227        self
228    }
229    pub(crate) fn timeout(mut self, timeout: Duration) -> Self {
230        self.context.timeout = timeout;
231        self
232    }
233    pub(crate) fn purpose(mut self, purpose: HttpPurpose) -> Self {
234        self.context.purpose = purpose;
235        self
236    }
237    pub(crate) fn cancel(mut self, signal: Option<CancellationToken>) -> Self {
238        self.client.signal = signal;
239        self
240    }
241    pub(crate) fn header<K, V>(mut self, key: K, value: V) -> Self
242    where
243        http::header::HeaderName: TryFrom<K>,
244        <http::header::HeaderName as TryFrom<K>>::Error: Into<http::Error>,
245        http::header::HeaderValue: TryFrom<V>,
246        <http::header::HeaderValue as TryFrom<V>>::Error: Into<http::Error>,
247    {
248        self.inner = match self.inner {
249            RequestKind::Custom(request) => RequestKind::Custom(request.and_then(|mut r| {
250                let key = http::header::HeaderName::try_from(key)
251                    .map_err(|_| TransportError::InvalidRequest)?;
252                let mut value = http::header::HeaderValue::try_from(value)
253                    .map_err(|_| TransportError::InvalidRequest)?;
254                value.set_sensitive(true);
255                r.headers.append(key, value);
256                Ok(r)
257            })),
258            #[cfg(feature = "native-http")]
259            RequestKind::Native(r) => RequestKind::Native(r.header(key, value)),
260        };
261        self
262    }
263    pub(crate) fn body(mut self, body: String) -> Self {
264        self.inner = match self.inner {
265            RequestKind::Custom(r) => RequestKind::Custom(r.map(|mut r| {
266                r.body = body.into_bytes();
267                r
268            })),
269            #[cfg(feature = "native-http")]
270            RequestKind::Native(r) => RequestKind::Native(r.body(body)),
271        };
272        self
273    }
274    pub(crate) fn json<T: Serialize + ?Sized>(mut self, body: &T) -> Self {
275        self.inner = match self.inner {
276            RequestKind::Custom(r) => RequestKind::Custom(r.and_then(|mut r| {
277                r.body = serde_json::to_vec(body).map_err(|_| TransportError::InvalidRequest)?;
278                r.headers
279                    .entry(http::header::CONTENT_TYPE)
280                    .or_insert(http::header::HeaderValue::from_static("application/json"));
281                Ok(r)
282            })),
283            #[cfg(feature = "native-http")]
284            RequestKind::Native(r) => RequestKind::Native(r.json(body)),
285        };
286        self
287    }
288    pub(crate) fn form<T: Serialize + ?Sized>(mut self, body: &T) -> Self {
289        self.inner = match self.inner {
290            RequestKind::Custom(r) => RequestKind::Custom(r.and_then(|mut r| {
291                r.body = serde_urlencoded::to_string(body)
292                    .map_err(|_| TransportError::InvalidRequest)?
293                    .into_bytes();
294                r.headers.entry(http::header::CONTENT_TYPE).or_insert(
295                    http::header::HeaderValue::from_static("application/x-www-form-urlencoded"),
296                );
297                Ok(r)
298            })),
299            #[cfg(feature = "native-http")]
300            RequestKind::Native(r) => RequestKind::Native(r.form(body)),
301        };
302        self
303    }
304    #[cfg(feature = "native-http")]
305    pub(crate) fn multipart(mut self, body: reqwest::multipart::Form) -> Self {
306        self.inner = match self.inner {
307            RequestKind::Custom(_) => RequestKind::Custom(Err(TransportError::UnsupportedBody)),
308            RequestKind::Native(r) => RequestKind::Native(r.multipart(body)),
309        };
310        self
311    }
312
313    pub(crate) async fn send(self) -> Result<Response> {
314        let cancel = self
315            .client
316            .signal
317            .as_ref()
318            .map(CancellationToken::child_token)
319            .unwrap_or_default();
320        let guard = cancel.clone().drop_guard();
321        let deadline = tokio::time::Instant::now() + self.context.timeout;
322        let request = match self.inner {
323            RequestKind::Custom(request) => {
324                let mut request = request?;
325                request.context = self.context;
326                PreparedRequest::Custom(request)
327            }
328            #[cfg(feature = "native-http")]
329            RequestKind::Native(request) => {
330                let mut request = request
331                    .build()
332                    .map_err(|_| TransportError::InvalidRequest)?;
333                for value in request.headers_mut().values_mut() {
334                    value.set_sensitive(true);
335                }
336                PreparedRequest::Native(request)
337            }
338        };
339        let send = async {
340            match (&self.client.backend, request) {
341                (Backend::Custom(custom), PreparedRequest::Custom(request)) => {
342                    let response = custom
343                        .execute(request, cancel.clone())
344                        .await
345                        .map_err(Error::from)?;
346                    Ok::<_, Error>((
347                        response.status,
348                        response.headers,
349                        Box::pin(response.body.map(|v| v.map_err(Error::from))) as ResponseBody,
350                    ))
351                }
352                #[cfg(feature = "native-http")]
353                (Backend::Native(client), PreparedRequest::Native(request)) => {
354                    let response = client.execute(request).await.map_err(|e| {
355                        if e.is_timeout() {
356                            TransportError::Timeout
357                        } else if e.is_connect() {
358                            TransportError::Connection
359                        } else {
360                            TransportError::Rejected
361                        }
362                    })?;
363                    let status = response.status();
364                    let headers = response.headers().clone();
365                    let body = response.bytes_stream().map(|v| {
366                        v.map_err(|e| {
367                            if e.is_timeout() {
368                                TransportError::Timeout.into()
369                            } else {
370                                TransportError::Body.into()
371                            }
372                        })
373                    });
374                    Ok((status, headers, Box::pin(body) as ResponseBody))
375                }
376                #[cfg(feature = "native-http")]
377                _ => Err(TransportError::InvalidRequest.into()),
378            }
379        };
380        let (status, headers, mut body) = tokio::select! {
381            biased;
382            _ = cancel.cancelled() => return Err(TransportError::Cancelled.into()),
383            result = tokio::time::timeout_at(deadline, send) => result.map_err(|_| TransportError::Timeout)??,
384        };
385        let mode = self.context.response_mode;
386        let body = Box::pin(async_stream::try_stream! {
387            let _guard = guard;
388            loop {
389                let next = tokio::select! {
390                    biased;
391                    _ = cancel.cancelled() => Err(Error::from(TransportError::Cancelled)),
392                    _ = tokio::time::sleep_until(deadline), if mode == HttpResponseMode::Buffered => Err(Error::from(TransportError::Timeout)),
393                    item = body.next() => Ok(item),
394                }?;
395                match next { Some(item) => yield item?, None => break }
396            }
397        });
398        Ok(Response {
399            status,
400            headers,
401            body,
402        })
403    }
404}
405
406type ResponseBody = Pin<Box<dyn Stream<Item = Result<Bytes>> + Send>>;
407pub(crate) struct Response {
408    status: StatusCode,
409    headers: HeaderMap,
410    body: ResponseBody,
411}
412impl Response {
413    pub(crate) fn status(&self) -> StatusCode {
414        self.status
415    }
416    pub(crate) fn headers(&self) -> &HeaderMap {
417        &self.headers
418    }
419    pub(crate) fn bytes_stream(self) -> ResponseBody {
420        self.body
421    }
422    pub(crate) async fn bytes(self) -> Result<Bytes> {
423        let mut body = self.body;
424        let mut output = Vec::new();
425        while let Some(chunk) = body.next().await {
426            output.extend_from_slice(&chunk?);
427        }
428        Ok(Bytes::from(output))
429    }
430    pub(crate) async fn text(self) -> Result<String> {
431        Ok(String::from_utf8_lossy(&self.bytes().await?).into_owned())
432    }
433    pub(crate) async fn json<T: DeserializeOwned>(self) -> Result<T> {
434        Ok(serde_json::from_slice(&self.bytes().await?)?)
435    }
436}
437
438/// Poll cancellation before the operation, including synchronous ready results.
439pub(crate) async fn with_cancel<T>(
440    signal: Option<&CancellationToken>,
441    future: impl std::future::Future<Output = T>,
442) -> Result<T> {
443    match signal {
444        Some(cancel) => tokio::select! {
445            biased;
446            _ = cancel.cancelled() => Err(TransportError::Cancelled.into()),
447            result = future => Ok(result),
448        },
449        None => Ok(future.await),
450    }
451}
452
453#[cfg(test)]
454mod tests {
455    use super::*;
456    use std::sync::Mutex;
457    struct PendingTransport {
458        headers_pending: bool,
459        cancel: Mutex<Option<CancellationToken>>,
460    }
461    #[async_trait]
462    impl HttpTransport for PendingTransport {
463        async fn execute(
464            &self,
465            _request: HttpRequest,
466            cancel: CancellationToken,
467        ) -> std::result::Result<HttpResponse, TransportError> {
468            *self.cancel.lock().unwrap() = Some(cancel);
469            if self.headers_pending {
470                return futures::future::pending().await;
471            }
472            Ok(HttpResponse {
473                status: StatusCode::OK,
474                headers: HeaderMap::new(),
475                body: Box::pin(futures::stream::pending()),
476            })
477        }
478    }
479    fn pending(headers_pending: bool) -> Arc<PendingTransport> {
480        Arc::new(PendingTransport {
481            headers_pending,
482            cancel: Mutex::new(None),
483        })
484    }
485    #[tokio::test]
486    async fn cancellation_and_timeout_cover_header_wait_without_fallback() {
487        for timeout in [true, false] {
488            let transport = pending(true);
489            let cancel = CancellationToken::new();
490            let http = HttpClient::new(transport.clone()).with_cancellation(Some(cancel.clone()));
491            let request = http
492                .get("https://invalid.invalid/")
493                .timeout(Duration::from_millis(20));
494            let send = request.send();
495            tokio::pin!(send);
496            assert!(tokio::time::timeout(Duration::from_millis(5), &mut send)
497                .await
498                .is_err());
499            if !timeout {
500                cancel.cancel();
501            }
502            assert!(tokio::time::timeout(Duration::from_millis(100), send)
503                .await
504                .unwrap()
505                .is_err());
506            assert!(transport
507                .cancel
508                .lock()
509                .unwrap()
510                .as_ref()
511                .unwrap()
512                .is_cancelled());
513        }
514    }
515    #[tokio::test]
516    async fn buffered_budget_covers_body_streaming_budget_only_headers() {
517        for mode in [HttpResponseMode::Buffered, HttpResponseMode::Streaming] {
518            let transport = pending(false);
519            let cancel = CancellationToken::new();
520            let http = HttpClient::new(transport.clone()).with_cancellation(Some(cancel.clone()));
521            let response = http
522                .get("https://invalid.invalid/")
523                .context(HttpContext {
524                    purpose: HttpPurpose::Model,
525                    response_mode: mode,
526                    timeout: Duration::from_millis(10),
527                })
528                .send()
529                .await
530                .unwrap();
531            let bytes = response.bytes();
532            tokio::pin!(bytes);
533            if mode == HttpResponseMode::Buffered {
534                assert!(tokio::time::timeout(Duration::from_millis(100), bytes)
535                    .await
536                    .unwrap()
537                    .is_err());
538            } else {
539                assert!(tokio::time::timeout(Duration::from_millis(30), &mut bytes)
540                    .await
541                    .is_err());
542                cancel.cancel();
543                assert!(bytes.await.is_err());
544            }
545            assert!(transport
546                .cancel
547                .lock()
548                .unwrap()
549                .as_ref()
550                .unwrap()
551                .is_cancelled());
552        }
553    }
554    #[tokio::test]
555    async fn dropping_unpolled_response_cancels_transport() {
556        let transport = pending(false);
557        let response = HttpClient::new(transport.clone())
558            .get("https://invalid.invalid/")
559            .send()
560            .await
561            .unwrap();
562        drop(response);
563        assert!(transport
564            .cancel
565            .lock()
566            .unwrap()
567            .as_ref()
568            .unwrap()
569            .is_cancelled());
570    }
571}