Struct RequestBuilder 

pub struct RequestBuilder { /* private fields */ }

HTTP request builder with fluent API

Created by [HttpClient::get], [HttpClient::post], etc. Supports chaining headers and body configuration before sending with send().

URL Construction

This crate does not provide query-string composition. Build your URL externally (e.g. via url::Url) and pass the final string to HttpClient:

use url::Url;
use toolkit_http::HttpClient;

let mut url = Url::parse("https://api.example.com/users")?;
url.query_pairs_mut()
    .append_pair("page", "1")
    .append_pair("limit", "10");

let client = HttpClient::builder().build()?;
let resp = client.get(url.as_str()).send().await?;

Example

use toolkit_http::HttpClient;

let client = HttpClient::builder().build()?;

// Simple GET
let resp = client
    .get("https://api.example.com/users")
    .send()
    .await?;

// POST with JSON body
let resp = client
    .post("https://api.example.com/users")
    .header("x-request-id", "123")
    .json(&NewUser { name: "Alice" })?
    .send()
    .await?;

// POST with form body
let resp = client
    .post("https://auth.example.com/token")
    .header("authorization", "Basic xyz")
    .form(&[("grant_type", "client_credentials")])?
    .send()
    .await?;

Implementations

impl RequestBuilder

pub fn header(self, name: &str, value: &str) -> Self

Add a single header to the request

Example

let resp = client
    .get("https://api.example.com")
    .header("authorization", "Bearer token")
    .header("x-request-id", "abc123")
    .send()
    .await?;

pub fn headers(self, headers: Vec<(String, String)>) -> Self

Add multiple headers to the request

Example

let resp = client
    .get("https://api.example.com")
    .headers(vec![
        ("authorization".to_owned(), "Bearer token".to_owned()),
        ("x-request-id".to_owned(), "abc123".to_owned()),
    ])
    .send()
    .await?;

pub fn with_request_type(self, t: impl Into<Cow<'static, str>>) -> Self

Attach a request_type label for metrics.

The label is added as a request_type attribute on the http.client.request.duration histogram when the otel feature and a metrics layer are configured. This mirrors go-appkit’s NewContextWithRequestType / GetRequestTypeFromContext pattern and lets you break down metrics by logical operation rather than route alone.

Setting this without a metrics layer is a safe no-op.

Example

client
    .get("https://api.example.com/tenants/123")
    .with_request_type("tenants_resolve")
    .send()
    .await?;

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

Set request body as JSON

Serializes the value using serde_json and sets Content-Type to application/json. unless a Content-Type header was already provided.

Errors

Returns Err(HttpError::Json) if serialization fails.

Example

#[derive(Serialize)]
struct CreateUser { name: String }

let resp = client
    .post("https://api.example.com/users")
    .json(&CreateUser { name: "Alice".into() })?
    .send()
    .await?;

pub fn form(self, fields: &[(&str, &str)]) -> Result<Self, HttpError>

Set request body as form URL-encoded

Serializes the fields and sets Content-Type to application/x-www-form-urlencoded. unless a Content-Type header was already provided.

Errors

Returns Err(HttpError::FormEncode) if encoding fails.

Example

let resp = client
    .post("https://auth.example.com/token")
    .form(&[
        ("grant_type", "client_credentials"),
        ("client_id", "my-app"),
    ])?
    .send()
    .await?;

pub fn body_bytes(self, body: Bytes) -> Self

Set request body as raw bytes

Example

let resp = client
    .post("https://api.example.com/upload")
    .header("content-type", "application/octet-stream")
    .body_bytes(Bytes::from(file_contents))
    .send()
    .await?;

pub fn body_string(self, body: String) -> Self

Set request body as a string

Example

let resp = client
    .post("https://api.example.com/text")
    .header("content-type", "text/plain")
    .body_string("Hello, World!".into())
    .send()
    .await?;

pub async fn send(self) -> Result<HttpResponse, HttpError>

Send the request and return the response

Errors

Returns HttpError if:

• Request building failed (invalid headers, URL, etc.)
• URL scheme is invalid for the transport security mode
• Network/transport error
• Request timeout
• Concurrency limit reached (Overloaded)

Example

let resp = client
    .get("https://api.example.com/data")
    .send()
    .await?;

let data: MyData = resp.json().await?;