Struct RequestBuilder 

pub struct RequestBuilder { /* private fields */ }

Fluent outbound request builder produced by Client methods.

Implementations

impl RequestBuilder

pub fn header(self, name: impl AsRef<str>, value: impl AsRef<str>) -> Self

Append a request header.

Headers named authorization, cookie, or set-cookie are accepted normally but are redacted in tracing events and log output. Invalid header names or values emit a tracing::warn! and are skipped.

pub fn json<T: Serialize>(self, body: &T) -> Self

Serialise body as JSON and set Content-Type: application/json.

Serialisation errors are captured and returned when send is called rather than being silently discarded.

pub fn text_body(self, body: impl Into<String>) -> Self

Set a plain-text body.

pub const fn retries(self, max: u32) -> Self

Override the maximum retry count for this request.

Also clears the idempotent-only flag so non-idempotent methods such as POST and PATCH are retried when the caller explicitly requests it.

pub const fn max_retry_after(self, max: Duration) -> Self

Override the maximum Retry-After sleep duration for this request.

pub const fn no_retry(self) -> Self

Disable retries for this request.

pub fn no_redirect(self) -> Self

Disable redirect following for this request.

A 3xx response is returned to the caller verbatim (status, headers and body) rather than being followed. Routes the request through the custom one-shot-client send path, which bypasses the process-wide circuit breaker.

pub fn follow_redirects<F>(self, max: usize, validator: F) -> Self

where F: Fn(&str) -> bool + Send + Sync + 'static,

Follow up to max redirects, validating each hop before following it.

Before following a 3xx, the Location header is resolved to an absolute URL (relative locations are joined against the current URL) and validator(&absolute_location) is called. If it returns false the request fails with ClientError::RedirectRejected. If the chain would exceed max hops the request fails with ClientError::TooManyRedirects (so max == 0 turns the first 3xx into an error). Routes the request through the custom one-shot-client send path, which bypasses the process-wide circuit breaker.

TOCTOU / rebinding limitation. The validator receives the redirect target as a string (not a resolved IP), and the subsequent connection re-resolves that host via normal DNS. So a validator that inspects IP literals sees only literal hosts, has a connect-time TOCTOU window against a hostname that re-resolves between check and connect, and provides no address pinning. When you need pinned, rebind-safe following that validates every resolved IP and pins the connection per hop, use Client::get_ssrf_safe instead.

pub const fn pin_to(self, addr: SocketAddr) -> Self

Pin the connection to addr, skipping DNS resolution.

The original Host header and TLS SNI are preserved; only the address the socket connects to is overridden. This protects against DNS-rebinding / TOCTOU attacks where a hostname re-resolves to a different (private) address between validation and connection.

Requires a domain (hostname) URL host. The pin is enforced via a DNS resolve override, but reqwest/hyper treat an IP-literal URL host as already-resolved and never consult the resolver — so the override is skipped and the socket would connect to the literal in the URL, not the pinned address. A pin_to request whose URL host is an IP literal (IPv4 or IPv6) is therefore rejected at send time with ClientError::PinRequiresDomainHost. Put the desired IP directly in the URL (no pin needed), or use a domain host.

Pinning applies to the initial connection only. Redirects are not followed under pin_to: a 3xx is returned to the caller verbatim (as if no_redirect were set) rather than being auto-followed to a possibly-different host that would be re-resolved via normal DNS, silently escaping the pin. If you need pinned, rebind-safe per-hop following, use Client::get_ssrf_safe instead.

Cannot be combined with follow_redirects. Because the pin only covers the first hop while later hops would re-resolve via DNS, chaining pin_to with follow_redirects (in either order) is rejected at send time with ClientError::IncompatiblePinRedirect rather than silently following a redirect off the pinned address. Use Client::get_ssrf_safe for pinned, per-hop-revalidated redirect following, pin_to alone (which returns the 3xx unfollowed), or follow_redirects without pin_to.

Implemented via a one-shot reqwest::ClientBuilder::resolve(host, addr) scoped to this request. Note that reqwest ignores the port in the resolve override and connects to the port from the request URL, so addr.port() is only honoured when it matches the URL’s port (which it does for addresses obtained by resolving that same URL). Routes the request through the custom one-shot-client send path, which bypasses the process-wide circuit breaker.

Env proxies are bypassed. The pinned client is built with .no_proxy(), so HTTP_PROXY / HTTPS_PROXY / ALL_PROXY are ignored and the socket connects directly to addr. This is required for the pin to hold: reqwest checks proxy interception before the connector where the resolve() override applies, so a configured proxy would otherwise receive the request and re-resolve the host — defeating the pin.

pub async fn send(self) -> Result<Response, ClientError>

Send the request, applying retries and returning a Response.

Errors

Returns ClientError::Json if a prior .json() call failed to serialise the body. Returns ClientError::Request for transport errors that exhaust all retry attempts. Returns ClientError::NoMock if the request is made in a test context without a matching mock entry.

Panics

Contains an internal unreachable!() that guards against a logic error in the retry loop; it cannot be reached in practice.