Struct RequestBuilder 

pub struct RequestBuilder { /* private fields */ }

Fluent outbound request builder produced by Client methods.

Implementations

impl RequestBuilder

pub const fn without_request_id(self) -> Self

Do not send the current request’s id as x-request-id.

By default, a request sent during an inbound request carries that request’s id (issue #3064). Use this for a host that must not see it.

pub const fn criticality(self, criticality: Criticality) -> Self

Send this criticality in the X-Autumn-Criticality header (issue #3068). Without this call, the client sends the criticality of the inbound request that it serves, if any.

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 sign_web_bot_auth(self, signer: &WebBotAuthSigner) -> Self

Sign this request with Web Bot Auth (RFC 9421 HTTP Message Signatures), so the receiving site can verify that it comes from this app. Adds Signature-Agent, Signature-Input, and Signature.

The URL must be absolute. Each attempt (a retry, a same-origin redirect) sends a new signature, so a held builder or a late retry never sends an expired one. See crate::aeo::web_bot_auth.

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 fn bytes_body(self, body: impl Into<Bytes>) -> Self

Set a raw byte body, without assuming any content type.

Use this for binary payloads — text_body takes a String and so cannot carry bytes that are not valid UTF-8. Set the content type yourself with header. The Web Push transport uses this for RFC 8291-encrypted bodies.

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

Override the maximum retry count for this request.

This does not enable retries for POST and PATCH. Use retry_non_idempotent for that.

pub const fn retry_non_idempotent(self) -> Self

Retry non-idempotent methods (POST, PATCH) too.

A retried POST can run two times on the server. So for a non-idempotent method, the client sends an Idempotency-Key header with a random value, the same on every attempt. A key you set with header is kept.

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

Override the cap on the jittered backoff between attempts.

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 const fn discard_response_body(self) -> Self

Return the status and headers without reading the response body.

Every other path collects the whole body into memory with no ceiling, which is the right default for an API call whose payload the caller wants. It is the wrong default when the remote host is untrusted and the caller needs only the status: a server that streams indefinitely then costs one unbounded allocation per request until the timeout fires.

Web Push is exactly that shape — the endpoint URL is chosen by the client, and the transport only ever reads the status code — so it sets this. Response::bytes then returns empty; dropping the underlying response closes the connection without draining it.

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 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 fn pin_to_addrs(self, addrs: impl IntoIterator<Item = SocketAddr>) -> Self

Like pin_to, but accepts several addresses for one host.

All addresses go to one request. reqwest tries the next address only if it cannot connect. A loop over pin_to could send a POST body twice.

An empty set makes send fail. It never drops the pin. Every other rule of pin_to applies.

pub const fn ssrf_safe(self) -> Self

Route this request through the SSRF-safe resolve→validate→pin send path documented on Client::get_ssrf_safe, for any HTTP method.

Client::get_ssrf_safe only builds GET requests, but the guarantee it describes — reject a resolved address on the built-in SSRF deny-list, pin the connection to the validated set, re-validate on every redirect hop — is implemented by Self::send purely from this flag and is not GET-specific. Any outbound call whose destination is not a value the app itself chose — a webhook subscriber’s target_url, a user-supplied callback, an OAuth discovery endpoint — needs this on every verb it uses, not only reads. Chain it after Client::post, Client::put, etc.:

client.post(target_url).ssrf_safe().json(&payload).send().await?;

Same incompatibility with pin_to as get_ssrf_safe: this path performs its own per-hop resolve→validate→pin, so chaining an explicit pin is rejected at send time with ClientError::PinNotAllowedWithSsrfSafe.

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.