Struct ajars_surf::surf::Request
source · [−]pub struct Request { /* private fields */ }
Expand description
An HTTP request, returns a Response
.
Implementations
sourceimpl Request
impl Request
sourcepub fn new(method: Method, url: Url) -> Request
pub fn new(method: Method, url: Url) -> Request
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);
sourcepub fn builder(method: Method, url: Url) -> RequestBuilderⓘNotable traits for RequestBuilderimpl Future for RequestBuilder type Output = Result<Response, Error>;
pub fn builder(method: Method, url: Url) -> RequestBuilderⓘNotable traits for RequestBuilderimpl Future for RequestBuilder type Output = Result<Response, Error>;
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");
sourcepub fn query<T>(&self) -> Result<T, Error> where
T: DeserializeOwned,
pub fn query<T>(&self) -> Result<T, Error> where
T: DeserializeOwned,
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);
sourcepub fn set_query(&mut self, query: &impl Serialize) -> Result<(), Error>
pub fn set_query(&mut self, query: &impl Serialize) -> Result<(), Error>
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");
sourcepub fn header(&self, key: impl Into<HeaderName>) -> Option<&HeaderValues>
pub fn header(&self, key: impl Into<HeaderName>) -> Option<&HeaderValues>
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");
sourcepub fn header_mut(
&mut self,
name: impl Into<HeaderName>
) -> Option<&mut HeaderValues>
pub fn header_mut(
&mut self,
name: impl Into<HeaderName>
) -> Option<&mut HeaderValues>
Get a mutable reference to a header.
sourcepub 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.
sourcepub fn append_header(
&mut self,
name: impl Into<HeaderName>,
values: impl ToHeaderValues
)
pub fn append_header(
&mut self,
name: impl Into<HeaderName>,
values: impl ToHeaderValues
)
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.
sourcepub fn remove_header(
&mut self,
name: impl Into<HeaderName>
) -> Option<HeaderValues>
pub fn remove_header(
&mut self,
name: impl Into<HeaderName>
) -> Option<HeaderValues>
Remove a header.
sourcepub fn iter(&self) -> Iter<'_>ⓘNotable traits for Iter<'a>impl<'a> Iterator for Iter<'a> type Item = (&'a HeaderName, &'a HeaderValues);
pub fn iter(&self) -> Iter<'_>ⓘNotable traits for Iter<'a>impl<'a> Iterator for Iter<'a> type Item = (&'a HeaderName, &'a HeaderValues);
An iterator visiting all header pairs in arbitrary order.
sourcepub fn iter_mut(&mut self) -> IterMut<'_>ⓘNotable traits for IterMut<'a>impl<'a> Iterator for IterMut<'a> type Item = (&'a HeaderName, &'a mut HeaderValues);
pub fn iter_mut(&mut self) -> IterMut<'_>ⓘNotable traits for IterMut<'a>impl<'a> Iterator for IterMut<'a> type Item = (&'a HeaderName, &'a mut HeaderValues);
An iterator visiting all header pairs in arbitrary order, with mutable references to the values.
sourcepub fn header_names(&self) -> Names<'_>ⓘNotable traits for Names<'a>impl<'a> Iterator for Names<'a> type Item = &'a HeaderName;
pub fn header_names(&self) -> Names<'_>ⓘNotable traits for Names<'a>impl<'a> Iterator for Names<'a> type Item = &'a HeaderName;
An iterator visiting all header names in arbitrary order.
sourcepub fn header_values(&self) -> Values<'_>ⓘNotable traits for Values<'a>impl<'a> Iterator for Values<'a> type Item = &'a HeaderValue;
pub fn header_values(&self) -> Values<'_>ⓘNotable traits for Values<'a>impl<'a> Iterator for Values<'a> type Item = &'a HeaderValue;
An iterator visiting all header values in arbitrary order.
sourcepub fn set_header(
&mut self,
key: impl Into<HeaderName>,
value: impl ToHeaderValues
)
pub fn set_header(
&mut self,
key: impl Into<HeaderName>,
value: impl ToHeaderValues
)
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");
sourcepub fn ext<T>(&self) -> Option<&T> where
T: 'static + Send + Sync,
pub fn ext<T>(&self) -> Option<&T> where
T: 'static + Send + Sync,
Get a request extension value.
sourcepub fn set_ext<T>(&mut self, val: T) -> Option<T> where
T: 'static + Send + Sync,
pub fn set_ext<T>(&mut self, val: T) -> Option<T> where
T: 'static + Send + Sync,
Set a request extension value.
sourcepub fn method(&self) -> Method
pub fn method(&self) -> Method
Get the request HTTP method.
Examples
let req = surf::get("https://httpbin.org/get").build();
assert_eq!(req.method(), surf::http::Method::Get);
sourcepub fn url(&self) -> &Url
pub fn url(&self) -> &Url
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")?);
sourcepub fn content_type(&self) -> Option<Mime>
pub fn content_type(&self) -> Option<Mime>
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.
sourcepub fn set_content_type(&mut self, mime: Mime)
pub fn set_content_type(&mut self, mime: Mime)
Set the request content type from a Mime
.
sourcepub fn len(&self) -> Option<usize>
pub fn len(&self) -> Option<usize>
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.
sourcepub fn is_empty(&self) -> Option<bool>
pub fn is_empty(&self) -> Option<bool>
Returns true
if the set length of the body stream is zero, false
otherwise.
sourcepub fn take_body(&mut self) -> Body
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.
sourcepub fn body_string(&mut self, string: String)
pub fn body_string(&mut self, string: String)
sourcepub async fn body_file(
&'_ mut self,
path: impl AsRef<Path>
) -> Result<(), Error>
pub async fn body_file(
&'_ mut self,
path: impl AsRef<Path>
) -> Result<(), Error>
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.
sourcepub fn middleware(&mut self, middleware: impl Middleware)
pub fn middleware(&mut self, middleware: impl Middleware)
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
sourceimpl From<RequestBuilder> for Request
impl From<RequestBuilder> for Request
sourcefn from(builder: RequestBuilder) -> Request
fn from(builder: RequestBuilder) -> Request
Converts a surf::RequestBuilder
to a surf::Request
.
sourceimpl<'_> Index<&'_ str> for Request
impl<'_> Index<&'_ str> for Request
sourcefn index(&self, name: &str) -> &HeaderValues
fn index(&self, name: &str) -> &HeaderValues
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.
sourceimpl Index<HeaderName> for Request
impl Index<HeaderName> for Request
sourcefn index(&self, name: HeaderName) -> &HeaderValues
fn index(&self, name: HeaderName) -> &HeaderValues
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.
sourceimpl IntoIterator for Request
impl IntoIterator for Request
sourcefn into_iter(self) -> <Request as IntoIterator>::IntoIter
fn into_iter(self) -> <Request as IntoIterator>::IntoIter
Returns a iterator of references over the remaining items.
type Item = (HeaderName, HeaderValues)
type Item = (HeaderName, HeaderValues)
The type of the elements being iterated over.
sourceimpl<'a> IntoIterator for &'a Request
impl<'a> IntoIterator for &'a Request
type Item = (&'a HeaderName, &'a HeaderValues)
type Item = (&'a HeaderName, &'a HeaderValues)
The type of the elements being iterated over.
sourceimpl<'a> IntoIterator for &'a mut Request
impl<'a> IntoIterator for &'a mut Request
type Item = (&'a HeaderName, &'a mut HeaderValues)
type Item = (&'a HeaderName, &'a mut HeaderValues)
The type of the elements being iterated over.
Auto Trait Implementations
impl !RefUnwindSafe for Request
impl Send for Request
impl Sync for Request
impl Unpin for Request
impl !UnwindSafe for Request
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more