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);
pub fn builder(method: Method, url: Url) -> RequestBuilderⓘNotable traits for RequestBuilderimpl Future for RequestBuilder type Output = Result<Response>;
pub fn builder(method: Method, url: Url) -> RequestBuilderⓘNotable traits for RequestBuilderimpl Future for RequestBuilder type Output = Result<Response>;
impl Future for RequestBuilder type Output = Result<Response>;
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.
pub fn insert_header(
&mut self,
name: impl Into<HeaderName>,
values: impl ToHeaderValues
) -> Option<HeaderValues>
pub fn insert_header(
&mut self,
name: impl Into<HeaderName>,
values: impl ToHeaderValues
) -> Option<HeaderValues>
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, 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");
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.
Panics
This method will panic if an invalid MIME type was set as a header. Use the set_header
method to bypass any checks.
Set the request content type from a Mime
.
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.
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 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.
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
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
.
type Output = HeaderValues
type Output = HeaderValues
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
.
type Output = HeaderValues
type Output = HeaderValues
The returned type after indexing.
type Item = (HeaderName, HeaderValues)
type Item = (HeaderName, HeaderValues)
The type of the elements being iterated over.
Auto Trait Implementations
impl !RefUnwindSafe for Request
impl !UnwindSafe for Request
Blanket Implementations
Mutably borrows from an owned value. Read more
Instruments this type with the provided Span
, returning an
Instrumented
wrapper. Read more
pub fn vzip(self) -> V
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
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