1//! HTTP request types.
2//!
3//! This module contains structs related to HTTP requests, notably the
4//! `Request` type itself as well as a builder to create requests. Typically
5//! you'll import the `http::Request` type rather than reaching into this
6//! module itself.
7//!
8//! # Examples
9//!
10//! Creating a `Request` to send
11//!
12//! ```no_run
13//! use http::{Request, Response};
14//!
15//! let mut request = Request::builder()
16//! .uri("https://www.rust-lang.org/")
17//! .header("User-Agent", "my-awesome-agent/1.0");
18//!
19//! if needs_awesome_header() {
20//! request = request.header("Awesome", "yes");
21//! }
22//!
23//! let response = send(request.body(()).unwrap());
24//!
25//! # fn needs_awesome_header() -> bool {
26//! # true
27//! # }
28//! #
29//! fn send(req: Request<()>) -> Response<()> {
30//! // ...
31//! # panic!()
32//! }
33//! ```
34//!
35//! Inspecting a request to see what was sent.
36//!
37//! ```
38//! use http::{Request, Response, StatusCode};
39//!
40//! fn respond_to(req: Request<()>) -> http::Result<Response<()>> {
41//! if req.uri() != "/awesome-url" {
42//! return Response::builder()
43//! .status(StatusCode::NOT_FOUND)
44//! .body(())
45//! }
46//!
47//! let has_awesome_header = req.headers().contains_key("Awesome");
48//! let body = req.body();
49//!
50//! // ...
51//! # panic!()
52//! }
53//! ```
54
55use std::any::Any;
56use std::convert::{TryFrom};
57use std::fmt;
58
59use crate::header::{HeaderMap, HeaderName, HeaderValue};
60use crate::method::Method;
61use crate::version::Version;
62use crate::{Extensions, Result, Uri};
63
64/// Represents an HTTP request.
65///
66/// An HTTP request consists of a head and a potentially optional body. The body
67/// component is generic, enabling arbitrary types to represent the HTTP body.
68/// For example, the body could be `Vec<u8>`, a `Stream` of byte chunks, or a
69/// value that has been deserialized.
70///
71/// # Examples
72///
73/// Creating a `Request` to send
74///
75/// ```no_run
76/// use http::{Request, Response};
77///
78/// let mut request = Request::builder()
79/// .uri("https://www.rust-lang.org/")
80/// .header("User-Agent", "my-awesome-agent/1.0");
81///
82/// if needs_awesome_header() {
83/// request = request.header("Awesome", "yes");
84/// }
85///
86/// let response = send(request.body(()).unwrap());
87///
88/// # fn needs_awesome_header() -> bool {
89/// # true
90/// # }
91/// #
92/// fn send(req: Request<()>) -> Response<()> {
93/// // ...
94/// # panic!()
95/// }
96/// ```
97///
98/// Inspecting a request to see what was sent.
99///
100/// ```
101/// use http::{Request, Response, StatusCode};
102///
103/// fn respond_to(req: Request<()>) -> http::Result<Response<()>> {
104/// if req.uri() != "/awesome-url" {
105/// return Response::builder()
106/// .status(StatusCode::NOT_FOUND)
107/// .body(())
108/// }
109///
110/// let has_awesome_header = req.headers().contains_key("Awesome");
111/// let body = req.body();
112///
113/// // ...
114/// # panic!()
115/// }
116/// ```
117///
118/// Deserialize a request of bytes via json:
119///
120/// ```
121/// # extern crate serde;
122/// # extern crate serde_json;
123/// # extern crate http;
124/// use http::Request;
125/// use serde::de;
126///
127/// fn deserialize<T>(req: Request<Vec<u8>>) -> serde_json::Result<Request<T>>
128/// where for<'de> T: de::Deserialize<'de>,
129/// {
130/// let (parts, body) = req.into_parts();
131/// let body = serde_json::from_slice(&body)?;
132/// Ok(Request::from_parts(parts, body))
133/// }
134/// #
135/// # fn main() {}
136/// ```
137///
138/// Or alternatively, serialize the body of a request to json
139///
140/// ```
141/// # extern crate serde;
142/// # extern crate serde_json;
143/// # extern crate http;
144/// use http::Request;
145/// use serde::ser;
146///
147/// fn serialize<T>(req: Request<T>) -> serde_json::Result<Request<Vec<u8>>>
148/// where T: ser::Serialize,
149/// {
150/// let (parts, body) = req.into_parts();
151/// let body = serde_json::to_vec(&body)?;
152/// Ok(Request::from_parts(parts, body))
153/// }
154/// #
155/// # fn main() {}
156/// ```
157pub struct Request<T> {
158 head: Parts,
159 body: T,
160}
161
162/// Component parts of an HTTP `Request`
163///
164/// The HTTP request head consists of a method, uri, version, and a set of
165/// header fields.
166pub struct Parts {
167 /// The request's method
168 pub method: Method,
169
170 /// The request's URI
171 pub uri: Uri,
172
173 /// The request's version
174 pub version: Version,
175
176 /// The request's headers
177 pub headers: HeaderMap<HeaderValue>,
178
179 /// The request's extensions
180 pub extensions: Extensions,
181
182 _priv: (),
183}
184
185/// An HTTP request builder
186///
187/// This type can be used to construct an instance or `Request`
188/// through a builder-like pattern.
189#[derive(Debug)]
190pub struct Builder {
191 inner: Result<Parts>,
192}
193
194impl Request<()> {
195 /// Creates a new builder-style object to manufacture a `Request`
196 ///
197 /// This method returns an instance of `Builder` which can be used to
198 /// create a `Request`.
199 ///
200 /// # Examples
201 ///
202 /// ```
203 /// # use http::*;
204 /// let request = Request::builder()
205 /// .method("GET")
206 /// .uri("https://www.rust-lang.org/")
207 /// .header("X-Custom-Foo", "Bar")
208 /// .body(())
209 /// .unwrap();
210 /// ```
211 #[inline]
212 pub fn builder() -> Builder {
213 Builder::new()
214 }
215
216 /// Creates a new `Builder` initialized with a GET method and the given URI.
217 ///
218 /// This method returns an instance of `Builder` which can be used to
219 /// create a `Request`.
220 ///
221 /// # Example
222 ///
223 /// ```
224 /// # use http::*;
225 ///
226 /// let request = Request::get("https://www.rust-lang.org/")
227 /// .body(())
228 /// .unwrap();
229 /// ```
230 pub fn get<T>(uri: T) -> Builder
231 where
232 Uri: TryFrom<T>,
233 <Uri as TryFrom<T>>::Error: Into<crate::Error>,
234
235 {
236 Builder::new().method(Method::GET).uri(uri)
237 }
238
239 /// Creates a new `Builder` initialized with a PUT method and the given URI.
240 ///
241 /// This method returns an instance of `Builder` which can be used to
242 /// create a `Request`.
243 ///
244 /// # Example
245 ///
246 /// ```
247 /// # use http::*;
248 ///
249 /// let request = Request::put("https://www.rust-lang.org/")
250 /// .body(())
251 /// .unwrap();
252 /// ```
253 pub fn put<T>(uri: T) -> Builder
254 where
255 Uri: TryFrom<T>,
256 <Uri as TryFrom<T>>::Error: Into<crate::Error>,
257
258 {
259 Builder::new().method(Method::PUT).uri(uri)
260 }
261
262 /// Creates a new `Builder` initialized with a POST method and the given URI.
263 ///
264 /// This method returns an instance of `Builder` which can be used to
265 /// create a `Request`.
266 ///
267 /// # Example
268 ///
269 /// ```
270 /// # use http::*;
271 ///
272 /// let request = Request::post("https://www.rust-lang.org/")
273 /// .body(())
274 /// .unwrap();
275 /// ```
276 pub fn post<T>(uri: T) -> Builder
277 where
278 Uri: TryFrom<T>,
279 <Uri as TryFrom<T>>::Error: Into<crate::Error>,
280
281 {
282 Builder::new().method(Method::POST).uri(uri)
283 }
284
285 /// Creates a new `Builder` initialized with a DELETE method and the given URI.
286 ///
287 /// This method returns an instance of `Builder` which can be used to
288 /// create a `Request`.
289 ///
290 /// # Example
291 ///
292 /// ```
293 /// # use http::*;
294 ///
295 /// let request = Request::delete("https://www.rust-lang.org/")
296 /// .body(())
297 /// .unwrap();
298 /// ```
299 pub fn delete<T>(uri: T) -> Builder
300 where
301 Uri: TryFrom<T>,
302 <Uri as TryFrom<T>>::Error: Into<crate::Error>,
303
304 {
305 Builder::new().method(Method::DELETE).uri(uri)
306 }
307
308 /// Creates a new `Builder` initialized with an OPTIONS method and the given URI.
309 ///
310 /// This method returns an instance of `Builder` which can be used to
311 /// create a `Request`.
312 ///
313 /// # Example
314 ///
315 /// ```
316 /// # use http::*;
317 ///
318 /// let request = Request::options("https://www.rust-lang.org/")
319 /// .body(())
320 /// .unwrap();
321 /// # assert_eq!(*request.method(), Method::OPTIONS);
322 /// ```
323 pub fn options<T>(uri: T) -> Builder
324 where
325 Uri: TryFrom<T>,
326 <Uri as TryFrom<T>>::Error: Into<crate::Error>,
327
328 {
329 Builder::new().method(Method::OPTIONS).uri(uri)
330 }
331
332 /// Creates a new `Builder` initialized with a HEAD method and the given URI.
333 ///
334 /// This method returns an instance of `Builder` which can be used to
335 /// create a `Request`.
336 ///
337 /// # Example
338 ///
339 /// ```
340 /// # use http::*;
341 ///
342 /// let request = Request::head("https://www.rust-lang.org/")
343 /// .body(())
344 /// .unwrap();
345 /// ```
346 pub fn head<T>(uri: T) -> Builder
347 where
348 Uri: TryFrom<T>,
349 <Uri as TryFrom<T>>::Error: Into<crate::Error>,
350
351 {
352 Builder::new().method(Method::HEAD).uri(uri)
353 }
354
355 /// Creates a new `Builder` initialized with a CONNECT method and the given URI.
356 ///
357 /// This method returns an instance of `Builder` which can be used to
358 /// create a `Request`.
359 ///
360 /// # Example
361 ///
362 /// ```
363 /// # use http::*;
364 ///
365 /// let request = Request::connect("https://www.rust-lang.org/")
366 /// .body(())
367 /// .unwrap();
368 /// ```
369 pub fn connect<T>(uri: T) -> Builder
370 where
371 Uri: TryFrom<T>,
372 <Uri as TryFrom<T>>::Error: Into<crate::Error>,
373
374 {
375 Builder::new().method(Method::CONNECT).uri(uri)
376 }
377
378 /// Creates a new `Builder` initialized with a PATCH method and the given URI.
379 ///
380 /// This method returns an instance of `Builder` which can be used to
381 /// create a `Request`.
382 ///
383 /// # Example
384 ///
385 /// ```
386 /// # use http::*;
387 ///
388 /// let request = Request::patch("https://www.rust-lang.org/")
389 /// .body(())
390 /// .unwrap();
391 /// ```
392 pub fn patch<T>(uri: T) -> Builder
393 where
394 Uri: TryFrom<T>,
395 <Uri as TryFrom<T>>::Error: Into<crate::Error>,
396 {
397 Builder::new().method(Method::PATCH).uri(uri)
398 }
399
400 /// Creates a new `Builder` initialized with a TRACE method and the given URI.
401 ///
402 /// This method returns an instance of `Builder` which can be used to
403 /// create a `Request`.
404 ///
405 /// # Example
406 ///
407 /// ```
408 /// # use http::*;
409 ///
410 /// let request = Request::trace("https://www.rust-lang.org/")
411 /// .body(())
412 /// .unwrap();
413 /// ```
414 pub fn trace<T>(uri: T) -> Builder
415 where
416 Uri: TryFrom<T>,
417 <Uri as TryFrom<T>>::Error: Into<crate::Error>,
418 {
419 Builder::new().method(Method::TRACE).uri(uri)
420 }
421}
422
423impl<T> Request<T> {
424 /// Creates a new blank `Request` with the body
425 ///
426 /// The component parts of this request will be set to their default, e.g.
427 /// the GET method, no headers, etc.
428 ///
429 /// # Examples
430 ///
431 /// ```
432 /// # use http::*;
433 /// let request = Request::new("hello world");
434 ///
435 /// assert_eq!(*request.method(), Method::GET);
436 /// assert_eq!(*request.body(), "hello world");
437 /// ```
438 #[inline]
439 pub fn new(body: T) -> Request<T> {
440 Request {
441 head: Parts::new(),
442 body: body,
443 }
444 }
445
446 /// Creates a new `Request` with the given components parts and body.
447 ///
448 /// # Examples
449 ///
450 /// ```
451 /// # use http::*;
452 /// let request = Request::new("hello world");
453 /// let (mut parts, body) = request.into_parts();
454 /// parts.method = Method::POST;
455 ///
456 /// let request = Request::from_parts(parts, body);
457 /// ```
458 #[inline]
459 pub fn from_parts(parts: Parts, body: T) -> Request<T> {
460 Request {
461 head: parts,
462 body: body,
463 }
464 }
465
466 /// Returns a reference to the associated HTTP method.
467 ///
468 /// # Examples
469 ///
470 /// ```
471 /// # use http::*;
472 /// let request: Request<()> = Request::default();
473 /// assert_eq!(*request.method(), Method::GET);
474 /// ```
475 #[inline]
476 pub fn method(&self) -> &Method {
477 &self.head.method
478 }
479
480 /// Returns a mutable reference to the associated HTTP method.
481 ///
482 /// # Examples
483 ///
484 /// ```
485 /// # use http::*;
486 /// let mut request: Request<()> = Request::default();
487 /// *request.method_mut() = Method::PUT;
488 /// assert_eq!(*request.method(), Method::PUT);
489 /// ```
490 #[inline]
491 pub fn method_mut(&mut self) -> &mut Method {
492 &mut self.head.method
493 }
494
495 /// Returns a reference to the associated URI.
496 ///
497 /// # Examples
498 ///
499 /// ```
500 /// # use http::*;
501 /// let request: Request<()> = Request::default();
502 /// assert_eq!(*request.uri(), *"/");
503 /// ```
504 #[inline]
505 pub fn uri(&self) -> &Uri {
506 &self.head.uri
507 }
508
509 /// Returns a mutable reference to the associated URI.
510 ///
511 /// # Examples
512 ///
513 /// ```
514 /// # use http::*;
515 /// let mut request: Request<()> = Request::default();
516 /// *request.uri_mut() = "/hello".parse().unwrap();
517 /// assert_eq!(*request.uri(), *"/hello");
518 /// ```
519 #[inline]
520 pub fn uri_mut(&mut self) -> &mut Uri {
521 &mut self.head.uri
522 }
523
524 /// Returns the associated version.
525 ///
526 /// # Examples
527 ///
528 /// ```
529 /// # use http::*;
530 /// let request: Request<()> = Request::default();
531 /// assert_eq!(request.version(), Version::HTTP_11);
532 /// ```
533 #[inline]
534 pub fn version(&self) -> Version {
535 self.head.version
536 }
537
538 /// Returns a mutable reference to the associated version.
539 ///
540 /// # Examples
541 ///
542 /// ```
543 /// # use http::*;
544 /// let mut request: Request<()> = Request::default();
545 /// *request.version_mut() = Version::HTTP_2;
546 /// assert_eq!(request.version(), Version::HTTP_2);
547 /// ```
548 #[inline]
549 pub fn version_mut(&mut self) -> &mut Version {
550 &mut self.head.version
551 }
552
553 /// Returns a reference to the associated header field map.
554 ///
555 /// # Examples
556 ///
557 /// ```
558 /// # use http::*;
559 /// let request: Request<()> = Request::default();
560 /// assert!(request.headers().is_empty());
561 /// ```
562 #[inline]
563 pub fn headers(&self) -> &HeaderMap<HeaderValue> {
564 &self.head.headers
565 }
566
567 /// Returns a mutable reference to the associated header field map.
568 ///
569 /// # Examples
570 ///
571 /// ```
572 /// # use http::*;
573 /// # use http::header::*;
574 /// let mut request: Request<()> = Request::default();
575 /// request.headers_mut().insert(HOST, HeaderValue::from_static("world"));
576 /// assert!(!request.headers().is_empty());
577 /// ```
578 #[inline]
579 pub fn headers_mut(&mut self) -> &mut HeaderMap<HeaderValue> {
580 &mut self.head.headers
581 }
582
583 /// Returns a reference to the associated extensions.
584 ///
585 /// # Examples
586 ///
587 /// ```
588 /// # use http::*;
589 /// let request: Request<()> = Request::default();
590 /// assert!(request.extensions().get::<i32>().is_none());
591 /// ```
592 #[inline]
593 pub fn extensions(&self) -> &Extensions {
594 &self.head.extensions
595 }
596
597 /// Returns a mutable reference to the associated extensions.
598 ///
599 /// # Examples
600 ///
601 /// ```
602 /// # use http::*;
603 /// # use http::header::*;
604 /// let mut request: Request<()> = Request::default();
605 /// request.extensions_mut().insert("hello");
606 /// assert_eq!(request.extensions().get(), Some(&"hello"));
607 /// ```
608 #[inline]
609 pub fn extensions_mut(&mut self) -> &mut Extensions {
610 &mut self.head.extensions
611 }
612
613 /// Returns a reference to the associated HTTP body.
614 ///
615 /// # Examples
616 ///
617 /// ```
618 /// # use http::*;
619 /// let request: Request<String> = Request::default();
620 /// assert!(request.body().is_empty());
621 /// ```
622 #[inline]
623 pub fn body(&self) -> &T {
624 &self.body
625 }
626
627 /// Returns a mutable reference to the associated HTTP body.
628 ///
629 /// # Examples
630 ///
631 /// ```
632 /// # use http::*;
633 /// let mut request: Request<String> = Request::default();
634 /// request.body_mut().push_str("hello world");
635 /// assert!(!request.body().is_empty());
636 /// ```
637 #[inline]
638 pub fn body_mut(&mut self) -> &mut T {
639 &mut self.body
640 }
641
642 /// Consumes the request, returning just the body.
643 ///
644 /// # Examples
645 ///
646 /// ```
647 /// # use http::Request;
648 /// let request = Request::new(10);
649 /// let body = request.into_body();
650 /// assert_eq!(body, 10);
651 /// ```
652 #[inline]
653 pub fn into_body(self) -> T {
654 self.body
655 }
656
657 /// Consumes the request returning the head and body parts.
658 ///
659 /// # Examples
660 ///
661 /// ```
662 /// # use http::*;
663 /// let request = Request::new(());
664 /// let (parts, body) = request.into_parts();
665 /// assert_eq!(parts.method, Method::GET);
666 /// ```
667 #[inline]
668 pub fn into_parts(self) -> (Parts, T) {
669 (self.head, self.body)
670 }
671
672 /// Consumes the request returning a new request with body mapped to the
673 /// return type of the passed in function.
674 ///
675 /// # Examples
676 ///
677 /// ```
678 /// # use http::*;
679 /// let request = Request::builder().body("some string").unwrap();
680 /// let mapped_request: Request<&[u8]> = request.map(|b| {
681 /// assert_eq!(b, "some string");
682 /// b.as_bytes()
683 /// });
684 /// assert_eq!(mapped_request.body(), &"some string".as_bytes());
685 /// ```
686 #[inline]
687 pub fn map<F, U>(self, f: F) -> Request<U>
688 where
689 F: FnOnce(T) -> U,
690 {
691 Request {
692 body: f(self.body),
693 head: self.head,
694 }
695 }
696}
697
698impl<T: Default> Default for Request<T> {
699 fn default() -> Request<T> {
700 Request::new(T::default())
701 }
702}
703
704impl<T: fmt::Debug> fmt::Debug for Request<T> {
705 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
706 f.debug_struct("Request")
707 .field("method", self.method())
708 .field("uri", self.uri())
709 .field("version", &self.version())
710 .field("headers", self.headers())
711 // omits Extensions because not useful
712 .field("body", self.body())
713 .finish()
714 }
715}
716
717impl Parts {
718 /// Creates a new default instance of `Parts`
719 fn new() -> Parts {
720 Parts {
721 method: Method::default(),
722 uri: Uri::default(),
723 version: Version::default(),
724 headers: HeaderMap::default(),
725 extensions: Extensions::default(),
726 _priv: (),
727 }
728 }
729}
730
731impl fmt::Debug for Parts {
732 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
733 f.debug_struct("Parts")
734 .field("method", &self.method)
735 .field("uri", &self.uri)
736 .field("version", &self.version)
737 .field("headers", &self.headers)
738 // omits Extensions because not useful
739 // omits _priv because not useful
740 .finish()
741 }
742}
743
744impl Builder {
745 /// Creates a new default instance of `Builder` to construct a `Request`.
746 ///
747 /// # Examples
748 ///
749 /// ```
750 /// # use http::*;
751 ///
752 /// let req = request::Builder::new()
753 /// .method("POST")
754 /// .body(())
755 /// .unwrap();
756 /// ```
757 #[inline]
758 pub fn new() -> Builder {
759 Builder::default()
760 }
761
762 /// Set the HTTP method for this request.
763 ///
764 /// By default this is `GET`.
765 ///
766 /// # Examples
767 ///
768 /// ```
769 /// # use http::*;
770 ///
771 /// let req = Request::builder()
772 /// .method("POST")
773 /// .body(())
774 /// .unwrap();
775 /// ```
776 pub fn method<T>(self, method: T) -> Builder
777 where
778 Method: TryFrom<T>,
779 <Method as TryFrom<T>>::Error: Into<crate::Error>,
780 {
781 self.and_then(move |mut head| {
782 let method = TryFrom::try_from(method).map_err(Into::into)?;
783 head.method = method;
784 Ok(head)
785 })
786 }
787
788 /// Get the HTTP Method for this request.
789 ///
790 /// By default this is `GET`. If builder has error, returns None.
791 ///
792 /// # Examples
793 ///
794 /// ```
795 /// # use http::*;
796 ///
797 /// let mut req = Request::builder();
798 /// assert_eq!(req.method_ref(),Some(&Method::GET));
799 ///
800 /// req = req.method("POST");
801 /// assert_eq!(req.method_ref(),Some(&Method::POST));
802 /// ```
803 pub fn method_ref(&self) -> Option<&Method> {
804 self.inner.as_ref().ok().map(|h| &h.method)
805 }
806
807 /// Set the URI for this request.
808 ///
809 /// By default this is `/`.
810 ///
811 /// # Examples
812 ///
813 /// ```
814 /// # use http::*;
815 ///
816 /// let req = Request::builder()
817 /// .uri("https://www.rust-lang.org/")
818 /// .body(())
819 /// .unwrap();
820 /// ```
821 pub fn uri<T>(self, uri: T) -> Builder
822 where
823 Uri: TryFrom<T>,
824 <Uri as TryFrom<T>>::Error: Into<crate::Error>,
825 {
826 self.and_then(move |mut head| {
827 head.uri = TryFrom::try_from(uri).map_err(Into::into)?;
828 Ok(head)
829 })
830 }
831
832 /// Get the URI for this request
833 ///
834 /// By default this is `/`.
835 ///
836 /// # Examples
837 ///
838 /// ```
839 /// # use http::*;
840 ///
841 /// let mut req = Request::builder();
842 /// assert_eq!(req.uri_ref().unwrap(), "/" );
843 ///
844 /// req = req.uri("https://www.rust-lang.org/");
845 /// assert_eq!(req.uri_ref().unwrap(), "https://www.rust-lang.org/" );
846 /// ```
847 pub fn uri_ref(&self) -> Option<&Uri> {
848 self.inner.as_ref().ok().map(|h| &h.uri)
849 }
850
851 /// Set the HTTP version for this request.
852 ///
853 /// By default this is HTTP/1.1
854 ///
855 /// # Examples
856 ///
857 /// ```
858 /// # use http::*;
859 ///
860 /// let req = Request::builder()
861 /// .version(Version::HTTP_2)
862 /// .body(())
863 /// .unwrap();
864 /// ```
865 pub fn version(self, version: Version) -> Builder {
866 self.and_then(move |mut head| {
867 head.version = version;
868 Ok(head)
869 })
870 }
871
872 /// Get the HTTP version for this request
873 ///
874 /// By default this is HTTP/1.1.
875 ///
876 /// # Examples
877 ///
878 /// ```
879 /// # use http::*;
880 ///
881 /// let mut req = Request::builder();
882 /// assert_eq!(req.version_ref().unwrap(), &Version::HTTP_11 );
883 ///
884 /// req = req.version(Version::HTTP_2);
885 /// assert_eq!(req.version_ref().unwrap(), &Version::HTTP_2 );
886 /// ```
887 pub fn version_ref(&self) -> Option<&Version> {
888 self.inner.as_ref().ok().map(|h| &h.version)
889 }
890
891 /// Appends a header to this request builder.
892 ///
893 /// This function will append the provided key/value as a header to the
894 /// internal `HeaderMap` being constructed. Essentially this is equivalent
895 /// to calling `HeaderMap::append`.
896 ///
897 /// # Examples
898 ///
899 /// ```
900 /// # use http::*;
901 /// # use http::header::HeaderValue;
902 ///
903 /// let req = Request::builder()
904 /// .header("Accept", "text/html")
905 /// .header("X-Custom-Foo", "bar")
906 /// .body(())
907 /// .unwrap();
908 /// ```
909 pub fn header<K, V>(self, key: K, value: V) -> Builder
910 where
911 HeaderName: TryFrom<K>,
912 <HeaderName as TryFrom<K>>::Error: Into<crate::Error>,
913 HeaderValue: TryFrom<V>,
914 <HeaderValue as TryFrom<V>>::Error: Into<crate::Error>,
915 {
916 self.and_then(move |mut head| {
917 let name = <HeaderName as TryFrom<K>>::try_from(key).map_err(Into::into)?;
918 let value = <HeaderValue as TryFrom<V>>::try_from(value).map_err(Into::into)?;
919 head.headers.append(name, value);
920 Ok(head)
921 })
922 }
923
924 /// Get header on this request builder.
925 /// when builder has error returns None
926 ///
927 /// # Example
928 ///
929 /// ```
930 /// # use http::Request;
931 /// let req = Request::builder()
932 /// .header("Accept", "text/html")
933 /// .header("X-Custom-Foo", "bar");
934 /// let headers = req.headers_ref().unwrap();
935 /// assert_eq!( headers["Accept"], "text/html" );
936 /// assert_eq!( headers["X-Custom-Foo"], "bar" );
937 /// ```
938 pub fn headers_ref(&self) -> Option<&HeaderMap<HeaderValue>> {
939 self.inner.as_ref().ok().map(|h| &h.headers)
940 }
941
942 /// Get headers on this request builder.
943 ///
944 /// When builder has error returns None.
945 ///
946 /// # Example
947 ///
948 /// ```
949 /// # use http::{header::HeaderValue, Request};
950 /// let mut req = Request::builder();
951 /// {
952 /// let headers = req.headers_mut().unwrap();
953 /// headers.insert("Accept", HeaderValue::from_static("text/html"));
954 /// headers.insert("X-Custom-Foo", HeaderValue::from_static("bar"));
955 /// }
956 /// let headers = req.headers_ref().unwrap();
957 /// assert_eq!( headers["Accept"], "text/html" );
958 /// assert_eq!( headers["X-Custom-Foo"], "bar" );
959 /// ```
960 pub fn headers_mut(&mut self) -> Option<&mut HeaderMap<HeaderValue>> {
961 self.inner.as_mut().ok().map(|h| &mut h.headers)
962 }
963
964 /// Adds an extension to this builder
965 ///
966 /// # Examples
967 ///
968 /// ```
969 /// # use http::*;
970 ///
971 /// let req = Request::builder()
972 /// .extension("My Extension")
973 /// .body(())
974 /// .unwrap();
975 ///
976 /// assert_eq!(req.extensions().get::<&'static str>(),
977 /// Some(&"My Extension"));
978 /// ```
979 pub fn extension<T>(self, extension: T) -> Builder
980 where
981 T: Any + Send + Sync + 'static,
982 {
983 self.and_then(move |mut head| {
984 head.extensions.insert(extension);
985 Ok(head)
986 })
987 }
988
989 /// Get a reference to the extensions for this request builder.
990 ///
991 /// If the builder has an error, this returns `None`.
992 ///
993 /// # Example
994 ///
995 /// ```
996 /// # use http::Request;
997 /// let req = Request::builder().extension("My Extension").extension(5u32);
998 /// let extensions = req.extensions_ref().unwrap();
999 /// assert_eq!(extensions.get::<&'static str>(), Some(&"My Extension"));
1000 /// assert_eq!(extensions.get::<u32>(), Some(&5u32));
1001 /// ```
1002 pub fn extensions_ref(&self) -> Option<&Extensions> {
1003 self.inner.as_ref().ok().map(|h| &h.extensions)
1004 }
1005
1006 /// Get a mutable reference to the extensions for this request builder.
1007 ///
1008 /// If the builder has an error, this returns `None`.
1009 ///
1010 /// # Example
1011 ///
1012 /// ```
1013 /// # use http::Request;
1014 /// let mut req = Request::builder().extension("My Extension");
1015 /// let mut extensions = req.extensions_mut().unwrap();
1016 /// assert_eq!(extensions.get::<&'static str>(), Some(&"My Extension"));
1017 /// extensions.insert(5u32);
1018 /// assert_eq!(extensions.get::<u32>(), Some(&5u32));
1019 /// ```
1020 pub fn extensions_mut(&mut self) -> Option<&mut Extensions> {
1021 self.inner.as_mut().ok().map(|h| &mut h.extensions)
1022 }
1023
1024 /// "Consumes" this builder, using the provided `body` to return a
1025 /// constructed `Request`.
1026 ///
1027 /// # Errors
1028 ///
1029 /// This function may return an error if any previously configured argument
1030 /// failed to parse or get converted to the internal representation. For
1031 /// example if an invalid `head` was specified via `header("Foo",
1032 /// "Bar\r\n")` the error will be returned when this function is called
1033 /// rather than when `header` was called.
1034 ///
1035 /// # Examples
1036 ///
1037 /// ```
1038 /// # use http::*;
1039 ///
1040 /// let request = Request::builder()
1041 /// .body(())
1042 /// .unwrap();
1043 /// ```
1044 pub fn body<T>(self, body: T) -> Result<Request<T>> {
1045 self.inner.map(move |head| {
1046 Request {
1047 head,
1048 body,
1049 }
1050 })
1051 }
1052
1053 // private
1054
1055 fn and_then<F>(self, func: F) -> Self
1056 where
1057 F: FnOnce(Parts) -> Result<Parts>
1058 {
1059 Builder {
1060 inner: self.inner.and_then(func),
1061 }
1062 }
1063}
1064
1065impl Default for Builder {
1066 #[inline]
1067 fn default() -> Builder {
1068 Builder {
1069 inner: Ok(Parts::new()),
1070 }
1071 }
1072}
1073
1074#[cfg(test)]
1075mod tests {
1076 use super::*;
1077
1078 #[test]
1079 fn it_can_map_a_body_from_one_type_to_another() {
1080 let request = Request::builder().body("some string").unwrap();
1081 let mapped_request = request.map(|s| {
1082 assert_eq!(s, "some string");
1083 123u32
1084 });
1085 assert_eq!(mapped_request.body(), &123u32);
1086 }
1087}
1088