Struct Config

source

pub struct Config {Show 17 fields
    pub http_status_as_error: bool,
    pub https_only: bool,
    pub ip_family: IpFamily,
    pub tls_config: TlsConfig,
    pub proxy: Option<Proxy>,
    pub no_delay: bool,
    pub max_redirects: u32,
    pub redirect_auth_headers: RedirectAuthHeaders,
    pub user_agent: Option<String>,
    pub timeouts: Timeouts,
    pub max_response_header_size: usize,
    pub input_buffer_size: usize,
    pub output_buffer_size: usize,
    pub max_idle_connections: usize,
    pub max_idle_connections_per_host: usize,
    pub max_idle_age: Duration,
    pub middleware: MiddlewareChain,
    /* 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

When creating config instances, the prefered way is to use the ..Default::default() pattern.

§Example

use ureq::{Agent, Config, Timeouts};
use std::time::Duration;

let config = Config {
    timeouts: Timeouts {
        global: Some(Duration::from_secs(10)),
        ..Default::default()
    },
    https_only: true,
    ..Default::default()
};

let agent = Agent::new_with_config(config);

And alternative way is to set properties on an already created config

use ureq::{Agent, Config};
use std::time::Duration;

let mut config = Config::new();
config.timeouts.global = Some(Duration::from_secs(10));
config.https_only = true;

let agent: Agent = config.into();

§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, Config};

let agent: Agent = Config {
    https_only: false,
    ..Default::default()
}.into();

let mut builder = agent.get("http://httpbin.org/get");

let config = builder.config();
config.https_only = true;

§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::{Agent, Config};

let agent: Agent = Config {
    https_only: false,
    ..Default::default()
}.into();

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

let config = agent.configure_request(&mut request);
config.https_only = true;

§Correct usage

Note: For a struct with pub fields, Rust dosn’t have a way to force the use of ..Default::default(). Config must be instantiated in one two ways:

Config::default() or Config::new().
Config { <override defaults>, ..Default::default() }

Any other way to construct the config is not valid, and breaking changes arising from doing that are not considered breaking. Specifically it is not correct to use Config { ... } without a ..Default::default().

Fields§

§http_status_as_error: bool

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

Defaults to true.

§https_only: bool

Whether to limit requests (including redirects) to https only

Defaults to false.

§ip_family: IpFamily

Configuration of IPv4/IPv6.

This affects the resolver.

Defaults to IpFamily::Any.

§tls_config: TlsConfig

Config for TLS.

This config is generic for all TLS connectors.

§proxy: Option<Proxy>

Proxy configuration.

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

§no_delay: bool

Disable Nagle’s algorithm

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

Defaults to true.

§max_redirects: u32

The max number of redirects to follow before giving up

Defaults to 10

§redirect_auth_headers: 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.

§user_agent: Option<String>

Value to use for the User-Agent field.

None means the default value which is ureq/<version>.

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.

Defaults to ureq/<version>

§timeouts: Timeouts

The timeout settings on agent level.

This can be overridden per request.

§max_response_header_size: usize

Max size of the HTTP response header.

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

Defaults to 64kb.

§input_buffer_size: usize

Default size of the input buffer

The default connectors use this setting.

Defaults to 128kb.

§output_buffer_size: usize

Default size of the output buffer.

The default connectors use this setting.

Defaults to 128kb.

§max_idle_connections: usize

Max number of idle pooled connections overall.

This setting has no effect when used per-request.

Defaults to 10

§max_idle_connections_per_host: usize

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

This setting has no effect when used per-request.

Defaults to 3

§max_idle_age: 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

§middleware: MiddlewareChain

Middleware used for this agent.

Defaults to no middleware.

Struct ConfigCopy item path

§Agent level config

§Example

§Request level config

§Request builder example

§HTTP request example

§Correct usage

Fields§

Implementations§

impl Config

pub fn new() -> Self

impl Config

pub fn new_agent(&self) -> Agent

Trait Implementations§

impl Clone for Config

fn clone(&self) -> Config

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

impl Debug for Config

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

impl Default for Config

fn default() -> Self

impl From<Config> for Agent

fn from(value: Config) -> Self

Auto Trait Implementations§

impl Freeze for Config

impl !RefUnwindSafe for Config

impl Send for Config

impl Sync for Config

impl Unpin for Config

impl !UnwindSafe for Config

Blanket Implementations§

impl<T> Any for Twhere T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Twhere T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Twhere T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> CloneToUninit for Twhere T: Clone,

unsafe fn clone_to_uninit(&self, dst: *mut T)

impl<T> From<T> for T

fn from(t: T) -> T

impl<T, U> Into<U> for Twhere U: From<T>,

fn into(self) -> U

impl<T> ToOwned for Twhere T: Clone,

type Owned = T

fn to_owned(&self) -> T

fn clone_into(&self, target: &mut T)

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

type Error = Infallible

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Struct Config

impl<T> Any for T
where T: 'static + ?Sized,

impl<T> Borrow<T> for T
where T: ?Sized,

impl<T> BorrowMut<T> for T
where T: ?Sized,

impl<T> CloneToUninit for T
where T: Clone,

impl<T, U> Into<U> for T
where U: From<T>,

impl<T> ToOwned for T
where T: Clone,

impl<T, U> TryFrom<U> for T
where U: Into<T>,

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,