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;