Struct Config

#[non_exhaustive]
pub struct Config {
    pub base_url: Option<Url>,
    pub headers: HashMap<HeaderName, HeaderValues>,
    pub http_config: Config,
    pub http_client: Option<Arc<dyn HttpClient>>,
}

Configuration for surf::Clients and their underlying HTTP clients.

use std::convert::TryInto;
use surf::{Client, Config, Url};

let client: Client = Config::new()
    .set_base_url(Url::parse("https://example.org")?)
    .try_into()?;

let mut response = client.get("/").await?;

println!("{}", response.body_string().await?);

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

base_url: Option<Url>

The base URL for a client. All request URLs will be relative to this URL.

Note: a trailing slash is significant. Without it, the last path component is considered to be a “file” name to be removed to get at the “directory” that is used as the base.

headers: HashMap<HeaderName, HeaderValues>

Headers to be applied to every request made by this client.

http_config: Config

Underlying HTTP client config.

http_client: Option<Arc<dyn HttpClient>>

Optional custom http client.

Implementations

impl Config

pub fn new() -> Self

Construct new empty config.

impl Config

pub fn add_header( self, name: impl Into<HeaderName>, values: impl ToHeaderValues, ) -> Result<Self>

Adds a header to be added to every request by this client.

Default: No extra headers.

use std::convert::TryInto;
use surf::{Client, Config};
use surf::http::auth::BasicAuth;

let auth = BasicAuth::new("Username", "Password");

let client: Client = Config::new()
    .add_header(auth.name(), auth.value())?
    .try_into()?;

pub fn set_base_url(self, base: Url) -> Self

Sets the base URL for this client. All request URLs will be relative to this URL.

Note: a trailing slash is significant. Without it, the last path component is considered to be a “file” name to be removed to get at the “directory” that is used as the base.

Default: None (internally).

use std::convert::TryInto;
use surf::{Client, Config, Url};

let client: Client = Config::new()
    .set_base_url(Url::parse("https://example.org")?)
    .try_into()?;

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

Set HTTP/1.1 keep-alive (connection pooling).

Default: true.

Note: Does nothing on wasm-client (or native-client on wasm32).

pub fn set_tcp_no_delay(self, no_delay: bool) -> Self

Set TCP NO_DELAY.

Default: false.

Note: Does nothing on wasm-client (or native-client on wasm32).

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

Set connection timeout duration.

Passing None will remove the timeout.

Default: Some(Duration::from_secs(60)).

use std::convert::TryInto;
use std::time::Duration;
use surf::{Client, Config};

let client: Client = Config::new()
    .set_timeout(Some(Duration::from_secs(5)))
    .try_into()?;

pub fn set_max_connections_per_host( self, max_connections_per_host: usize, ) -> Self

Set the maximum number of simultaneous connections that this client is allowed to keep open to individual hosts at one time.

Default: 50. This number is based on a few random benchmarks and see whatever gave decent perf vs resource use in Orogene.

Note: The behavior of this is different depending on the backend in use.

• h1-client: 0 is disallowed and asserts as otherwise it would cause a semaphore deadlock.
• curl-client: 0 allows for limitless connections per host.
• hyper-client: No effect. Hyper does not support such an option.
• wasm-client: No effect. Web browsers do not support such an option.

pub fn set_http_client(self, http_client: impl HttpClient) -> Self

Override the http client entirely.

When using this, any underlying http_client::Config http configuration will be ignored.

use std::convert::TryInto;
use surf::{Client, Config};

// Connect directly to a Tide server, e.g. for testing.
let server = tide::new();

let client: Client = Config::new()
    .set_http_client(server)
    .try_into()?;

Trait Implementations

impl AsRef<Config> for Config

fn as_ref(&self) -> &HttpConfig

Converts this type into a shared reference of the (usually inferred) input type.

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

Formats the value using the given formatter.

impl Default for Config

fn default() -> Self

Returns the “default value” for a type.

impl From<Config> for Config

fn from(http_config: HttpConfig) -> Self

Converts to this type from the input type.

impl TryFrom<Config> for Client

type Error = <IsahcClient as TryFrom<Config>>::Error

The type returned in the event of a conversion error.

fn try_from(config: Config) -> Result<Self, Self::Error>

Performs the conversion.