fetch_kit/middleware/
mod.rs

1//! Middleware: the core [`Middleware`] trait + [`ClientWithMiddleware`]
2//! chain runner, plus the bundled feature-gated implementations.
3//!
4//! # Ordering semantics
5//!
6//! Middleware wrap the transport in an onion; the middleware registered
7//! **first** is the **outermost** layer — it observes the request first
8//! and the response last:
9//!
10//! ```text
11//! ClientBuilder::new(client)
12//!     .with(AuthMiddleware)       // 1st registered → outermost
13//!     .with(RetryMiddleware::new(config))
14//!     .build();
15//!
16//! request  →  Auth  →  Retry  →  transport
17//! response ←  Auth  ←  Retry  ←  ╹
18//! ```
19//!
20//! Inner middleware therefore see *every attempt* a retry-style outer
21//! middleware issues, and outer middleware see only the final outcome.
22//! The built-in default client composes `[retry, breaker]`: the breaker
23//! sits inside the retry loop and records each HTTP attempt
24//! individually.
25//!
26//! # Built-ins vs middleware (the composition story)
27//!
28//! The bundled middleware are the *composition points*; the
29//! [`crate::ClientBuilder`] knobs are the *defaults*:
30//!
31//! | Knob (default) | Middleware equivalent (composable) |
32//! |---|---|
33//! | `retries` / `retry_bounds` | `RetryMiddleware` (feature `retry`, default-on) |
34//! | `with_breaker` | `CircuitBreakerMiddleware` (feature `circuit-breaker`) |
35//! | — | `ThrottleMiddleware` (feature `throttle`) |
36//! | — | `TimeoutMiddleware` (feature `timeout`) |
37//! | `base_url` (eager) | `BaseUrlMiddleware` (feature `base-url`) |
38//!
39//! [`crate::ClientBuilder::with_middleware`] registers custom middleware
40//! **outermost** — wrapping the built-ins — so user middleware observe the
41//! final outcome of the whole default stack.
42
43#[cfg(feature = "base-url")]
44mod base_url;
45mod chain;
46#[cfg(feature = "circuit-breaker")]
47mod circuit_breaker;
48#[cfg(feature = "retry")]
49mod retry;
50#[cfg(feature = "throttle")]
51mod throttle;
52#[cfg(feature = "timeout")]
53mod timeout;
54
55#[cfg(feature = "base-url")]
56pub use base_url::{BaseUrlMiddleware, RELATIVE_MARKER_HOST};
57pub use chain::{
58    ClientBuilder, ClientWithMiddleware, Error, Middleware, Next, RequestBuilder, Result,
59};
60#[cfg(feature = "circuit-breaker")]
61pub use circuit_breaker::CircuitBreakerMiddleware;
62#[cfg(feature = "retry")]
63pub use loop_retry::RetryConfig;
64#[cfg(feature = "retry")]
65pub use retry::{RetryMiddleware, is_retryable_error, is_retryable_status};
66#[cfg(feature = "throttle")]
67pub use throttle::ThrottleMiddleware;
68#[cfg(feature = "timeout")]
69pub use timeout::TimeoutMiddleware;
fetch_kit/middleware/mod.rs

fetch_kit/middleware/
mod.rs
