[−][src]Struct surf::Request
An HTTP request, returns a Response
.
Implementations
impl Request
[src]
pub fn new(method: Method, url: Url) -> Self
[src]
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);
#[must_use]pub fn builder(method: Method, url: Url) -> RequestBuilderⓘNotable traits for RequestBuilder
impl Future for RequestBuilder type Output = Result<Response>;
[src]
Notable traits for RequestBuilder
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");
pub fn query<T: DeserializeOwned>(&self) -> Result<T>
[src]
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);
pub fn set_query(&mut self, query: &impl Serialize) -> Result<()>
[src]
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.as_ref().url().as_str(), "https://httpbin.org/get?page=2");
pub fn header(&self, key: impl Into<HeaderName>) -> Option<&HeaderValues>
[src]
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");
pub fn header_mut(
&mut self,
name: impl Into<HeaderName>
) -> Option<&mut HeaderValues>
[src]
&mut self,
name: impl Into<HeaderName>
) -> Option<&mut HeaderValues>
Get a mutable reference to a header.
pub fn insert_header(
&mut self,
name: impl Into<HeaderName>,
values: impl ToHeaderValues
) -> Option<HeaderValues>
[src]
&mut self,
name: impl Into<HeaderName>,
values: impl ToHeaderValues
) -> Option<HeaderValues>
Set an HTTP header.
pub fn append_header(
&mut self,
name: impl Into<HeaderName>,
values: impl ToHeaderValues
)
[src]
&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.
pub fn remove_header(
&mut self,
name: impl Into<HeaderName>
) -> Option<HeaderValues>
[src]
&mut self,
name: impl Into<HeaderName>
) -> Option<HeaderValues>
Remove a header.
#[must_use]pub fn iter(&self) -> Iter<'_>ⓘNotable traits for Iter<'a>
impl<'a> Iterator for Iter<'a> type Item = (&'a HeaderName, &'a HeaderValues);
[src]
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.
#[must_use]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);
[src]
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.
#[must_use]pub fn header_names(&self) -> Names<'_>ⓘNotable traits for Names<'a>
impl<'a> Iterator for Names<'a> type Item = &'a HeaderName;
[src]
Notable traits for Names<'a>
impl<'a> Iterator for Names<'a> type Item = &'a HeaderName;
An iterator visiting all header names in arbitrary order.
#[must_use]pub fn header_values(&self) -> Values<'_>ⓘNotable traits for Values<'a>
impl<'a> Iterator for Values<'a> type Item = &'a HeaderValue;
[src]
Notable traits for Values<'a>
impl<'a> Iterator for Values<'a> type Item = &'a HeaderValue;
An iterator visiting all header values in arbitrary order.
pub fn set_header(
&mut self,
key: impl Into<HeaderName>,
value: impl ToHeaderValues
)
[src]
&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");
#[must_use]pub fn ext<T: Send + Sync + 'static>(&self) -> Option<&T>
[src]
Get a request extension value.
pub fn set_ext<T: Send + Sync + 'static>(&mut self, val: T) -> Option<T>
[src]
Set a request extension value.
pub fn method(&self) -> Method
[src]
Get the request HTTP method.
Examples
let req = surf::get("https://httpbin.org/get").build(); assert_eq!(req.method(), surf::http::Method::Get);
pub fn url(&self) -> &Url
[src]
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")?);
pub fn content_type(&self) -> Option<Mime>
[src]
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.
pub fn set_content_type(&mut self, mime: Mime)
[src]
Set the request content type from a Mime
.
pub fn len(&self) -> Option<usize>
[src]
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.
pub fn is_empty(&self) -> Option<bool>
[src]
Returns true
if the set length of the body stream is zero, false
otherwise.
pub fn set_body(&mut self, body: impl Into<Body>)
[src]
pub fn take_body(&mut self) -> Body
[src]
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.
pub fn body_json(&mut self, json: &impl Serialize) -> Result<()>
[src]
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.
pub fn body_string(&mut self, string: String)
[src]
pub fn body_bytes(&mut self, bytes: impl AsRef<[u8]>)
[src]
pub async fn body_file<'_>(&'_ mut self, path: impl AsRef<Path>) -> Result<()>
[src]
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.
pub fn body_form(&mut self, form: &impl Serialize) -> Result<()>
[src]
Trait Implementations
impl AsMut<Request> for Request
[src]
impl AsRef<Request> for Request
[src]
impl Clone for Request
[src]
impl Debug for Request
[src]
impl From<Request> for Request
[src]
impl<'_> Index<&'_ str> for Request
[src]
type Output = HeaderValues
The returned type after indexing.
fn index(&self, name: &str) -> &HeaderValues
[src]
Returns a reference to the value corresponding to the supplied name.
Panics
Panics if the name is not present in Request
.
impl Index<HeaderName> for Request
[src]
type Output = HeaderValues
The returned type after indexing.
fn index(&self, name: HeaderName) -> &HeaderValues
[src]
Returns a reference to the value corresponding to the supplied name.
Panics
Panics if the name is not present in Request
.
impl Into<Request> for Request
[src]
impl Into<Request> for RequestBuilder
[src]
impl IntoIterator for Request
[src]
type Item = (HeaderName, HeaderValues)
The type of the elements being iterated over.
type IntoIter = IntoIter
Which kind of iterator are we turning this into?
fn into_iter(self) -> Self::IntoIter
[src]
Returns a iterator of references over the remaining items.
impl<'a> IntoIterator for &'a Request
[src]
type Item = (&'a HeaderName, &'a HeaderValues)
The type of the elements being iterated over.
type IntoIter = Iter<'a>
Which kind of iterator are we turning this into?
fn into_iter(self) -> Self::IntoIter
[src]
impl<'a> IntoIterator for &'a mut Request
[src]
type Item = (&'a HeaderName, &'a mut HeaderValues)
The type of the elements being iterated over.
type IntoIter = IterMut<'a>
Which kind of iterator are we turning this into?
fn into_iter(self) -> Self::IntoIter
[src]
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
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T> Instrument for T
[src]
fn instrument(self, span: Span) -> Instrumented<Self>
[src]
fn in_current_span(self) -> Instrumented<Self>
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<I> IntoIterator for I where
I: Iterator,
[src]
I: Iterator,
type Item = <I as Iterator>::Item
The type of the elements being iterated over.
type IntoIter = I
Which kind of iterator are we turning this into?
pub fn into_iter(self) -> I
[src]
impl<T> Same<T> for T
type Output = T
Should always be Self
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn clone_into(&self, target: &mut T)
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
V: MultiLane<T>,
pub fn vzip(self) -> V
impl<T> WithSubscriber for T
[src]
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
[src]
S: Into<Dispatch>,