Struct RequestBuilder 

pub struct RequestBuilder<'a> { /* private fields */ }

Fluent builder for a single HTTP request.

By default send returns Response even on non-2xx status. Use throw_on_error(true) to get Err from send, or use send_json which checks status before deserializing.

Implementations

impl<'a> RequestBuilder<'a>

pub fn param(self, key: impl Into<String>, value: impl ToString) -> Self

Sets a path template parameter (:key in the path).

pub fn params(self, params: HashMap<String, String>) -> Self

Merges path parameters from a map.

pub fn params_iter( self, params: impl IntoIterator<Item = (impl Into<String>, impl ToString)>, ) -> Self

Merges path parameters from an iterator.

pub fn params_ordered( self, params: impl IntoIterator<Item = (impl Into<String>, impl ToString)>, ) -> Self

Merges path parameters in iterator order (substitution follows :segment order in the path).

Alias for params_iter; prefer this name when documenting ordered routes.

pub fn base_url(self, base_url: impl AsRef<str>) -> Result<Self>

Overrides the client base URL for this request only.

Examples

let client = Client::new("https://api.example.com")?;
let _ = client
    .get("/health")
    .base_url("https://status.example.com")?
    .send()
    .await?;

pub fn query(self, key: impl Into<String>, value: impl ToString) -> Self

Adds a query string parameter.

pub fn queries(self, query: IndexMap<String, QueryValue>) -> Self

Sets multiple query parameters preserving insertion order.

pub fn query_json<T: Serialize>( self, key: impl Into<String>, value: &T, ) -> Result<Self>

Available on crate feature json only.

Serializes value as JSON and uses it as a query parameter (feature json).

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

Adds a request header.

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

Available on crate feature json only.

Sets a JSON request body (feature json).

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

Sets a raw request body.

pub fn content_type(self, value: impl AsRef<str>) -> Result<Self>

Sets Content-Type when not already present.

pub fn body_stream(self, stream: BodyStream) -> Self

Sets a streaming request body (not replayable with automatic retry).

Sets Content-Type to application/octet-stream when not already set.

pub fn form<I, K, V>(self, fields: I) -> Self

where I: IntoIterator<Item = (K, V)>, K: AsRef<str>, V: AsRef<str>,

URL-encoded form body (application/x-www-form-urlencoded).

pub fn multipart(self, form: Form) -> Self

Available on crate feature multipart only.

Multipart form body (requires the multipart feature).

Automatic retry is not supported when multipart bodies are used.

pub fn timeout(self, timeout: Duration) -> Self

Overrides the client default timeout for this request.

pub fn retry(self, policy: RetryPolicy) -> Self

Overrides the client default retry policy for this request.

pub fn auth(self, auth: Auth) -> Self

Overrides authentication for this request.

pub fn bearer_token(self, token: impl Into<String>) -> Self

Sets bearer authentication for this request.

pub fn cancellation_token(self, token: CancellationToken) -> Self

Cancels the in-flight request and retry sleeps when this token is triggered.

Examples

let client = Client::new("https://api.example.com")?;
let token = CancellationToken::new();
let token_clone = token.clone();
tokio::spawn(async move {
    tokio::time::sleep(Duration::from_millis(10)).await;
    token_clone.cancel();
});
let err = client
    .get("/slow")
    .cancellation_token(token)
    .send()
    .await
    .unwrap_err();
assert!(err.is_cancelled());

pub fn throw_on_error(self, throw: bool) -> Self

When true, send returns Err on non-2xx HTTP status (like upstream throw: true).

pub fn json_parser<F>(self, f: F) -> Self

where F: Fn(&Bytes) -> Result<Value, String> + Send + Sync + 'static,

Available on crate feature json only.

Overrides the client’s JSON parser for this request only.

See crate::json_parser for fast path vs two-step parsing.

pub fn json_parser_fn(self, parser: JsonParserFn) -> Self

Available on crate feature json only.

Overrides the client’s JSON parser for this request only.

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

Executes the request and returns the Response.

Non-2xx responses are returned as Ok(Response) unless throw_on_error is true. Deserialize JSON with Response::json or use send_json for a one-step typed result.

Examples

let client = Client::new("https://api.example.com")?;
let response = client.get("/users/1").send().await?;
if response.is_success() {
    println!("status {}", response.status());
}

pub fn max_response_bytes(self, limit: u64) -> Self

Maximum response body size in bytes for this request.

Applies to send, send_json, send_stream, and StreamingResponse::collect. When the body would exceed the limit, returns Error::BodyTooLarge. On the streaming path, the limit is also enforced incrementally on each chunk.

pub fn retry_body_peek_bytes(self, limit: u64) -> Self

Overrides the client default for how many bytes may be read when a custom retry predicate runs on a stream.

pub async fn send_stream(self) -> Result<StreamingResponse>

Executes the request and returns a StreamingResponse without buffering the full body.

Uses Hooks::on_request, Hooks::on_response_stream, and Hooks::on_success_stream (2xx). Buffered Hooks::on_response / on_success are not called. Custom retry predicates may peek up to ClientBuilder::retry_body_peek_bytes without consuming the body returned to the caller. Non-2xx responses keep the full streaming body unless Self::throw_on_error(true) or a retry discards it. Cancellation wakes pending body reads via the cancellation token (checked on each stream poll).

Examples

let client = Client::new("https://api.example.com")?;
let mut response = client.get("/export").send_stream().await?;
while let Some(chunk) = response.bytes_stream().next().await {
    let _chunk = chunk?;
}

pub async fn send_json<T: DeserializeOwned>(self) -> Result<T>

Available on crate feature json only.

Executes the request and deserializes JSON on success (feature json).

Fails with Error::Http or Error::Deserialize on non-2xx or invalid JSON.

Examples

let client = Client::new("https://api.example.com")?;
let user: User = client.get("/users/:id").param("id", 1).send_json().await?;

pub fn disable_validation(self, disable: bool) -> Self

Available on crate feature schema-validate only.

When true, skip registry JSON Schema validation for this request (request body, query, params, and response on send() / StreamingResponse::collect).

Strict SchemaRegistry::ensure_route still runs. Does not affect garde (validate_response on send_json_validated).

Matches upstream TypeScript disableValidation (feature schema-validate).

pub fn validate_response(self, validate: bool) -> Self

Available on crate feature validate only.

When false, send_json_validated only deserializes (no garde).

pub async fn send_json_validated<T>(self) -> Result<T>

where T: DeserializeOwned + Validate, T::Context: Default,

Available on crate feature validate only.

send + Response::json_validated (feature validate).

pub fn json_validated<T>(self, body: &T) -> Result<Self>

where T: Serialize + Validate, T::Context: Default,

Available on crate feature validate only.

Serializes and validates body with garde::Validate before sending (feature validate).