Struct Config

Source

pub struct Config { /* private fields */ }

Expand description

Config primarily for the Agent, but also per-request.

Config objects are cheap to clone and should not incur any heap allocations.

§Agent level config

§Example

use ureq::Agent;
use std::time::Duration;

let config = Agent::config_builder()
    .timeout_global(Some(Duration::from_secs(10)))
    .https_only(true)
    .build();

let agent = Agent::new_with_config(config);

§Request level config

The config can also be change per-request. Since every request ultimately executes using an Agent (also the root-level ureq::get(...) have an implicit agent), a request level config clones the agent level config.

There are two ways of getting a request level config.

§Request builder example

The first way is via RequestBuilder::config().

use ureq::Agent;

let agent: Agent = Agent::config_builder()
    .https_only(false)
    .build()
    .into();

let response = agent.get("http://httpbin.org/get")
    .config()
    // override agent level setting for this request
    .https_only(true)
    .build()
    .call();

§HTTP request example

The second way is via Agent::configure_request(). This is used when working with the http crate http::Request type directly.

use ureq::{http, Agent};

let agent: Agent = Agent::config_builder()
    .https_only(false)
    .build()
    .into();

let request = http::Request::get("http://httpbin.org/get")
    .body(()).unwrap();

let request = agent.configure_request(request)
    // override agent level setting for this request
    .https_only(true)
    .build();

let response = agent.run(request);

Implementations§

Source §

impl Config

Source

pub fn builder() -> ConfigBuilder<AgentScope>

A builder to make a bespoke configuration.

The default values are already set.

Source

pub fn new_agent(&self) -> Agent

Creates a new agent by cloning this config.

Cloning the config does not incur heap allocations.

Source §

impl Config

Source

pub fn http_status_as_error(&self) -> bool

Whether to treat 4xx and 5xx HTTP status codes as Err(Error::StatusCode)).

Defaults to true.

Source

pub fn https_only(&self) -> bool

Whether to limit requests (including redirects) to https only

Defaults to false.

Source

pub fn ip_family(&self) -> IpFamily

Configuration of IPv4/IPv6.

This affects the resolver.

Defaults to IpFamily::Any.

Source

pub fn tls_config(&self) -> &TlsConfig

Config for TLS.

This config is generic for all TLS connectors.

Source

pub fn proxy(&self) -> Option<&Proxy>

Proxy configuration.

Picked up from environment when using Config::default() or

Source

pub fn no_delay(&self) -> bool

Disable Nagle’s algorithm

Set TCP_NODELAY. It’s up to the transport whether this flag is honored.

Defaults to true.

Source

pub fn max_redirects(&self) -> u32

The max number of redirects to follow before giving up.

Whe max redirects are reached, the behavior is controlled by the max_redirects_will_error setting. Set to true (which is the default) the result is a TooManyRedirects error. Set to false, the response is returned as is.

If max_redirects is 0, no redirects are followed and the response is always returned (never a TooManyRedirects error).

Defaults to 10

Source

pub fn max_redirects_will_error(&self) -> bool

If we should error when max redirects are reached.

This has no meaning if max_redirects is 0.

Defaults to true

Source

pub fn redirect_auth_headers(&self) -> RedirectAuthHeaders

How to handle Authorization headers when following redirects

Never (the default) means the authorization header is never attached to a redirected call.
SameHost will keep the header when the redirect is to the same host and under https.

Defaults to None.

Source

pub fn save_redirect_history(&self) -> bool

If we should record a history of every redirect location, including the request and final locations.

Comes at the cost of allocating/retaining the Uri for every redirect loop.

See ResponseExt::get_redirect_history().

Defaults to false.

Source

pub fn user_agent(&self) -> &AutoHeaderValue

Value to use for the User-Agent header.

This can be overridden by setting a user-agent header on the request object. The one difference is that a connection to a HTTP proxy server will receive this value, not the request-level one.

Setting a value of "" on the request or agent level will also not send a header.

Defaults to Default, which results in ureq/<version>

Source

pub fn accept(&self) -> &AutoHeaderValue

Value to use for the Accept header.

This agent configured value can be overriden per request by setting the header. Setting a value of "" on the request or agent level will also not send a header.

Defaults to Default, which results in */*

Source

pub fn accept_encoding(&self) -> &AutoHeaderValue

Value to use for the Accept-Encoding header.

Defaults to Default, which will add gz and brotli depending on the feature flags gzip and brotli respectively. If neither feature is enabled, the header is not added.

This agent configured value can be overriden per request by setting the header.

Setting a value of "" on the request or agent level will also not send a header.

This communicates capability to the server, however the triggering the automatic decompression behavior is not affected since that only looks at the Content-Encoding response header.

Source

pub fn timeouts(&self) -> Timeouts

All configured timeouts.

Source

pub fn max_response_header_size(&self) -> usize

Max size of the HTTP response header.

From the status, including all headers up until the body.

Defaults to 64kb.

Source

pub fn input_buffer_size(&self) -> usize

Default size of the input buffer

The default connectors use this setting.

Defaults to 128kb.

Source

pub fn output_buffer_size(&self) -> usize

Default size of the output buffer.

The default connectors use this setting.

Defaults to 128kb.

Source

pub fn max_idle_connections(&self) -> usize

Max number of idle pooled connections overall.

This setting has no effect when used per-request.

Defaults to 10

Source

pub fn max_idle_connections_per_host(&self) -> usize

Max number of idle pooled connections per host/port combo.

This setting has no effect when used per-request.

Defaults to 3

Source

pub fn max_idle_age(&self) -> Duration

Max duration to keep an idle connection in the pool

This can also be configured per-request to be shorter than the pool. For example: if the pool is configured to 15 seconds and we have a connection with an age of 10 seconds, a request setting this config property to 3 seconds, would ignore the pooled connection (but still leave it in the pool).

Defaults to 15 seconds

Source