Struct Client

pub struct Client { /* private fields */ }

An HTTP client, capable of sending Requests and running a middleware stack.

Can be optionally set with a base url.

Examples

let client = surf::Client::new();
let res1 = client.recv_string(surf::get("https://httpbin.org/get"));
let res2 = client.recv_string(surf::get("https://httpbin.org/get"));
let (str1, str2) = futures_util::future::try_join(res1, res2).await?;

Implementations

impl Client

pub fn new() -> Self

Create a new Client instance.

Examples

let client = surf::Client::new();

let req = surf::get("https://httpbin.org/get");
let res = client.send(req).await?;

pub fn with_http_client<C: HttpClient>(http_client: C) -> Self

Create a new Client instance with an http_client::HttpClient backend.

Examples

use http_client::isahc::IsahcClient;
let client = surf::Client::with_http_client(IsahcClient::new());

pub fn with(self, middleware: impl Middleware) -> Self

Push middleware onto the middleware stack.

See the middleware submodule for more information on middleware.

Examples

let req = surf::get("https://httpbin.org/get");
let client = surf::client()
    .with(surf::middleware::Redirect::default());
let res = client.send(req).await?;

pub async fn send(&self, req: impl Into<Request>) -> Result<Response>

Send a Request using this client.

Client middleware is run before per-request middleware.

Examples

let req = surf::get("https://httpbin.org/get");
let client = surf::client();
let res = client.send(req).await?;

pub async fn recv_bytes(&self, req: impl Into<Request>) -> Result<Vec<u8>>

Submit a Request and get the response body as bytes.

Examples

let req = surf::get("https://httpbin.org/get");
let bytes = surf::client().recv_bytes(req).await?;
assert!(bytes.len() > 0);

pub async fn recv_string(&self, req: impl Into<Request>) -> Result<String>

Submit a Request and get the response body as a string.

Examples

let req = surf::get("https://httpbin.org/get");
let string = surf::client().recv_string(req).await?;
assert!(string.len() > 0);

pub async fn recv_json<T: DeserializeOwned>( &self, req: impl Into<Request>, ) -> Result<T>

Submit a Request and decode the response body from json into a struct.

Examples

#[derive(Deserialize, Serialize)]
struct Ip {
    ip: String
}

let req = surf::get("https://api.ipify.org?format=json");
let Ip { ip } = surf::client().recv_json(req).await?;
assert!(ip.len() > 10);

pub async fn recv_form<T: DeserializeOwned>( &self, req: impl Into<Request>, ) -> Result<T>

Submit a Request and decode the response body from form encoding into a struct.

Errors

Any I/O error encountered while reading the body is immediately returned as an Err.

If the body cannot be interpreted as valid json for the target type T, an Err is returned.

Examples

#[derive(Deserialize, Serialize)]
struct Body {
    apples: u32
}

let req = surf::get("https://api.example.com/v1/response");
let Body { apples } = surf::client().recv_form(req).await?;

pub fn get(&self, uri: impl AsRef<str>) -> RequestBuilder

Perform an HTTP GET request using the Client connection.

Panics

This will panic if a malformed URL is passed.

Errors

Returns errors from the middleware, http backend, and network sockets.

Examples

let client = surf::client();
let string = client.get("https://httpbin.org/get").recv_string().await?;

pub fn head(&self, uri: impl AsRef<str>) -> RequestBuilder

Perform an HTTP HEAD request using the Client connection.

Panics

This will panic if a malformed URL is passed.

Errors

Returns errors from the middleware, http backend, and network sockets.

Examples

let client = surf::client();
let string = client.head("https://httpbin.org/head").recv_string().await?;

pub fn post(&self, uri: impl AsRef<str>) -> RequestBuilder

Perform an HTTP POST request using the Client connection.

Panics

This will panic if a malformed URL is passed.

Errors

Returns errors from the middleware, http backend, and network sockets.

Examples

let client = surf::client();
let string = client.post("https://httpbin.org/post").recv_string().await?;

pub fn put(&self, uri: impl AsRef<str>) -> RequestBuilder

Perform an HTTP PUT request using the Client connection.

Panics

This will panic if a malformed URL is passed.

Errors

Returns errors from the middleware, http backend, and network sockets.

Examples

let client = surf::client();
let string = client.put("https://httpbin.org/put").recv_string().await?;

pub fn delete(&self, uri: impl AsRef<str>) -> RequestBuilder

Perform an HTTP DELETE request using the Client connection.

Panics

This will panic if a malformed URL is passed.

Errors

Returns errors from the middleware, http backend, and network sockets.

Examples

let client = surf::client();
let string = client.delete("https://httpbin.org/delete").recv_string().await?;

pub fn connect(&self, uri: impl AsRef<str>) -> RequestBuilder

Perform an HTTP CONNECT request using the Client connection.

Panics

This will panic if a malformed URL is passed.

Errors

Returns errors from the middleware, http backend, and network sockets.

Examples

let client = surf::client();
let string = client.connect("https://httpbin.org/connect").recv_string().await?;

pub fn options(&self, uri: impl AsRef<str>) -> RequestBuilder

Perform an HTTP OPTIONS request using the Client connection.

Panics

This will panic if a malformed URL is passed.

Errors

Returns errors from the middleware, http backend, and network sockets.

Examples

let client = surf::client();
let string = client.options("https://httpbin.org/options").recv_string().await?;

pub fn trace(&self, uri: impl AsRef<str>) -> RequestBuilder

Perform an HTTP TRACE request using the Client connection.

Panics

This will panic if a malformed URL is passed.

Errors

Returns errors from the middleware, http backend, and network sockets.

Examples

let client = surf::client();
let string = client.trace("https://httpbin.org/trace").recv_string().await?;

pub fn patch(&self, uri: impl AsRef<str>) -> RequestBuilder

Perform an HTTP PATCH request using the Client connection.

Panics

This will panic if a malformed URL is passed.

Errors

Returns errors from the middleware, http backend, and network sockets.

Examples

let client = surf::client();
let string = client.patch("https://httpbin.org/patch").recv_string().await?;

pub fn request(&self, verb: Method, uri: impl AsRef<str>) -> RequestBuilder

Perform a HTTP request with the given verb using the Client connection.

Panics

This will panic if a malformed URL is passed.

Errors

Returns errors from the middleware, http backend, and network sockets.

Examples

use http_types::Method;
let client = surf::client();
let req = client.request(Method::Get, "http://httpbin.org/get");
let res = client.send(req).await?;

pub fn set_base_url(&mut self, base: Url)

👎Deprecated since 6.5.0: Please use Config instead

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.

Examples

let mut client = surf::client();
client.set_base_url(Url::parse("http://example.com/api/v1/")?);
client.get("posts.json").recv_json().await?; /// http://example.com/api/v1/posts.json

pub fn config(&self) -> &Config

Get the current configuration.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Self

Clones the Client.

This copies the middleware stack from the original, but shares the HttpClient and http client config of the original. Note that individual middleware in the middleware stack are still shared by reference.

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

Performs copy-assignment from source.

impl Debug for Client

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

Formats the value using the given formatter.

impl Default for Client

fn default() -> Self

Returns the “default value” for a 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.