Struct viaduct::Request

#[must_use =
  "`Request`'s \"builder\" functions take by move, not by `&mut self`"]pub struct Request {
    pub method: Method,
    pub url: Url,
    pub headers: Headers,
    pub body: Option<Vec<u8>>,
}

Fields

method: Method

url: Url

headers: Headers

body: Option<Vec<u8>>

Implementations

impl Request

pub fn new(method: Method, url: Url) -> Self

Construct a new request to the given url using the given method. Note that the request is not made until send() is called.

pub fn send(self) -> Result<Response, Error>

pub fn get(url: Url) -> Self

Alias for Request::new(Method::Get, url), for convenience.

pub fn post(url: Url) -> Self

Alias for Request::new(Method::Post, url), for convenience.

pub fn put(url: Url) -> Self

Alias for Request::new(Method::Put, url), for convenience.

pub fn delete(url: Url) -> Self

Alias for Request::new(Method::Delete, url), for convenience.

pub fn query(self, pairs: &[(&str, &str)]) -> Self

Append the provided query parameters to the URL

Example

let some_url = url::Url::parse("https://www.example.com/xyz").unwrap();

let req = Request::post(some_url).query(&[("a", "1234"), ("b", "qwerty")]);
assert_eq!(req.url.as_str(), "https://www.example.com/xyz?a=1234&b=qwerty");

// This appends to the query query instead of replacing `a`.
let req = req.query(&[("a", "5678")]);
assert_eq!(req.url.as_str(), "https://www.example.com/xyz?a=1234&b=qwerty&a=5678");

pub fn set_query<'a, Q: Into<Option<&'a str>>>(self, query: Q) -> Self

Set the query string of the URL. Note that req.set_query(None) will clear the query.

See also Request::query which appends a slice of query pairs, which is typically more ergonomic when usable.

Example

let some_url = url::Url::parse("https://www.example.com/xyz").unwrap();

let req = Request::post(some_url).set_query("a=b&c=d");
assert_eq!(req.url.as_str(), "https://www.example.com/xyz?a=b&c=d");

let req = req.set_query(None);
assert_eq!(req.url.as_str(), "https://www.example.com/xyz");

pub fn headers<I>(self, to_add: I) -> Self where
    I: IntoIterator<Item = Header>, 

Add all the provided headers to the list of headers to send with this request.

pub fn header<Name, Val>(self, name: Name, val: Val) -> Result<Self, Error> where
    Name: Into<HeaderName> + PartialEq<HeaderName>,
    Val: Into<String> + AsRef<str>, 

Add the provided header to the list of headers to send with this request.

This returns Err if val contains characters that may not appear in the body of a header.

Example

Request::post(some_url)
    .header(header_names::CONTENT_TYPE, "application/json")?
    .header("My-Header", "Some special value")?;
// ...

pub fn body(self, body: impl Into<Vec<u8>>) -> Self

Set this request's body.

pub fn json<T: ?Sized + Serialize>(self, val: &T) -> Self

Set body to the result of serializing val, and, unless it has already been set, set the Content-Type header to "application/json".

Note: This panics if serde_json::to_vec fails. This can only happen in a couple cases:

1. Trying to serialize a map with non-string keys.
2. We wrote a custom serializer that fails.

Neither of these are things we do. If they happen, it seems better for this to fail hard with an easy to track down panic, than for e.g. sync to fail with a JSON parse error (which we'd probably attribute to corrupt data on the server, or something).

Trait Implementations

impl Clone for Request

fn clone(&self) -> Request

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Request

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

Formats the value using the given formatter.

impl From<Request> for Request

fn from(request: Request) -> Self

Performs the conversion.

impl PartialEq<Request> for Request

fn eq(&self, other: &Request) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Request) -> bool

This method tests for !=.

impl StructuralPartialEq for Request