Struct ClientBuilder 

pub struct ClientBuilder<IL = Identity, OL = Identity, C = DefaultMkClient, LB = DefaultLb> { /* private fields */ }

Available on crate feature client only.

A builder for configuring an HTTP Client.

Implementations

impl ClientBuilder<Identity, Identity, DefaultMkClient, DefaultLb>

pub fn new() -> Self

Create a new client builder.

impl<IL, OL, C, LB, DISC> ClientBuilder<IL, OL, C, LbConfig<LB, DISC>>

pub fn load_balance<NLB>( self, load_balance: NLB, ) -> ClientBuilder<IL, OL, C, LbConfig<NLB, DISC>>

Set load balancer for the client.

pub fn discover<NDISC>( self, discover: NDISC, ) -> ClientBuilder<IL, OL, C, LbConfig<LB, NDISC>>

Set service discover for the client.

impl<IL, OL, C, LB> ClientBuilder<IL, OL, C, LB>

pub fn layer_inner<Inner>( self, layer: Inner, ) -> ClientBuilder<Stack<Inner, IL>, OL, C, LB>

Add a new inner layer to the client.

The layer’s Service should be Send + Sync + Clone + 'static.

Order

Assume we already have two layers: foo and bar. We want to add a new layer baz.

The current order is: foo -> bar (the request will come to foo first, and then bar).

After we call .layer_inner(baz), we will get: foo -> bar -> baz.

The overall order for layers is: outer -> LoadBalance -> [inner] -> transport.

pub fn layer_inner_front<Inner>( self, layer: Inner, ) -> ClientBuilder<Stack<IL, Inner>, OL, C, LB>

Add a new inner layer to the client.

The layer’s Service should be Send + Sync + Clone + 'static.

Order

Assume we already have two layers: foo and bar. We want to add a new layer baz.

The current order is: foo -> bar (the request will come to foo first, and then bar).

After we call .layer_inner_front(baz), we will get: baz -> foo -> bar.

The overall order for layers is: outer -> LoadBalance -> [inner] -> transport.

pub fn layer_outer<Outer>( self, layer: Outer, ) -> ClientBuilder<IL, Stack<Outer, OL>, C, LB>

Add a new outer layer to the client.

The layer’s Service should be Send + Sync + Clone + 'static.

Order

Assume we already have two layers: foo and bar. We want to add a new layer baz.

The current order is: foo -> bar (the request will come to foo first, and then bar).

After we call .layer_outer(baz), we will get: foo -> bar -> baz.

The overall order for layers is: [outer] -> Timeout -> LoadBalance -> inner -> transport.

pub fn layer_outer_front<Outer>( self, layer: Outer, ) -> ClientBuilder<IL, Stack<OL, Outer>, C, LB>

Add a new outer layer to the client.

The layer’s Service should be Send + Sync + Clone + 'static.

Order

Assume we already have two layers: foo and bar. We want to add a new layer baz.

The current order is: foo -> bar (the request will come to foo first, and then bar).

After we call .layer_outer_front(baz), we will get: baz -> foo -> bar.

The overall order for layers is: [outer] -> LoadBalance -> inner -> transport.

pub fn mk_load_balance<NLB>( self, mk_load_balance: NLB, ) -> ClientBuilder<IL, OL, C, NLB>

Set a new load balance for the client.

pub fn header<K, V>(&mut self, key: K, value: V) -> &mut Self

where K: TryInto<HeaderName>, K::Error: Error + Send + Sync + 'static, V: TryInto<HeaderValue>, V::Error: Error + Send + Sync + 'static,

Insert a header to the request.

pub fn set_tls_config<T>(&mut self, tls_config: T) -> &mut Self

where T: Into<TlsConnector>,

Available on crate features rustls or native-tls only.

Set tls config for the client.

pub fn headers(&self) -> &HeaderMap

Get a reference to the default headers of the client.

pub fn headers_mut(&mut self) -> &mut HeaderMap

Get a mutable reference to the default headers of the client.

pub fn set_title_case_headers(&mut self, title_case_headers: bool) -> &mut Self

👎Deprecated since 0.4.0: set_title_case_headers has been removed into http1_config

Available on crate feature http1 only.

Set whether HTTP/1 connections will write header names as title case at the socket level.

Default is false.

pub fn set_max_headers(&mut self, max_headers: usize) -> &mut Self

👎Deprecated since 0.4.0: set_max_headers has been removed into http1_config

Available on crate feature http1 only.

Set the maximum number of headers.

When a response is received, the parser will reserve a buffer to store headers for optimal performance.

