Struct crux_http::Request

source ·
pub struct Request { /* private fields */ }
Expand description

An HTTP request, returns a Response.

Implementations§

source§

impl Request

source

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
fn main() -> crux_http::Result<()> {
use crux_http::http::{Url, Method};

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

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

Get the URL querystring.

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

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

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

Set the URL querystring.

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

let query = Index { page: 2 };
let mut req = caps.http.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");
source

pub fn header(&self, key: impl Into<HeaderName>) -> Option<&HeaderValues>

Get an HTTP header.

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

pub fn header_mut( &mut self, name: impl Into<HeaderName>, ) -> Option<&mut HeaderValues>

Get a mutable reference to a header.

source

pub fn insert_header( &mut self, name: impl Into<HeaderName>, values: impl ToHeaderValues, ) -> Option<HeaderValues>

Set an HTTP header.

source

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.

source

pub fn remove_header( &mut self, name: impl Into<HeaderName>, ) -> Option<HeaderValues>

Remove a header.

source

pub fn iter(&self) -> Iter<'_>

An iterator visiting all header pairs in arbitrary order.

source

pub fn iter_mut(&mut self) -> IterMut<'_>

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

source

pub fn header_names(&self) -> Names<'_>

An iterator visiting all header names in arbitrary order.

source

pub fn header_values(&self) -> Values<'_>

An iterator visiting all header values in arbitrary order.

source

pub fn set_header( &mut self, key: impl Into<HeaderName>, value: impl ToHeaderValues, )

Set an HTTP header.

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

pub fn ext<T: Send + Sync + 'static>(&self) -> Option<&T>

Get a request extension value.

source

pub fn set_ext<T: Send + Sync + 'static>(&mut self, val: T) -> Option<T>

Set a request extension value.

source

pub fn method(&self) -> Method

Get the request HTTP method.

§Examples
let req = caps.http.get("https://httpbin.org/get").build();
assert_eq!(req.method(), crux_http::http::Method::Get);
source

pub fn url(&self) -> &Url

Get the request url.

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

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.

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.

source

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

Set the request content type from a Mime.

Read more on MDN

source

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.

source

pub fn is_empty(&self) -> Option<bool>

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

source

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.

source

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.

source

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

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.

source

pub fn body_string(&mut self, string: String)

Pass a string as the request body.

§Mime

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

source

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

Pass bytes as the request body.

§Mime

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

source

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

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.

source

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 = caps.http.get("https://httpbin.org/get").build();
req.middleware(crux_http::middleware::Redirect::default());

Trait Implementations§

source§

impl AsMut<Headers> for Request

source§

fn as_mut(&mut self) -> &mut Headers

Converts this type into a mutable reference of the (usually inferred) input type.
source§

impl AsMut<Request> for Request

source§

fn as_mut(&mut self) -> &mut Request

Converts this type into a mutable reference of the (usually inferred) input type.
source§

impl AsRef<Headers> for Request

source§

fn as_ref(&self) -> &Headers

Converts this type into a shared reference of the (usually inferred) input type.
source§

impl AsRef<Request> for Request

source§

fn as_ref(&self) -> &Request

Converts this type into a shared reference of the (usually inferred) input type.
source§

impl Clone for Request

source§

fn clone(&self) -> Request

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for Request

source§

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

Formats the value using the given formatter. Read more
source§

impl From<Request> for Request

source§

fn from(req: Request) -> Self

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

source§

impl Index<&str> for Request

source§

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.

source§

type Output = HeaderValues

The returned type after indexing.
source§

impl Index<HeaderName> for Request

source§

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.

source§

type Output = HeaderValues

The returned type after indexing.
source§

impl Into<Request> for Request

source§

fn into(self) -> Request

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

source§

impl<'a> IntoIterator for &'a Request

source§

type Item = (&'a HeaderName, &'a HeaderValues)

The type of the elements being iterated over.
source§

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?
source§

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value. Read more
source§

impl<'a> IntoIterator for &'a mut Request

source§

type Item = (&'a HeaderName, &'a mut HeaderValues)

The type of the elements being iterated over.
source§

type IntoIter = IterMut<'a>

Which kind of iterator are we turning this into?
source§

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value. Read more
source§

impl IntoIterator for Request

source§

fn into_iter(self) -> Self::IntoIter

Returns a iterator of references over the remaining items.

source§

type Item = (HeaderName, HeaderValues)

The type of the elements being iterated over.
source§

type IntoIter = IntoIter

Which kind of iterator are we turning this into?

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

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

fn clone_into(&self, target: &mut T)

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

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V