3 releases (1 stable)
new 1.0.0 | Dec 4, 2024 |
---|---|
0.2.0 | Apr 15, 2024 |
0.1.0 | Dec 6, 2022 |
#111 in HTTP client
2,345 downloads per month
13KB
85 lines
reqwest-chain
Apply custom criteria to any reqwest
response, deciding when and how to retry.
reqwest-chain
builds on reqwest-middleware
, to allow you to focus on your core logic without the boilerplate.
Use case
This crate is a more general framework than reqwest-retry
. It allows inspection of:
- The result of the previous request
- The state of the retry chain
- The global state of your middleware
Based on this information, it allows updating any aspect of the next request.
If all you need is a simple retry, you should use reqwest-retry
.
Getting started
See the tests
directory for several examples.
You should implement Chainer
for your middleware struct. This uses the chain
method to make a decision after each request respones:
- If another request is required, update the previous request to form the
next request in the chain, and return
Ok(None)
. - If the response is ready, return it inside
Ok(Some(response))
. - If an error occurs and you cannot continue, return
Err(error)
.
Below is the initial use case; refresh some authorization credential on request failure.
use reqwest_chain::{Chainer, ChainMiddleware};
use reqwest_middleware::reqwest::{Client, Request, Response, StatusCode};
use reqwest_middleware::reqwest::header::{AUTHORIZATION, HeaderValue};
use reqwest_middleware::{ClientBuilder, ClientWithMiddleware, Error};
// Mimic some external function that returns a valid token.
fn fetch_token() -> String {
"valid-token".to_string()
}
struct FetchTokenMiddleware;
#[async_trait::async_trait]
impl Chainer for FetchTokenMiddleware {
// We don't need it here, but you can choose to keep track of state between
// chained retries.
type State = ();
async fn chain(
&self,
result: Result<Response, Error>,
_state: &mut Self::State,
request: &mut Request,
) -> Result<Option<Response>, Error> {
let response = result?;
if response.status() != StatusCode::UNAUTHORIZED {
return Ok(Some(response))
};
request.headers_mut().insert(
AUTHORIZATION,
HeaderValue::from_str(&format!("Bearer {}", fetch_token())).expect("invalid header value"),
);
Ok(None)
}
}
async fn run() {
let client = ClientBuilder::new(Client::new())
.with(ChainMiddleware::new(FetchTokenMiddleware))
.build();
client
.get("https://example.org")
// If this token is invalid, the request will be automatically retried
// with an updated token.
.header(AUTHORIZATION, "Bearer expired-token")
.send()
.await
.unwrap();
}
Thanks
Many thanks to the prior work in this area, namely:
reqwest-middleware
for the underlying frameworkreqwest-retry
for inspiration
Dependencies
~4–15MB
~189K SLoC