Skip to main content

rig_http/http_client/
mod.rs

1//! Transport-independent HTTP requests, lazy response bodies, and errors.
2//!
3//! ```
4//! use rig_http::http_client::{Bytes, Request};
5//!
6//! let request = Request::get("https://example.com/v1/models").body(Bytes::new())?;
7//! assert_eq!(request.uri().path(), "/v1/models");
8//! # Ok::<(), rig_http::http_client::Error>(())
9//! ```
10
11pub use bytes::Bytes;
12pub use http::{
13    HeaderMap, HeaderValue, Method, Request, Response, StatusCode, Uri, request::Builder,
14};
15mod erased;
16pub mod framing;
17pub mod middleware;
18pub mod multipart;
19use crate::wasm_compat::*;
20pub use erased::DynHttpClient;
21pub use middleware::{Exchange, HttpMiddleware};
22pub use multipart::MultipartForm;
23
24/// A boxed error: `Send + Sync` except on wasm.
25#[cfg(not(target_family = "wasm"))]
26pub type BoxError = Box<dyn std::error::Error + Send + Sync + 'static>;
27
28/// A boxed error: `Send + Sync` except on wasm.
29#[cfg(target_family = "wasm")]
30pub type BoxError = Box<dyn std::error::Error + 'static>;
31
32/// Why an HTTP request failed: a protocol or header error, a non-success
33/// reply, or the transport's own error, which says whether sending the same
34/// request again may work.
35#[derive(Debug, thiserror::Error)]
36#[non_exhaustive]
37pub enum Error {
38    /// The request could not be built.
39    #[error("Http error: {0}")]
40    Protocol(#[from] http::Error),
41    /// Failed HTTP response preserving its status, body, and headers.
42    /// Transport failures without a response use [`Self::Transient`],
43    /// [`Self::Permanent`] or a protocol variant.
44    #[error("Invalid status code {status} with message: {body}")]
45    InvalidStatusCodeWithDetails {
46        /// The non-success status.
47        status: StatusCode,
48        /// The raw response body.
49        body: String,
50        /// The failed response's headers, verbatim.
51        headers: http::HeaderMap,
52    },
53    /// The response stream ended before it was done.
54    #[error("Stream ended")]
55    StreamEnded,
56    /// The response's content type was not the one expected.
57    #[error("Invalid content type was returned: {0:?}")]
58    InvalidContentType(HeaderValue),
59    /// The transport failed without a reply, and sending the same request
60    /// again may work: a refused or reset connection, a timeout, a body cut
61    /// short.
62    #[error("Http client error: {0}")]
63    Transient(#[source] BoxError),
64    /// The transport failed without a reply, and sending the same request
65    /// again fails the same way: a request it cannot send as it is, missing
66    /// credentials, a client that could not be built.
67    #[error("Http client error: {0}")]
68    Permanent(#[source] BoxError),
69}
70
71impl Error {
72    /// Preserved HTTP failure status, or `None` for other error variants.
73    pub fn non_success_status(&self) -> Option<StatusCode> {
74        match self {
75            Self::InvalidStatusCodeWithDetails { status, .. } => Some(*status),
76            _ => None,
77        }
78    }
79
80    /// The response body this error preserved, when it has one. Companion to
81    /// [`Self::non_success_status`] and [`Self::non_success_headers`].
82    pub fn non_success_body(&self) -> Option<&str> {
83        match self {
84            Self::InvalidStatusCodeWithDetails { body, .. } => Some(body.as_str()),
85            _ => None,
86        }
87    }
88
89    /// Constructs a failure from its HTTP status, headers, and body without
90    /// validating that the status is non-successful.
91    pub fn non_success_with_details(status: StatusCode, headers: HeaderMap, body: String) -> Self {
92        Self::InvalidStatusCodeWithDetails {
93            status,
94            body,
95            headers,
96        }
97    }
98
99    /// Returns the failed response's headers, when this error preserved them.
100    /// Don't parse `Retry-After` from them by hand: a provider error carries
101    /// these headers into rig-core's `ErrorReport`, whose `retry_after` reads
102    /// every form of the wait a provider asks for.
103    ///
104    /// Returns `None` for a response-less failure: every non-success error
105    /// carries its headers.
106    pub fn non_success_headers(&self) -> Option<&HeaderMap> {
107        match self {
108            Self::InvalidStatusCodeWithDetails { headers, .. } => Some(headers),
109            _ => None,
110        }
111    }
112}
113
114/// A result with an HTTP [`Error`].
115pub type Result<T> = std::result::Result<T, Error>;
116
117impl Error {
118    /// Whether sending the same request again may pass: after `StreamEnded`
119    /// and what the transport called [`Error::Transient`] it may, a status
120    /// decides through [`retryable_status`], and after anything else
121    /// (protocol, header and content-type errors, [`Error::Permanent`]) it
122    /// does not. A retry may repeat a request the server already processed.
123    pub fn is_transient(&self) -> bool {
124        match self {
125            Self::StreamEnded | Self::Transient(_) => true,
126            Self::InvalidStatusCodeWithDetails { status, .. } => {
127                retryable_status(Some(status.as_u16()))
128            }
129            _ => false,
130        }
131    }
132
133    /// A transport's own error after which sending the same request again
134    /// may work, such as a reset connection or a timeout. A non-success
135    /// reply goes through [`Error::non_success_with_details`] instead, so its
136    /// status decides.
137    pub fn transient(error: impl Into<BoxError>) -> Self {
138        Self::Transient(error.into())
139    }
140
141    /// A transport's own error that sending the same request again meets
142    /// again, such as a request it cannot send or a client it could not
143    /// build.
144    pub fn permanent(error: impl Into<BoxError>) -> Self {
145        Self::Permanent(error.into())
146    }
147}
148
149/// The one status → retryable table.
150///
151/// Request Timeout (408), Too Early (425), Too Many Requests (429) and every
152/// server error (5xx) are retryable; every other status is not. A missing
153/// status decides nothing here: a failure with no status is classified by
154/// what its transport called it ([`Error::Transient`] or
155/// [`Error::Permanent`]), not by what it lacks.
156pub const fn retryable_status(status: Option<u16>) -> bool {
157    match status {
158        None => false,
159        Some(408 | 425 | 429) => true,
160        Some(s) => s >= 500 && s <= 599,
161    }
162}
163
164/// A response body that is read when awaited.
165pub type LazyBody = WasmBoxedFuture<'static, Result<Bytes>>;
166
167/// The body of a streaming response: the transport's own chunks, boxed.
168pub type BoxedStream = WasmBoxedStream<'static, Result<Bytes>>;
169
170/// A response whose body streams.
171pub type StreamingResponse = Response<BoxedStream>;
172
173/// The empty body of a WebSocket handshake request. An HTTP request with no
174/// body sends `Bytes::new()`.
175#[derive(Debug, Clone, Copy)]
176pub struct NoBody;
177
178impl From<NoBody> for Bytes {
179    fn from(_: NoBody) -> Self {
180        Bytes::new()
181    }
182}
183
184/// Reads `response`'s body as text, replacing invalid UTF-8.
185pub async fn text(response: Response<LazyBody>) -> Result<String> {
186    let text = response.into_body().await?;
187    Ok(String::from(String::from_utf8_lossy(&text)))
188}
189
190/// An HTTP client Rig sends through: unary, multipart and streaming requests.
191///
192/// `rig-reqwest`'s `ReqwestClient` is the bundled implementation; a provider
193/// configuration takes any implementation with `connect(client)`.
194#[diagnostic::on_unimplemented(
195    message = "`{Self}` is not an HTTP client Rig can send through",
196    label = "not an `HttpClientExt`",
197    note = "use `rig_reqwest::ReqwestClient` (wrap a configured `reqwest::Client` with `ReqwestClient::from(client)`), erase a client with `DynHttpClient::new(client)`, or implement `HttpClientExt`; a provider configuration takes it with `.connect(client)`"
198)]
199pub trait HttpClientExt: WasmCompatSend + WasmCompatSync {
200    /// Sends a request and returns headers with a lazy body.
201    fn send(
202        &self,
203        req: Request<Bytes>,
204    ) -> impl Future<Output = Result<Response<LazyBody>>> + WasmCompatSend + 'static;
205
206    /// Sends a multipart request and returns headers with a lazy body.
207    fn send_multipart(
208        &self,
209        req: Request<MultipartForm>,
210    ) -> impl Future<Output = Result<Response<LazyBody>>> + WasmCompatSend + 'static;
211
212    /// Sends a request and returns headers with a stream of transport byte chunks.
213    fn send_streaming(
214        &self,
215        req: Request<Bytes>,
216    ) -> impl Future<Output = Result<StreamingResponse>> + WasmCompatSend;
217}
218
219#[cfg(test)]
220mod non_success_header_tests;