pub struct Request<T> { /* private fields */ }
Expand description
Represents an HTTP request.
An HTTP request consists of a head and a potentially optional body. The body
component is generic, enabling arbitrary types to represent the HTTP body.
For example, the body could be Vec<u8>
, a Stream
of byte chunks, or a
value that has been deserialized.
§Examples
Creating a Request
to send
use http::{Request, Response};
let mut request = Request::builder()
.uri("https://www.rust-lang.org/")
.header("User-Agent", "my-awesome-agent/1.0");
if needs_awesome_header() {
request = request.header("Awesome", "yes");
}
let response = send(request.body(()).unwrap());
fn send(req: Request<()>) -> Response<()> {
// ...
}
Inspecting a request to see what was sent.
use http::{Request, Response, StatusCode};
fn respond_to(req: Request<()>) -> http::Result<Response<()>> {
if req.uri() != "/awesome-url" {
return Response::builder()
.status(StatusCode::NOT_FOUND)
.body(())
}
let has_awesome_header = req.headers().contains_key("Awesome");
let body = req.body();
// ...
}
Deserialize a request of bytes via json:
use http::Request;
use serde::de;
fn deserialize<T>(req: Request<Vec<u8>>) -> serde_json::Result<Request<T>>
where for<'de> T: de::Deserialize<'de>,
{
let (parts, body) = req.into_parts();
let body = serde_json::from_slice(&body)?;
Ok(Request::from_parts(parts, body))
}
Or alternatively, serialize the body of a request to json
use http::Request;
use serde::ser;
fn serialize<T>(req: Request<T>) -> serde_json::Result<Request<Vec<u8>>>
where T: ser::Serialize,
{
let (parts, body) = req.into_parts();
let body = serde_json::to_vec(&body)?;
Ok(Request::from_parts(parts, body))
}
Implementations§
source§impl Request<()>
impl Request<()>
sourcepub fn builder() -> Builder
pub fn builder() -> Builder
Creates a new builder-style object to manufacture a Request
This method returns an instance of Builder
which can be used to
create a Request
.
§Examples
let request = Request::builder()
.method("GET")
.uri("https://www.rust-lang.org/")
.header("X-Custom-Foo", "Bar")
.body(())
.unwrap();
sourcepub fn get<T>(uri: T) -> Builder
pub fn get<T>(uri: T) -> Builder
Creates a new Builder
initialized with a GET method and the given URI.
This method returns an instance of Builder
which can be used to
create a Request
.
§Example
let request = Request::get("https://www.rust-lang.org/")
.body(())
.unwrap();
sourcepub fn put<T>(uri: T) -> Builder
pub fn put<T>(uri: T) -> Builder
Creates a new Builder
initialized with a PUT method and the given URI.
This method returns an instance of Builder
which can be used to
create a Request
.
§Example
let request = Request::put("https://www.rust-lang.org/")
.body(())
.unwrap();
sourcepub fn post<T>(uri: T) -> Builder
pub fn post<T>(uri: T) -> Builder
Creates a new Builder
initialized with a POST method and the given URI.
This method returns an instance of Builder
which can be used to
create a Request
.
§Example
let request = Request::post("https://www.rust-lang.org/")
.body(())
.unwrap();
sourcepub fn delete<T>(uri: T) -> Builder
pub fn delete<T>(uri: T) -> Builder
Creates a new Builder
initialized with a DELETE method and the given URI.
This method returns an instance of Builder
which can be used to
create a Request
.
§Example
let request = Request::delete("https://www.rust-lang.org/")
.body(())
.unwrap();
sourcepub fn options<T>(uri: T) -> Builder
pub fn options<T>(uri: T) -> Builder
Creates a new Builder
initialized with an OPTIONS method and the given URI.
This method returns an instance of Builder
which can be used to
create a Request
.
§Example
let request = Request::options("https://www.rust-lang.org/")
.body(())
.unwrap();
sourcepub fn head<T>(uri: T) -> Builder
pub fn head<T>(uri: T) -> Builder
Creates a new Builder
initialized with a HEAD method and the given URI.
This method returns an instance of Builder
which can be used to
create a Request
.
§Example
let request = Request::head("https://www.rust-lang.org/")
.body(())
.unwrap();
sourcepub fn connect<T>(uri: T) -> Builder
pub fn connect<T>(uri: T) -> Builder
Creates a new Builder
initialized with a CONNECT method and the given URI.
This method returns an instance of Builder
which can be used to
create a Request
.
§Example
let request = Request::connect("https://www.rust-lang.org/")
.body(())
.unwrap();
sourcepub fn patch<T>(uri: T) -> Builder
pub fn patch<T>(uri: T) -> Builder
Creates a new Builder
initialized with a PATCH method and the given URI.
This method returns an instance of Builder
which can be used to
create a Request
.
§Example
let request = Request::patch("https://www.rust-lang.org/")
.body(())
.unwrap();
source§impl<T> Request<T>
impl<T> Request<T>
sourcepub fn new(body: T) -> Request<T>
pub fn new(body: T) -> Request<T>
Creates a new blank Request
with the body
The component parts of this request will be set to their default, e.g. the GET method, no headers, etc.
§Examples
let request = Request::new("hello world");
assert_eq!(*request.method(), Method::GET);
assert_eq!(*request.body(), "hello world");
sourcepub fn from_parts(parts: Parts, body: T) -> Request<T>
pub fn from_parts(parts: Parts, body: T) -> Request<T>
Creates a new Request
with the given components parts and body.
§Examples
let request = Request::new("hello world");
let (mut parts, body) = request.into_parts();
parts.method = Method::POST;
let request = Request::from_parts(parts, body);
sourcepub fn method(&self) -> &Method
pub fn method(&self) -> &Method
Returns a reference to the associated HTTP method.
§Examples
let request: Request<()> = Request::default();
assert_eq!(*request.method(), Method::GET);
sourcepub fn method_mut(&mut self) -> &mut Method
pub fn method_mut(&mut self) -> &mut Method
Returns a mutable reference to the associated HTTP method.
§Examples
let mut request: Request<()> = Request::default();
*request.method_mut() = Method::PUT;
assert_eq!(*request.method(), Method::PUT);
sourcepub fn uri(&self) -> &Uri
pub fn uri(&self) -> &Uri
Returns a reference to the associated URI.
§Examples
let request: Request<()> = Request::default();
assert_eq!(*request.uri(), *"/");
sourcepub fn uri_mut(&mut self) -> &mut Uri
pub fn uri_mut(&mut self) -> &mut Uri
Returns a mutable reference to the associated URI.
§Examples
let mut request: Request<()> = Request::default();
*request.uri_mut() = "/hello".parse().unwrap();
assert_eq!(*request.uri(), *"/hello");
sourcepub fn version(&self) -> Version
pub fn version(&self) -> Version
Returns the associated version.
§Examples
let request: Request<()> = Request::default();
assert_eq!(request.version(), Version::HTTP_11);
sourcepub fn version_mut(&mut self) -> &mut Version
pub fn version_mut(&mut self) -> &mut Version
Returns a mutable reference to the associated version.
§Examples
let mut request: Request<()> = Request::default();
*request.version_mut() = Version::HTTP_2;
assert_eq!(request.version(), Version::HTTP_2);
sourcepub fn headers(&self) -> &HeaderMap<HeaderValue>
pub fn headers(&self) -> &HeaderMap<HeaderValue>
Returns a reference to the associated header field map.
§Examples
let request: Request<()> = Request::default();
assert!(request.headers().is_empty());
sourcepub fn headers_mut(&mut self) -> &mut HeaderMap<HeaderValue>
pub fn headers_mut(&mut self) -> &mut HeaderMap<HeaderValue>
Returns a mutable reference to the associated header field map.
§Examples
let mut request: Request<()> = Request::default();
request.headers_mut().insert(HOST, HeaderValue::from_static("world"));
assert!(!request.headers().is_empty());
sourcepub fn extensions(&self) -> &Extensions
pub fn extensions(&self) -> &Extensions
Returns a reference to the associated extensions.
§Examples
let request: Request<()> = Request::default();
assert!(request.extensions().get::<i32>().is_none());
sourcepub fn extensions_mut(&mut self) -> &mut Extensions
pub fn extensions_mut(&mut self) -> &mut Extensions
Returns a mutable reference to the associated extensions.
§Examples
let mut request: Request<()> = Request::default();
request.extensions_mut().insert("hello");
assert_eq!(request.extensions().get(), Some(&"hello"));
sourcepub fn body(&self) -> &T
pub fn body(&self) -> &T
Returns a reference to the associated HTTP body.
§Examples
let request: Request<String> = Request::default();
assert!(request.body().is_empty());
sourcepub fn body_mut(&mut self) -> &mut T
pub fn body_mut(&mut self) -> &mut T
Returns a mutable reference to the associated HTTP body.
§Examples
let mut request: Request<String> = Request::default();
request.body_mut().push_str("hello world");
assert!(!request.body().is_empty());
sourcepub fn into_body(self) -> T
pub fn into_body(self) -> T
Consumes the request, returning just the body.
§Examples
let request = Request::new(10);
let body = request.into_body();
assert_eq!(body, 10);
sourcepub fn into_parts(self) -> (Parts, T)
pub fn into_parts(self) -> (Parts, T)
Consumes the request returning the head and body parts.
§Examples
let request = Request::new(());
let (parts, body) = request.into_parts();
assert_eq!(parts.method, Method::GET);
sourcepub fn map<F, U>(self, f: F) -> Request<U>where
F: FnOnce(T) -> U,
pub fn map<F, U>(self, f: F) -> Request<U>where
F: FnOnce(T) -> U,
Consumes the request returning a new request with body mapped to the return type of the passed in function.
§Examples
let request = Request::builder().body("some string").unwrap();
let mapped_request: Request<&[u8]> = request.map(|b| {
assert_eq!(b, "some string");
b.as_bytes()
});
assert_eq!(mapped_request.body(), &"some string".as_bytes());