Struct surf::Request[−][src]

pub struct Request { /* fields omitted */ }
Expand description

An HTTP request, returns a Response.

Implementations

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, Method};

let url = Url::parse("https://httpbin.org/get")?;
let req = surf::Request::new(Method::Get, url);

Begin a chained request builder. For more details, see RequestBuilder

Example:

use surf::http::{Method, mime::HTML, Url};
let url = Url::parse("https://httpbin.org/post")?;
let mut request = surf::Request::builder(Method::Post, url.clone())
    .body("<html>hi</html>")
    .header("custom-header", "value")
    .content_type(HTML)
    .build();

assert_eq!(request.take_body().into_string().await.unwrap(), "<html>hi</html>");
assert_eq!(request.method(), Method::Post);
assert_eq!(request.url(), &url);
assert_eq!(request["custom-header"], "value");
assert_eq!(request["content-type"], "text/html;charset=utf-8");

Get the URL querystring.

Examples

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

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

Set the URL querystring.

Examples

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

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

Get an HTTP header.

Examples

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

Get a mutable reference to a header.

Set an HTTP header.

Append a header to the headers.

Unlike insert this function will not override the contents of a header, but insert a header if there aren’t any. Or else append to the existing list of headers.

Remove a header.

An iterator visiting all header pairs in arbitrary order.

An iterator visiting all header pairs in arbitrary order, with mutable references to the values.

An iterator visiting all header names in arbitrary order.

An iterator visiting all header values in arbitrary order.

Set an HTTP header.

Examples

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

Get a request extension value.

Set a request extension value.

Get the request HTTP method.

Examples

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

Get the request url.

Examples

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

Get the request content type as a 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.

[src]

pub fn set_content_type(&mut self, mime: Mime)

Set the request content type from a Mime.

Read more on MDN

Get the length of the body stream, if it has been set.

This value is set when passing a fixed-size object into as the body. E.g. a string, or a buffer. Consumers of this API should check this value to decide whether to use Chunked encoding, or set the response length.

Returns true if the set length of the body stream is zero, false otherwise.

[src]

pub fn set_body(&mut self, body: impl Into<Body>)

Pass an AsyncRead stream as the request body.

Mime

The encoding is set to application/octet-stream.

[src]

pub fn take_body(&mut self) -> Body

Take the request body as a Body.

This method can be called after the body has already been taken or read, but will return an empty Body.

This is useful for consuming the body via an AsyncReader or AsyncBufReader.

Pass JSON as the request body.

Mime

The content-type is set to application/json.

Errors

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

Pass a string as the request body.

Mime

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

Pass bytes as the request body.

Mime

The content-type is set to application/octet-stream.

Pass a file as the request body.

Mime

The content-type 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.

Pass a form as the request body.

Mime

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

Errors

An error will be returned if the encoding failed.

Push middleware onto a per-request middleware stack.

Important: Setting per-request middleware incurs extra allocations. Creating a Client with middleware is recommended.

Client middleware is run before per-request middleware.

See the middleware submodule for more information on middleware.

Examples

let mut req = surf::get("https://httpbin.org/get").build();
req.middleware(surf::middleware::Redirect::default());

Trait Implementations

Performs the conversion.

Performs the conversion.

Performs the conversion.

Performs the conversion.

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

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

Converts a surf::RequestBuilder to a surf::Request.

Returns a reference to the value corresponding to the supplied name.

Panics

Panics if the name is not present in Request.

The returned type after indexing.

Returns a reference to the value corresponding to the supplied name.

Panics

Panics if the name is not present in Request.

The returned type after indexing.

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

Returns a iterator of references over the remaining items.

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Performs the conversion.

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more