Struct Config

pub struct Config { /* private fields */ }

Available on crate feature dep_ureq only.

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

impl Config

pub fn builder() -> ConfigBuilder<AgentScope>

A builder to make a bespoke configuration.

The default values are already set.

pub fn new_agent(&self) -> Agent

Creates a new agent by cloning this config.

Cloning the config does not incur heap allocations.

impl Config

pub fn http_status_as_error(&self) -> bool

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

Defaults to true.

pub fn https_only(&self) -> bool

Whether to limit requests (including redirects) to https only

Defaults to false.

pub fn ip_family(&self) -> IpFamily

Configuration of IPv4/IPv6.

This affects the resolver.

Defaults to IpFamily::Any.

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

Proxy configuration.

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

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.

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

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

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.

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.

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>

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 */*

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.

pub fn timeouts(&self) -> Timeouts

All configured timeouts.

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.

pub fn input_buffer_size(&self) -> usize

Default size of the input buffer

The default connectors use this setting.

Defaults to 128kb.

pub fn output_buffer_size(&self) -> usize

Default size of the output buffer.

The default connectors use this setting.

Defaults to 128kb.

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

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

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

pub fn allow_non_standard_methods(&self) -> bool

Whether to allow non-standard HTTP methods.

By default the methods are limited by the HTTP version.

Defaults to false

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Config

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

Formats the value using the given formatter.

impl Default for Config

fn default() -> Config

Returns the “default value” for a type.

impl From<Config> for Agent

fn from(value: Config) -> Agent

Converts to this type from the input type.