Struct ClientBuilder 

pub struct ClientBuilder { /* private fields */ }

Builder for Client. Use it to configure host/port, headers, keep-alive, timeouts, and other options before creating a client instance.

By default:

• ConnectionPolicy is Close;
• no host/port are set until you call ClientBuilder::host / ClientBuilder::port or ClientBuilder::with_uri.
• no operation timeouts are applied unless configured explicitly.

Implementations

impl ClientBuilder

pub fn new() -> Self

Create a new ClientBuilder with default settings.

pub fn host(self, host: &str) -> Self

Set ICAP server host (hostname or IP).

pub const fn port(self, port: u16) -> Self

Set ICAP server TCP port (default 1344 if not set).

pub fn host_override(self, host: &str) -> Self

Override the Host: header value sent in ICAP requests.

This does not change the actual remote address used for the TCP connection, only the value of the Host ICAP header.

pub fn default_header(self, name: &str, value: &str) -> IcapResult<Self>

Insert a default ICAP header that will be sent with every request.

pub fn try_user_agent(self, user_agent: &str) -> IcapResult<Self>

Tries to set the ICAP User-Agent header for all requests created by this client.

A per-request override via Request::icap_header("User-Agent", "...") takes precedence over the value set here. Prefer this fallible variant when the value comes from user input.

pub fn user_agent(self, user_agent: &str) -> Self

Sets the ICAP User-Agent header for all requests created by this client.

A per-request override via Request::icap_header("User-Agent", "...") takes precedence over the value set here.

Example

use icap_rs::Client;
let client = Client::builder()
    .host("icap.example")
    .port(1344)
    .user_agent("my-app/1.2.3")
    .build();

Invalid header values are silently dropped; use ClientBuilder::try_user_agent when validation is required.

pub const fn keep_alive(self, yes: bool) -> Self

Enable or disable connection reuse (keep-alive).

pub const fn with_timeouts(self, timeouts: ClientTimeouts) -> Self

Install a full ClientTimeouts configuration in one shot.

Replaces any per-field timeouts set via Self::timeout, Self::connect_timeout, Self::write_timeout, or Self::continue_timeout. Per-field setters called after with_timeouts continue to mutate the same struct, so

use std::time::Duration;
use icap_rs::{Client, ClientTimeouts};

let tos = ClientTimeouts::default();
let d = Duration::from_secs(3);
let _client = Client::builder()
    .host("icap.example")
    .with_timeouts(tos)
    .connect_timeout(Some(d))
    .build();

is equivalent to mutating tos.connect before passing it in.

pub const fn timeout(self, dur: Option<Duration>) -> Self

Set a timeout for the whole client send operation.

This is an outer deadline around connect, optional TLS handshake, writes, Preview negotiation, and final response reads. More specific timeouts may still fire first.

pub const fn connect_timeout(self, dur: Option<Duration>) -> Self

Set a timeout for establishing the TCP connection.

For icaps://, this covers TCP connect only. TLS handshakes are governed by ClientTlsConfig::with_handshake_timeout.

pub const fn write_timeout(self, dur: Option<Duration>) -> Self

Set a timeout for writing ICAP request bytes to the network.

This covers request headers, preview markers, body chunks, and flushes. It does not limit reading from the caller-provided body source.

pub const fn continue_timeout(self, dur: Option<Duration>) -> Self

Set a timeout for Preview decision responses.

When a request uses ICAP Preview, the client waits for either 100 Continue or an early final response before sending the remainder. If this timeout is not set, only the outer timeout applies when configured.

pub const fn with_response_header_limit(self, bytes: usize) -> Self

Set the maximum ICAP response header block size, in bytes.

The limit includes the status line, all ICAP header lines, and the terminating CRLFCRLF. The default is 64 KiB. Oversized response headers are reported as protocol header errors instead of generic I/O failures.

pub const fn with_options_cache(self, config: OptionsCacheConfig) -> Self

Enable client-side caching of OPTIONS responses (RFC 3507 §4.10 / §5).

When enabled, the client fetches OPTIONS for a service once and reuses it for subsequent REQMOD/RESPMOD requests until it expires. The lifetime comes from the server’s Options-TTL header, falling back to OptionsCacheConfig::default_ttl when the header is absent; with neither, the response is not cached. A changed ISTag on a later modification response invalidates the cached entry.

Caching is opt-in: without this call the client never sends OPTIONS automatically.

Examples

use std::time::Duration;
use icap_rs::{Client, OptionsCacheConfig};

let client = Client::builder()
    .host("127.0.0.1")
    .with_options_cache(OptionsCacheConfig::new().with_default_ttl(Duration::from_secs(60)))
    .build();

pub fn proxy_auth(self, username: &str, password: &str) -> Self

Configure proxy authentication credentials (RFC 3507 §7.1).

When the ICAP server responds with 407 Proxy Authentication Required, the client retries the request exactly once with a Proxy-Authorization: Basic <base64(username:password)> header.

If the retry also yields a 407 (wrong credentials), the error response is returned to the caller as-is.

Examples

use icap_rs::Client;

let client = Client::builder()
    .host("proxy.example.com")
    .proxy_auth("alice", "hunter2")
    .build();

pub fn with_uri(self, uri: &str) -> IcapResult<Self>

Configure the builder from an ICAP URI (icap://... or icaps://...).

This extracts host and port for use in the TCP connection. The service path, if present in the URI, is ignored here and should be set on the request itself. icaps:// implicitly enables TLS using ClientTlsConfig::with_native_roots; call with_tls before or after with_uri to override the default TLS configuration.

The default port is 1344 for icap:// and 11344 for icaps://.

pub fn try_build(self) -> IcapResult<Client>

Build a Client, returning an error when required configuration is missing.

Errors

Returns an error if host was not set via ClientBuilder::host or ClientBuilder::with_uri.

pub fn build(self) -> Client

Build a Client, defaulting host to "127.0.0.1" when unset.

Use ClientBuilder::try_build when missing configuration should be reported as an error instead of being silently defaulted.

Trait Implementations

impl Debug for ClientBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ClientBuilder

fn default() -> ClientBuilder

Returns the “default value” for a type.