Struct ClientBuilder 

pub struct ClientBuilder { /* private fields */ }

Builder for Client.

Implementations

impl ClientBuilder

pub fn new() -> Self

Creates an empty builder; Self::base_url is required before Self::build.

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

Sets the base URL (required).

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

Sets the default request timeout.

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

Sets the default RetryPolicy for all requests.

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

Sets default authentication for all requests.

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

Adds a default header applied to every request.

pub fn hooks(self, hooks: Hooks) -> Self

Sets client-level lifecycle hooks.

pub fn plugin<P: Plugin + 'static>(self, plugin: P) -> Self

Registers a [Plugin] on this client.

pub fn reqwest_client(self, client: ReqwestClient) -> Self

Uses a custom reqwest client for the default ReqwestBackend.

pub fn backend(self, backend: Arc<dyn HttpBackend>) -> Self

Use a custom HTTP backend (for testing or alternate transports).

Examples

let client = ClientBuilder::new()
    .base_url("https://api.example.com")?
    .backend(Arc::new(MockBackend))
    .build()?;

pub fn wire_concurrency_limit(self, limit: usize) -> Self

Declares the limit used by ConcurrencyLimitLayer on your transport stack so Self::build can warn when it matches Self::max_in_flight.

This does not configure Tower; it is only for diagnostics when stacking client and transport caps.

pub fn max_in_flight(self, limit: usize) -> Self

Limits how many requests this client may have in flight at once (including retries).

Implemented with a tokio semaphore in the core client. This counts the full request lifecycle (hooks and retries), not just the transport hop. For wire-level limits only, use Self::transport_stack with Tower’s ConcurrencyLimitLayer (feature tower) instead of—or deliberately alongside—this setting.

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

Maximum response body size (in bytes) for RequestBuilder::send, send_json, and send_stream when the request does not set its own limit.

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

Maximum bytes read from a streaming body when a custom retry predicate is configured.

Defaults to 64 KiB. Capped by Self::max_response_bytes when that is also set.

pub fn schema_registry(self, registry: Arc<SchemaRegistry>) -> Self

Available on crate feature schema only.

Attach a SchemaRegistry for strict route validation (feature schema).

pub fn http_service<S>(self, service: S) -> Self

where S: Service<HttpRequest, Response = HttpResponse, Error = Error> + Clone + Send + 'static, S::Future: Send + 'static,

Available on crate feature tower only.

Use a Tower Service as the HTTP transport for buffered send() only.

send_stream() uses the default reqwest streaming transport without your Tower layers. For middleware on both paths, use Self::transport_stack.

pub fn http_service_boxed(self, service: BoxHttpService) -> Self

Available on crate feature tower only.

Use a boxed Tower transport stack for buffered send() only (streaming uses plain reqwest).

Prefer Self::transport_stack when send_stream() must see the same middleware.

pub fn transport_stack<F>(self, configure: F) -> Self

where F: FnOnce(ReqwestHttpService, ReqwestStreamingHttpService) -> (BoxHttpService, BoxStreamingHttpService),

Available on crate feature tower only.

Build a Tower transport stack on top of the configured (or default) reqwest client.

Application hooks and RetryPolicy remain in the core client; only wire-level behavior is configured here.

Examples

let client = ClientBuilder::new()
    .base_url("https://api.example.com")?
    .transport_stack(|buffered, streaming| {
        (
            ServiceBuilder::new()
                .layer(ConcurrencyLimitLayer::new(32))
                .service(buffered)
                .into_box(),
            ServiceBuilder::new()
                .layer(ConcurrencyLimitLayer::new(32))
                .service(streaming)
                .into_streaming_box(),
        )
    })
    .build()?;

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.

Sets a custom JSON parser for all responses from this client.

See crate::json_parser for the two-step Bytes → Value → T pipeline vs the default single-step fast path, and Response::into_json_with for per-response Bytes → T without a global parser.

Examples

let client = ClientBuilder::new()
    .base_url("https://api.example.com")?
    .json_parser(|body: &Bytes| {
        let slice = body.strip_prefix(b"\xef\xbb\xbf").unwrap_or(body);
        serde_json::from_slice(slice).map_err(|e| e.to_string())
    })
    .build()?;

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

Available on crate feature json only.

Sets a custom JSON parser from an existing JsonParserFn.

pub fn build(self) -> Result<Client>

Builds the Client. Requires Self::base_url.

Examples

let client = ClientBuilder::new()
    .base_url("https://api.example.com")?
    .build()?;

Trait Implementations

impl Default for ClientBuilder

fn default() -> Self

Returns the “default value” for a type.