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, ) -> RequestBuilder<'a>

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

pub fn params(self, params: HashMap<String, String>) -> RequestBuilder<'a>

Merges path parameters from a map.

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

Merges path parameters from an iterator.

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

Adds a query string parameter.

pub fn queries(self, query: IndexMap<String, QueryValue>) -> RequestBuilder<'a>

Sets multiple query parameters preserving insertion order.

pub fn query_json<T>( self, key: impl Into<String>, value: &T, ) -> Result<RequestBuilder<'a>, Error>

where T: Serialize,

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<RequestBuilder<'a>, Error>

Adds a request header.

pub fn json<T>(self, body: &T) -> Result<RequestBuilder<'a>, Error>

where T: Serialize,

Sets a JSON request body (feature json).

pub fn body(self, body: impl Into<Bytes>) -> RequestBuilder<'a>

Sets a raw request body.

pub fn form<I, K, V>(self, fields: I) -> RequestBuilder<'a>

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

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

pub fn timeout(self, timeout: Duration) -> RequestBuilder<'a>

Overrides the client default timeout for this request.

pub fn retry(self, policy: RetryPolicy) -> RequestBuilder<'a>

Overrides the client default retry policy for this request.

pub fn auth(self, auth: Auth) -> RequestBuilder<'a>

Overrides authentication for this request.

pub fn bearer_token(self, token: impl Into<String>) -> RequestBuilder<'a>

Sets bearer authentication for this request.

pub fn cancellation_token(self, token: CancellationToken) -> RequestBuilder<'a>

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) -> RequestBuilder<'a>

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

pub fn json_parser<F>(self, f: F) -> RequestBuilder<'a>

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

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: Arc<dyn Fn(&Bytes) -> Result<Value, String> + Sync + Send>, ) -> RequestBuilder<'a>

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

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

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) -> RequestBuilder<'a>

Maximum response body size in bytes for this streaming request.

Applies to send_stream only. When a chunk would exceed the limit, the stream yields Error::BodyTooLarge.

pub fn retry_body_peek_bytes(self, limit: u64) -> RequestBuilder<'a>

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, Error>

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. 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>(self) -> Result<T, Error>

where T: DeserializeOwned,

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?;