Struct ClientBuilder 

pub struct ClientBuilder { /* private fields */ }

How a Client is put together: credentials, the HTTP client, the retry budget, the cache and the hooks, each with a default a caller can move.

Implementations

impl ClientBuilder

pub fn new(config: Config) -> ClientBuilder

A builder for config, at the defaults and without credentials.

pub fn token_provider( self, provider: impl TokenProvider + 'static, ) -> ClientBuilder

Authenticates with a bearer token drawn from provider for each request.

pub fn auth_strategy( self, strategy: impl AuthStrategy + 'static, ) -> ClientBuilder

Authenticates however strategy does: the way in for anything but a bearer token.

pub fn http_client(self, http: impl HttpClient + 'static) -> ClientBuilder

Replaces the HTTP client every request goes out on, including the attachment bytes that go to the storage service. The one supplied must not follow redirects; see HttpClient. The timeout set on the builder is then ignored — a timeout belongs to the client that can enforce it.

pub fn user_agent(self, user_agent: impl Into<String>) -> ClientBuilder

What the client calls itself in User-Agent.

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

How long the HTTP client the SDK ships gives an answer to arrive. It has no effect on one supplied with ClientBuilder::http_client. This bounds one request on the wire; the whole of an operation is bounded by ClientBuilder::operation_timeout.

pub fn operation_timeout(self, limit: Duration) -> ClientBuilder

The most an operation may take from the call to its answer, everything the client waits for included: waiting at the gate, fetching credentials, every attempt, every wait between them, the resend after a refresh, and reading the body. Past it the operation ends as a retryable network error, and whatever it was doing is dropped — a permit it held goes back, and the hooks hear it end. Decoding the answer into the caller’s type comes after, on the caller’s own thread, and is not waited for. None by default: an operation may then take as long as its attempts and waits add up to, each attempt bounded only by the HTTP client’s own ClientBuilder::timeout.

pub fn max_retries(self, max_retries: u32) -> ClientBuilder

The most times any operation is resent after a transient failure. A modelled route is resent as many times as its own policy allows and no more; this only lowers that. A path the caller wrote, which no policy covers, is resent this many times when its method is idempotent.

pub fn base_delay(self, base_delay: Duration) -> ClientBuilder

The least the client waits before the first resend. A modelled route starts from the delay its own policy names when that is longer; a path the caller wrote starts from this, or from DEFAULT_BASE_DELAY when it is not set. Each wait after the first is double the one before. ClientBuilder::max_delay holds every wait down, this one included.

pub fn max_delay(self, max_delay: Duration) -> ClientBuilder

The most the client waits between attempts, jitter included, whatever the policy, the backoff or ClientBuilder::base_delay asks for. The wait a Retry-After names is honoured as given.

pub fn max_jitter(self, max_jitter: Duration) -> ClientBuilder

The most added at random to each wait, so resends from many clients do not land together.

pub fn max_pages(self, max_pages: usize) -> ClientBuilder

How many pages Client::each_page reads before it stops. Zero is refused by ClientBuilder::build.

pub fn max_response_body_bytes(self, bytes: usize) -> ClientBuilder

The most a JSON or HTML answer may deliver before the client refuses to hold it. Zero asks for the default: the cap cannot be lifted, only moved.

pub fn cache(self, cache: impl ResponseCache + 'static) -> ClientBuilder

Caches JSON reads by ETag. Without this, config.cache_enabled decides whether a FileCache in config.cache_dir is used.

pub fn hooks(self, hooks: impl Hooks + 'static) -> ClientBuilder

Reports every operation and every request the client makes. Several sets of hooks go on as one with crate::observability::ChainHooks.

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

The client, or a usage error for a builder without credentials, with no timeout, or with no pages to read.

impl ClientBuilder

pub fn resilience(self, config: ResilienceConfig) -> ClientBuilder

Installs the layers the config asks for, keeping whatever hooks the builder already carries: they still hear about every operation and request.

pub fn circuit_breaker(self, config: CircuitBreakerConfig) -> ClientBuilder

Installs the circuit breaker alone.

pub fn bulkhead(self, config: BulkheadConfig) -> ClientBuilder

Installs the bulkhead alone.

pub fn rate_limit(self, config: RateLimitConfig) -> ClientBuilder

Installs the rate limiter alone.