If client receives more headers than the buffer size, the error “message header too large” is returned.

Note that headers is allocated on the stack by default, which has higher performance. After setting this value, headers will be allocated in heap memory, that is, heap memory allocation will occur for each response, and there will be a performance drop of about 5%.

Default is 100.

pub fn http1_config(&mut self) -> &mut Config

Available on crate feature http1 only.

Get configuration of http1 part.

pub fn http2_config(&mut self) -> &mut Config

Available on crate feature http2 only.

Get configuration of http2 part.

pub fn disable_tls(&mut self, disable: bool) -> &mut Self

Available on crate features rustls or native-tls only.

Disable TLS for the client.

Default is false, when TLS related feature is enabled, TLS is enabled by default.

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

Set idle timeout of connection pool.

If a connection is idle for more than the timeout, the connection will be dropped.

Default is 20 seconds.

pub fn set_max_idle_per_host(&mut self, num: usize) -> &mut Self

Set the maximum number of idle connections per host.

If the number of idle connections on a host exceeds this value, the connection pool will refuse to add new idle connections.

Default is 10240.

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

Set the maximum idle time for a connection.

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

Set the maximum idle time for reading data from the connection.

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

Set the maximum idle time for writing data to the connection.

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

Set the maximum idle time for the whole request.

pub fn user_agent<V>(&mut self, val: V) -> &mut Self

where V: TryInto<HeaderValue>, V::Error: Error + Send + Sync + 'static,

Set default User-Agent in request header.

If there is User-Agent given, a default User-Agent will be generated by crate name and version.

pub fn host_mode(&mut self, mode: Host) -> &mut Self

Set mode of client setting Host in headers.

This mode only works when building client by ClientBuilder::build, ClientBuilder::build_without_extra_layers will ignore this config.

For more configurations, refer to Host.

Default is Host::Auto, it will generate a Host by target domain name or address if there is no Host in request headers.

pub fn build<InnerReqBody, OuterReqBody, RespBody>(self) -> Result<C::Target>

where IL: Layer<ClientTransport<InnerReqBody>>, IL::Service: Send + Sync + 'static, LB: MkLbLayer, LB::Layer: Layer<IL::Service>, <LB::Layer as Layer<IL::Service>>::Service: Send + Sync, OL: Layer<<LB::Layer as Layer<IL::Service>>::Service>, OL::Service: Service<ClientContext, Request<OuterReqBody>, Response = Response<RespBody>, Error = ClientError> + Send + Sync + 'static, C: MkClient<Client<OuterReqBody, RespBody>>, InnerReqBody: Send, OuterReqBody: Send + 'static, RespBody: Send,

Build the HTTP client with default configurations.

This method will insert some default layers: Timeout, UserAgent and Host, and the final calling sequence will be as follows:

• Outer:
  • Timeout: Apply timeout from ClientBuilder::set_request_timeout or CallOpt::with_timeout. Note that without this layer, timeout from Client or CallOpt will not work.
  • Host: Insert Host to request headers. Host::Auto will be applied by default, it will insert a Host generated from current Target if there is no Host in headers.
  • UserAgent: Insert User-Agent into the request header, it takes the given value from ClientBuilder::user_agent or generates a value based on the current package name and version. If User-Agent already exists, this layer does nothing.
  • Other outer layers
• LoadBalance (LbConfig with DnsResolver by default)
• Inner layers
  • Other inner layers
• Transport through network or unix domain socket.

pub fn build_without_extra_layers<InnerReqBody, OuterReqBody, RespBody>( self, ) -> Result<C::Target>

where IL: Layer<ClientTransport<InnerReqBody>>, IL::Service: Send + Sync + 'static, LB: MkLbLayer, LB::Layer: Layer<IL::Service>, <LB::Layer as Layer<IL::Service>>::Service: Send + Sync, OL: Layer<<LB::Layer as Layer<IL::Service>>::Service>, OL::Service: Service<ClientContext, Request<OuterReqBody>, Response = Response<RespBody>, Error = ClientError> + Send + Sync + 'static, C: MkClient<Client<OuterReqBody, RespBody>>, InnerReqBody: Send, OuterReqBody: Send + 'static, RespBody: Send,

Build the HTTP client without inserting any extra layers.

This method is provided for advanced users, some features may not work properly without the default layers,

See ClientBuilder::build for more details.

Trait Implementations

impl Default for ClientBuilder<Identity, Identity, DefaultMkClient, DefaultLb>

fn default() -> Self

Returns the “default value” for a type.