Struct surf::Request

pub struct Request<C: HttpClient + Debug + Unpin + Send + Sync> { /* fields omitted */ }

An HTTP request, returns a Response.

Methods

impl Request<NativeClient>

pub fn new(method: Method, url: Url) -> Self

Create a new instance.

This method is particularly useful when input URLs might be passed by third parties, and you don't want to panic if they're malformed. If URLs are statically encoded, it might be easier to use one of the shorthand methods instead.

Examples

use surf::{http, url};

let method = http::Method::GET;
let url = url::Url::parse("https://httpbin.org/get")?;
let string = surf::Request::new(method, url).recv_string().await?;

impl<C: HttpClient> Request<C>

pub fn middleware(self, mw: impl Middleware<C>) -> Self

Push middleware onto the middleware stack.

See the middleware submodule for more information on middleware.

Examples

let res = surf::get("https://httpbin.org/get")
    .middleware(surf::middleware::logger::new())
    .await?;

pub fn query<T: DeserializeOwned>(&self) -> Result<T, Exception>

Get the URL querystring.

Examples

#[derive(Serialize, Deserialize)]
struct Index {
    page: u32
}

let req = surf::get("https://httpbin.org/get?page=2");
let Index { page } = req.query()?;
assert_eq!(page, 2);

pub fn set_query(self, query: &impl Serialize) -> Result<Self, Error>

Set the URL querystring.

Examples

#[derive(Serialize, Deserialize)]
struct Index {
    page: u32
}

let query = Index { page: 2 };
let req = surf::get("https://httpbin.org/get").set_query(&query)?;
assert_eq!(req.url().query(), Some("page=2"));

pub fn header(&self, key: &'static str) -> Option<&str>

Get an HTTP header.

Examples

let req = surf::get("https://httpbin.org/get")
    .set_header("X-Requested-With", "surf");
assert_eq!(req.header("X-Requested-With"), Some("surf"));

pub fn set_header(self, key: &'static str, value: impl AsRef<str>) -> Self

Set an HTTP header.

Examples

let req = surf::get("https://httpbin.org/get")
    .set_header("X-Requested-With", "surf");
assert_eq!(req.header("X-Requested-With"), Some("surf"));

pub fn headers<'a>(&'a mut self) -> Headers<'a>

Get all headers.

Examples

let mut req = surf::get("https://httpbin.org/get")
    .set_header("X-Requested-With", "surf");

for (name, value) in req.headers() {
    println!("{}: {}", name, value);
}

pub fn method(&self) -> &Method

Get the request HTTP method.

Examples

use surf::http;
let req = surf::get("https://httpbin.org/get");
assert_eq!(req.method(), http::Method::GET);

pub fn url(&self) -> &Url

Get the request url.

Examples

use surf::url::Url;
let req = surf::get("https://httpbin.org/get");
assert_eq!(req.url(), &Url::parse("https://httpbin.org/get")?);

pub fn mime(&self) -> Option<Mime>

Get the request MIME.

Gets the Content-Type header and parses it to a Mime type.

Read more on MDN

Panics

This method will panic if an invalid MIME type was set as a header. Use the set_header method to bypass any checks.

Examples

use surf::mime;
let req = surf::post("https://httpbin.org/get")
    .set_mime(mime::TEXT_CSS);
assert_eq!(req.mime(), Some(mime::TEXT_CSS));

pub fn set_mime(self, mime: Mime) -> Self

Set the request MIME.

Read more on MDN

Examples

use surf::mime;
let req = surf::post("https://httpbin.org/get")
    .set_mime(mime::TEXT_CSS);
assert_eq!(req.mime(), Some(mime::TEXT_CSS));

pub fn body<R>(self, reader: R) -> Self where
    R: AsyncRead + Unpin + Send + 'static, 

Pass an AsyncRead stream as the request body.

Mime

The encoding is set to application/octet-stream.

Examples

let reader = surf::get("https://httpbin.org/get").await?;
let uri = "https://httpbin.org/post";
let res = surf::post(uri).body(reader).await?;
assert_eq!(res.status(), 200);

pub fn body_json(self, json: &impl Serialize) -> Result<Self>

Pass JSON as the request body.

Mime

The encoding is set to application/json.

Errors

This method will return an error if the provided data could not be serialized to JSON.

Examples

let uri = "https://httpbin.org/post";
let data = serde_json::json!({ "name": "chashu" });
let res = surf::post(uri).body_json(&data)?.await?;
assert_eq!(res.status(), 200);

pub fn body_string(self, string: String) -> Self

Pass a string as the request body.

Mime

The encoding is set to text/plain; charset=utf-8.

Examples

let uri = "https://httpbin.org/post";
let data = "hello world".to_string();
let res = surf::post(uri).body_string(data).await?;
assert_eq!(res.status(), 200);

pub fn body_bytes(self, bytes: impl AsRef<[u8]>) -> Self

Pass bytes as the request body.

Mime

The encoding is set to application/octet-stream.

Examples

let uri = "https://httpbin.org/post";
let data = b"hello world";
let res = surf::post(uri).body_bytes(data).await?;
assert_eq!(res.status(), 200);

pub fn body_file(self, path: impl AsRef<Path>) -> Result<Self>

Pass a file as the request body.

Mime

The encoding is set based on the file extension using mime_guess if the operation was successful. If path has no extension, or its extension has no known MIME type mapping, then None is returned.

Errors

This method will return an error if the file couldn't be read.

Examples

let res = surf::post("https://httpbin.org/post")
    .body_file("README.md")?
    .await?;
assert_eq!(res.status(), 200);

pub fn body_form(self, form: &impl Serialize) -> Result<Self, Error>

Pass a form as the request body.

Mime

The encoding is set to application/x-www-form-urlencoded.

Errors

An error will be returned if the encoding failed.

Examples

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

let res = surf::post("https://httpbin.org/post")
    .body_form(&Body { apples: 7 })?
    .await?;
assert_eq!(res.status(), 200);

pub async fn recv_bytes(self) -> Result<Vec<u8>, Exception>

Submit the request and get the response body as bytes.

Examples

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

pub async fn recv_string(self) -> Result<String, Exception>

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

Examples

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

pub async fn recv_json<T: DeserializeOwned>(self) -> Result<T, Exception>

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

Examples

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

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

pub async fn recv_form<T: DeserializeOwned>(self) -> Result<T, Exception>

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 url = "https://api.example.com/v1/response";
let Body { apples } = surf::get(url).recv_form().await?;

Trait Implementations

impl<C: HttpClient> Into<Request<Body>> for Request<C>

fn into(self) -> Request<Body>

Converts a surf::Request to an http::Request.

impl<C: HttpClient> Debug for Request<C>

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

Formats the value using the given formatter.

impl<R: AsyncRead + Unpin + Send + 'static> TryFrom<Request<Box<R>>> for Request<NativeClient>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(http_request: Request<Box<R>>) -> Result<Self>

Converts an http::Request to a surf::Request.

impl<C: HttpClient> Future for Request<C>

type Output = Result<Response, Exception>

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Self::Output>

Attempt to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.