Struct surf::Client

pub struct Client { /* fields omitted */ }

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

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 instance.

Examples

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

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

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

Examples

let client = surf::Client::with_http_client(Arc::new(H1Client::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 fn send(
    &self,
    req: impl Into<Request>
) -> BoxFuture<'static, Result<Response>>

Send a Request using this client.

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 the 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 the 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 the 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 the 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 set_base_url(&mut self, base: Url)

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

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

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 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.