Skip to main content

rig_reqwest/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![cfg_attr(
3    test,
4    allow(
5        clippy::expect_used,
6        clippy::indexing_slicing,
7        clippy::panic,
8        clippy::unwrap_used,
9        clippy::unreachable
10    )
11)]
12//! The bundled reqwest HTTP transport for Rig.
13//!
14//! [`ReqwestClient::default()`] is the process-wide client: built once on
15//! first use and shared by every clone, so every provider client made with
16//! it shares one connection pool. Construction never fails. On a host with
17//! no CA certificates, the `rustls` build trusts the bundled Mozilla roots
18//! instead. When reqwest still cannot build its client, every send reports
19//! that build failure in-band.
20//!
21//! Native requests and bodies enter the captured Tokio context on each poll
22//! ([`rig_http::runtime`]), using a lazy fallback when no runtime is current. Callers retain ownership;
23//! dropping an operation cancels local work, not accepted remote work. Hosts
24//! must keep their runtime driven with I/O and timers enabled until operations
25//! finish. Missing drivers can panic; a stopped runtime causes I/O failure.
26//!
27//! ```no_run
28//! use rig_reqwest::ReqwestClient;
29//!
30//! let shared = ReqwestClient::default();
31//! let custom = ReqwestClient::from(rig_reqwest::reqwest::Client::new());
32//! # let _ = (shared, custom);
33//! ```
34
35pub use reqwest;
36
37/// A reqwest client implementing [`HttpClientExt`].
38///
39/// [`Default`] is the process-wide client, built once and shared by every
40/// clone; `From<reqwest::Client>` wraps a configured client and keeps its
41/// connection pool. Non-success responses retain at most 64 KiB of body bytes,
42/// with a truncation marker only after observing excess data. Partial diagnostic
43/// text survives body read failures; the client's timeout policy governs reads.
44///
45/// On native targets, [`Default`]'s client follows a redirect to another origin
46/// (scheme, host or port) with only harmless headers, so no credential reaches
47/// it. A browser follows redirects itself, so wasm lacks this protection, as do
48/// a client from `From<reqwest::Client>` and a `ReqwestMiddlewareClient`, which
49/// keep their own policy.
50#[derive(Clone, Debug)]
51pub struct ReqwestClient(Built);
52
53/// The process-wide client, erased behind [`DynHttpClient`].
54pub fn shared() -> DynHttpClient {
55    DynHttpClient::new(ReqwestClient::default())
56}
57
58/// What building the client produced: the client, or why reqwest refused.
59#[derive(Clone, Debug)]
60enum Built {
61    /// The process-wide client: on native targets, [`follow_redirects`]
62    /// follows its redirects.
63    Shared(Arc<reqwest::Client>),
64    /// A caller's client, which keeps its own redirect policy.
65    Client(Arc<reqwest::Client>),
66    /// The shared client could not be built: every send reports this, so
67    /// the failure surfaces where the first request is made rather than
68    /// where the client was named.
69    Failed(Arc<reqwest::Error>),
70}
71
72impl Default for ReqwestClient {
73    /// The process-wide client, built on first use. It never panics: a
74    /// client reqwest cannot build reports the build error on every send.
75    fn default() -> Self {
76        fn build() -> ReqwestClient {
77            ReqwestClient(match build_shared(shared_builder) {
78                Ok(client) => Built::Shared(Arc::new(client)),
79                Err(error) => Built::Failed(Arc::new(error)),
80            })
81        }
82        #[cfg(not(target_family = "wasm"))]
83        {
84            static SHARED: std::sync::LazyLock<ReqwestClient> = std::sync::LazyLock::new(build);
85            SHARED.clone()
86        }
87        #[cfg(target_family = "wasm")]
88        {
89            thread_local! {
90                static SHARED: ReqwestClient = build();
91            }
92            SHARED.with(Clone::clone)
93        }
94    }
95}
96
97impl ReqwestClient {
98    /// The reqwest client, or `None` for the shared client when reqwest
99    /// could not build it. On native targets, the shared client's is a second
100    /// one: its redirects are reqwest's own, so it lacks this type's protection
101    /// and does not share the pool.
102    pub fn inner(&self) -> Option<&reqwest::Client> {
103        match &self.0 {
104            #[cfg(not(target_family = "wasm"))]
105            Built::Shared(_) => {
106                static FOLLOWING: std::sync::LazyLock<Option<reqwest::Client>> =
107                    std::sync::LazyLock::new(|| build_shared(reqwest::Client::builder).ok());
108                FOLLOWING.as_ref()
109            }
110            #[cfg(target_family = "wasm")]
111            Built::Shared(client) => Some(client),
112            Built::Client(client) => Some(client),
113            Built::Failed(_) => None,
114        }
115    }
116
117    /// Whether `self` and `other` are clones of one client.
118    #[cfg(test)]
119    fn same(&self, other: &Self) -> bool {
120        match (&self.0, &other.0) {
121            (Built::Shared(a), Built::Shared(b)) | (Built::Client(a), Built::Client(b)) => {
122                Arc::ptr_eq(a, b)
123            }
124            (Built::Failed(a), Built::Failed(b)) => Arc::ptr_eq(a, b),
125            _ => false,
126        }
127    }
128}
129
130/// The builder of the shared client. On native targets reqwest follows no
131/// redirect, so that [`follow_redirects`] decides what each one carries.
132fn shared_builder() -> reqwest::ClientBuilder {
133    let builder = reqwest::Client::builder();
134    #[cfg(not(target_family = "wasm"))]
135    let builder = builder.redirect(reqwest::redirect::Policy::none());
136    builder
137}
138
139/// A client from `builder`, falling back to the bundled roots when the system's
140/// cannot be loaded.
141fn build_shared(builder: fn() -> reqwest::ClientBuilder) -> reqwest::Result<reqwest::Client> {
142    let built = builder().build();
143    #[cfg(all(feature = "rustls", not(target_family = "wasm")))]
144    let built = built.or_else(|error| with_bundled_roots(builder(), error));
145    built
146}
147
148/// `builder` trusting only the bundled Mozilla roots, after the
149/// default build failed with `error`. That build differs only in reading
150/// the system's root store, which a host without CA certificates lacks.
151/// Returns `error` when this build fails too.
152#[cfg(all(feature = "rustls", not(target_family = "wasm")))]
153fn with_bundled_roots(
154    builder: reqwest::ClientBuilder,
155    error: reqwest::Error,
156) -> reqwest::Result<reqwest::Client> {
157    let roots = webpki_root_certs::TLS_SERVER_ROOT_CERTS
158        .iter()
159        .filter_map(|der| reqwest::Certificate::from_der(der).ok());
160    let Ok(client) = builder.tls_certs_only(roots).build() else {
161        return Err(error);
162    };
163    tracing::warn!(
164        "the system's CA certificates could not be loaded ({}), so rig trusts its bundled \
165         Mozilla roots; install the system's CA certificates, or set SSL_CERT_FILE or \
166         SSL_CERT_DIR, to trust those instead",
167        Chain(&error)
168    );
169    Ok(client)
170}
171
172/// The error every send on an unbuilt client reports.
173fn unbuilt(error: &Arc<reqwest::Error>) -> Error {
174    Error::permanent(TransportBuildError(Arc::clone(error)))
175}
176
177impl From<reqwest::Client> for ReqwestClient {
178    fn from(client: reqwest::Client) -> Self {
179        Self(Built::Client(Arc::new(client)))
180    }
181}
182
183use bytes::Bytes;
184use rig_http::http_client::{
185    BoxedStream, DynHttpClient, Error, HttpClientExt, LazyBody, MultipartForm, Request, Response,
186    Result, StreamingResponse, multipart::PartContent, retryable_status,
187};
188use rig_http::wasm_compat::*;
189use std::sync::Arc;
190
191/// A transport build failure that displays the source chain and retains the
192/// original reqwest error as its source.
193#[derive(Debug)]
194struct TransportBuildError(Arc<reqwest::Error>);
195
196impl std::fmt::Display for TransportBuildError {
197    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
198        write!(
199            f,
200            "could not build the bundled reqwest transport: {}",
201            Chain(&*self.0)
202        )
203    }
204}
205
206/// An error followed by each of its sources, separated by `: `.
207struct Chain<'a>(&'a (dyn std::error::Error + 'static));
208
209impl std::fmt::Display for Chain<'_> {
210    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
211        write!(f, "{}", self.0)?;
212        std::iter::successors(self.0.source(), |cause| cause.source())
213            .try_for_each(|cause| write!(f, ": {cause}"))
214    }
215}
216
217impl std::error::Error for TransportBuildError {
218    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
219        Some(&*self.0)
220    }
221}
222
223/// Classify a reqwest error, retaining it as the source. A request reqwest
224/// could not build, a redirect it would not follow, and an error naming a
225/// status [`retryable_status`] does not retry (from `error_for_status`) are
226/// [`Error::Permanent`]; every other failure (connecting, a timeout, a body
227/// cut short, a retried status) is [`Error::Transient`].
228///
229/// A non-success reply this transport reads itself goes through
230/// [`non_success_body_error`] instead, which keeps its status, headers and
231/// body.
232pub fn from_reqwest(err: reqwest::Error) -> Error {
233    if is_transient(&err) {
234        Error::transient(err)
235    } else {
236        Error::permanent(err)
237    }
238}
239
240/// Whether sending again may pass a request that failed with `err`, as
241/// [`from_reqwest`] classifies it.
242fn is_transient(err: &reqwest::Error) -> bool {
243    match err.status() {
244        Some(status) => retryable_status(Some(status.as_u16())),
245        None => !(err.is_builder() || err.is_redirect()),
246    }
247}
248
249/// The most of a non-success reply's body its error keeps.
250const ERROR_BODY_LIMIT: usize = 64 * 1024;
251
252/// Read at most 64 KiB of a failed response, retaining status and headers.
253/// The client's timeout policy still governs body reads.
254async fn non_success_status_error(response: reqwest::Response) -> Error {
255    let status = response.status();
256    let headers = response.headers().clone();
257    non_success_body_error(status, headers, &mut Box::pin(response.bytes_stream())).await
258}
259
260/// The error a non-success reply becomes, read from its body's chunks: its
261/// status and headers, and at most the first 64 KiB of the body decoded as
262/// text by its charset, with a truncation marker when there was more. The
263/// body is read until one byte past the limit or its first error; the bytes
264/// read before an error are kept, and with none the error is the text. The
265/// rest of `body` is left unread for the caller. Every transport that gives
266/// providers rig-reqwest's errors builds them here, so the same reply gives
267/// the same error whichever reads it.
268pub async fn non_success_body_error<S, B, E>(
269    status: http::StatusCode,
270    headers: http::HeaderMap,
271    body: &mut S,
272) -> Error
273where
274    S: futures::Stream<Item = std::result::Result<B, E>> + Unpin,
275    B: AsRef<[u8]>,
276    E: std::fmt::Display,
277{
278    use futures::StreamExt;
279
280    let mut bytes = Vec::new();
281    let mut failure = None;
282    while let Some(chunk) = body.next().await {
283        match chunk {
284            Ok(chunk) => {
285                // One byte past the limit is enough to know the body was cut.
286                let remaining = ERROR_BODY_LIMIT + 1 - bytes.len();
287                bytes.extend(chunk.as_ref().iter().take(remaining));
288                if bytes.len() > ERROR_BODY_LIMIT {
289                    break;
290                }
291            }
292            Err(error) => {
293                failure = Some(error.to_string());
294                break;
295            }
296        }
297    }
298    let kept = bytes.get(..ERROR_BODY_LIMIT).unwrap_or(&bytes);
299    let mut text = if kept.is_empty() {
300        failure
301            .map(|failure| format!("failed to read error response body: {failure}"))
302            .unwrap_or_default()
303    } else {
304        decode_error_body(kept.to_vec(), &headers).await
305    };
306    if bytes.len() > ERROR_BODY_LIMIT {
307        text.push_str("\n[Response body truncated after 64 KiB]");
308    }
309    Error::non_success_with_details(status, headers, text)
310}
311
312/// Keep reqwest's charset decoding for the bounded, in-memory body.
313#[cfg(not(target_family = "wasm"))]
314async fn decode_error_body(bytes: Vec<u8>, headers: &http::HeaderMap) -> String {
315    let mut response = http::Response::new(bytes);
316    *response.headers_mut() = headers.clone();
317    reqwest::Response::from(response)
318        .text()
319        .await
320        .unwrap_or_else(|error| format!("failed to read error response body: {error}"))
321}
322
323#[cfg(target_family = "wasm")]
324async fn decode_error_body(bytes: Vec<u8>, _headers: &http::HeaderMap) -> String {
325    let bytes = bytes.strip_prefix(&[0xef, 0xbb, 0xbf]).unwrap_or(&bytes);
326    String::from_utf8_lossy(bytes).into_owned()
327}
328
329/// Keep successful bodies lazy and owned by the response on every executor.
330async fn into_response(mut response: reqwest::Response) -> Result<Response<LazyBody>> {
331    if !response.status().is_success() {
332        return Err(non_success_status_error(response).await);
333    }
334
335    let res = response_head(&mut response);
336    let body = async { response.bytes().await.map_err(from_reqwest) };
337    #[cfg(not(target_family = "wasm"))]
338    let body = rig_http::runtime::bind(body)?;
339    let body: LazyBody = Box::pin(body);
340    res.body(body).map_err(Error::Protocol)
341}
342
343/// The status, headers (moved out) and, on native, HTTP version of `response`.
344fn response_head(response: &mut reqwest::Response) -> http::response::Builder {
345    #[cfg(not(target_family = "wasm"))]
346    let mut res = Response::builder()
347        .status(response.status())
348        .version(response.version());
349
350    #[cfg(target_family = "wasm")]
351    let mut res = Response::builder().status(response.status());
352
353    if let Some(hs) = res.headers_mut() {
354        *hs = std::mem::take(response.headers_mut());
355    }
356    res
357}
358
359/// Convert an already-sent streaming response into the transport-agnostic
360/// [`StreamingResponse`], rejecting non-success statuses with the
361/// headers-preserving error. The body retains the request's reactor context.
362async fn into_streaming_response(mut response: reqwest::Response) -> Result<StreamingResponse> {
363    if !response.status().is_success() {
364        return Err(non_success_status_error(response).await);
365    }
366    let res = response_head(&mut response);
367
368    use futures::StreamExt;
369    let stream = response
370        .bytes_stream()
371        .map(|chunk| chunk.map_err(from_reqwest));
372    #[cfg(not(target_family = "wasm"))]
373    let stream = rig_http::runtime::bind_stream(stream)?;
374    let stream: BoxedStream = Box::pin(stream);
375    res.body(stream).map_err(Error::Protocol)
376}
377
378/// A part's content type was not a MIME type reqwest would accept.
379#[derive(Debug, thiserror::Error)]
380#[error("multipart part {part:?} has an unusable content type {content_type:?}: {source}")]
381struct InvalidPartContentType {
382    part: String,
383    content_type: String,
384    source: reqwest::Error,
385}
386
387/// Render a [`MultipartForm`] as a `reqwest::multipart::Form`.
388///
389/// Returns an error when a binary part has a content type reqwest rejects.
390pub fn multipart_form(value: MultipartForm) -> Result<reqwest::multipart::Form> {
391    let mut form = reqwest::multipart::Form::new();
392
393    for part in value.into_parts() {
394        let (name, content, filename, content_type) = part.into_pieces();
395        match content {
396            PartContent::Text(text) => {
397                form = form.text(name, text);
398            }
399            PartContent::Binary(bytes) => {
400                // A `Bytes` body is the same reusable part `Part::bytes` makes, uncopied.
401                let mut req_part = reqwest::multipart::Part::stream(bytes);
402                if let Some(content_type) = content_type.as_ref() {
403                    req_part = req_part.mime_str(content_type.as_ref()).map_err(|source| {
404                        Error::permanent(InvalidPartContentType {
405                            part: name.clone(),
406                            content_type: content_type.as_ref().to_string(),
407                            source,
408                        })
409                    })?;
410                }
411
412                if let Some(filename) = filename {
413                    req_part = req_part.file_name(filename);
414                }
415
416                form = form.part(name, req_part);
417            }
418        }
419    }
420
421    Ok(form)
422}
423
424/// What a request carries: bytes, or a multipart form.
425enum Payload {
426    Bytes(Bytes),
427    Form(reqwest::multipart::Form),
428}
429
430/// A reqwest client, plain or with middleware.
431trait Execute: WasmCompatSend + WasmCompatSync {
432    /// The send of `parts` with `payload`, or why it cannot be sent.
433    fn execute(
434        &self,
435        parts: http::request::Parts,
436        payload: Result<Payload>,
437    ) -> Result<impl Future<Output = Result<reqwest::Response>> + WasmCompatSend + 'static>;
438}
439
440impl Execute for ReqwestClient {
441    fn execute(
442        &self,
443        parts: http::request::Parts,
444        payload: Result<Payload>,
445    ) -> Result<impl Future<Output = Result<reqwest::Response>> + WasmCompatSend + 'static> {
446        let client = match &self.0 {
447            Built::Shared(client) | Built::Client(client) => client,
448            Built::Failed(error) => return Err(unbuilt(error)),
449        };
450        #[cfg(not(target_family = "wasm"))]
451        let follow = matches!(self.0, Built::Shared(_)).then(|| match &payload {
452            Ok(Payload::Bytes(bytes)) => Some(bytes.clone()),
453            _ => None,
454        });
455        let request = client
456            .request(parts.method, parts.uri.to_string())
457            .headers(parts.headers);
458        let request = match payload? {
459            Payload::Bytes(bytes) => request.body(bytes),
460            Payload::Form(form) => request.multipart(form),
461        };
462        let request = request.build().map_err(from_reqwest)?;
463        let client = Arc::clone(client);
464        Ok(async move {
465            #[cfg(not(target_family = "wasm"))]
466            if let Some(body) = follow {
467                return follow_redirects(client, request, body).await;
468            }
469            client.execute(request).await.map_err(from_reqwest)
470        })
471    }
472}
473
474/// The most redirects one request follows, reqwest's own limit.
475#[cfg(not(target_family = "wasm"))]
476const MAX_REDIRECTS: usize = 10;
477
478/// Sends `request`, following its redirects by reqwest's rules, and returns the
479/// first response it cannot follow: no redirect, no usable `Location`, a body it
480/// cannot replay (`body` is `None` for a multipart form), or the limit reached.
481///
482/// Past a change of origin only allow-listed headers go on, for the rest of the
483/// chain, so a key header rig has never heard of stays behind.
484#[cfg(not(target_family = "wasm"))]
485async fn follow_redirects(
486    client: Arc<reqwest::Client>,
487    request: reqwest::Request,
488    mut body: Option<Bytes>,
489) -> Result<reqwest::Response> {
490    use http::header::{
491        ACCEPT, CONTENT_ENCODING, CONTENT_LENGTH, CONTENT_TYPE, LOCATION, RANGE, REFERER,
492        TRANSFER_ENCODING, USER_AGENT,
493    };
494    use http::{HeaderValue, Method, StatusCode};
495
496    let mut method = request.method().clone();
497    let mut headers = request.headers().clone();
498    let mut response = client.execute(request).await.map_err(from_reqwest)?;
499    for _ in 0..MAX_REDIRECTS {
500        let drop_body = match response.status() {
501            StatusCode::MOVED_PERMANENTLY | StatusCode::FOUND => method == Method::POST,
502            StatusCode::SEE_OTHER => true,
503            StatusCode::TEMPORARY_REDIRECT | StatusCode::PERMANENT_REDIRECT => false,
504            _ => return Ok(response),
505        };
506        if drop_body {
507            if method != Method::HEAD {
508                method = Method::GET;
509            }
510            body = Some(Bytes::new());
511            headers.remove(CONTENT_TYPE);
512            headers.remove(CONTENT_LENGTH);
513            headers.remove(CONTENT_ENCODING);
514            headers.remove(TRANSFER_ENCODING);
515        }
516        let location = response.headers().get(LOCATION);
517        let location = location.and_then(|location| location.to_str().ok());
518        let previous = response.url();
519        let (Some(mut url), Some(replay)) = (
520            location.and_then(|location| previous.join(location).ok()),
521            body.clone(),
522        ) else {
523            return Ok(response);
524        };
525        if url.origin() == previous.origin() {
526            let mut referer = previous.clone();
527            let _ = referer.set_username("");
528            let _ = referer.set_password(None);
529            referer.set_fragment(None);
530            if let Ok(referer) = HeaderValue::from_str(referer.as_str()) {
531                headers.insert(REFERER, referer);
532            }
533        } else {
534            let kept = [ACCEPT, CONTENT_ENCODING, CONTENT_TYPE, RANGE, USER_AGENT];
535            headers = headers
536                .iter()
537                .filter(|(name, _)| kept.contains(*name))
538                .map(|(name, value)| (name.clone(), value.clone()))
539                .collect();
540        }
541        // reqwest's builder would turn these into an `Authorization` header.
542        let _ = url.set_username("");
543        let _ = url.set_password(None);
544        let request = client.request(method.clone(), url).headers(headers.clone());
545        response = request.body(replay).send().await.map_err(from_reqwest)?;
546    }
547    Ok(response)
548}
549
550/// Sends `parts` with `payload` through `client` and reads the reply with
551/// `convert`. The reactor is selected on first poll and kept through the
552/// conversion.
553fn send_with<C, T, F>(
554    client: &C,
555    parts: http::request::Parts,
556    payload: Result<Payload>,
557    convert: impl FnOnce(reqwest::Response) -> F + WasmCompatSend + 'static,
558) -> impl Future<Output = Result<T>> + WasmCompatSend + 'static
559where
560    C: Execute,
561    F: Future<Output = Result<T>> + WasmCompatSend,
562{
563    let sent = client.execute(parts, payload);
564    async move {
565        let sent = sent?;
566        let operation = async move { convert(sent.await?).await };
567        #[cfg(not(target_family = "wasm"))]
568        let operation = rig_http::runtime::bind(operation)?;
569        operation.await
570    }
571}
572
573/// [`HttpClientExt`] for a client that implements [`Execute`].
574macro_rules! http_client_ext {
575    ($client:ty) => {
576        impl HttpClientExt for $client {
577            fn send(
578                &self,
579                req: Request<Bytes>,
580            ) -> impl Future<Output = Result<Response<LazyBody>>> + WasmCompatSend + 'static {
581                let (parts, body) = req.into_parts();
582                send_with(self, parts, Ok(Payload::Bytes(body)), into_response)
583            }
584
585            fn send_multipart(
586                &self,
587                req: Request<MultipartForm>,
588            ) -> impl Future<Output = Result<Response<LazyBody>>> + WasmCompatSend + 'static {
589                let (parts, form) = req.into_parts();
590                // Reject invalid MIME types locally rather than sending incomplete metadata.
591                let payload = multipart_form(form).map(Payload::Form);
592                send_with(self, parts, payload, into_response)
593            }
594
595            fn send_streaming(
596                &self,
597                req: Request<Bytes>,
598            ) -> impl Future<Output = Result<StreamingResponse>> + WasmCompatSend {
599                let (parts, body) = req.into_parts();
600                let payload = Ok(Payload::Bytes(body));
601                send_with(self, parts, payload, into_streaming_response)
602            }
603        }
604    };
605}
606http_client_ext!(ReqwestClient);
607
608#[cfg(any(
609    feature = "reqwest-middleware-rustls",
610    feature = "reqwest-middleware-native-tls"
611))]
612mod middleware;
613#[cfg(any(
614    feature = "reqwest-middleware-rustls",
615    feature = "reqwest-middleware-native-tls"
616))]
617pub use middleware::ReqwestMiddlewareClient;
618
619// Compile-time thread-safety contract: the transport handle is shared across
620// threads by every host runtime.
621#[cfg(not(target_family = "wasm"))]
622const _: fn() = || {
623    fn assert_send_sync_static<T: Send + Sync + 'static>() {}
624    assert_send_sync_static::<ReqwestClient>();
625};
626
627#[cfg(test)]
628mod tests;