http/
response.rs

1//! HTTP response types.
2//!
3//! This module contains structs related to HTTP responses, notably the
4//! `Response` type itself as well as a builder to create responses. Typically
5//! you'll import the `http::Response` type rather than reaching into this
6//! module itself.
7//!
8//! # Examples
9//!
10//! Creating a `Response` to return
11//!
12//! ```
13//! use http::{Request, Response, StatusCode};
14//!
15//! fn respond_to(req: Request<()>) -> http::Result<Response<()>> {
16//!     let mut builder = Response::builder()
17//!         .header("Foo", "Bar")
18//!         .status(StatusCode::OK);
19//!
20//!     if req.headers().contains_key("Another-Header") {
21//!         builder = builder.header("Another-Header", "Ack");
22//!     }
23//!
24//!     builder.body(())
25//! }
26//! ```
27//!
28//! A simple 404 handler
29//!
30//! ```
31//! use http::{Request, Response, StatusCode};
32//!
33//! fn not_found(_req: Request<()>) -> http::Result<Response<()>> {
34//!     Response::builder()
35//!         .status(StatusCode::NOT_FOUND)
36//!         .body(())
37//! }
38//! ```
39//!
40//! Or otherwise inspecting the result of a request:
41//!
42//! ```no_run
43//! use http::{Request, Response};
44//!
45//! fn get(url: &str) -> http::Result<Response<()>> {
46//!     // ...
47//! # panic!()
48//! }
49//!
50//! let response = get("https://www.rust-lang.org/").unwrap();
51//!
52//! if !response.status().is_success() {
53//!     panic!("failed to get a successful response status!");
54//! }
55//!
56//! if let Some(date) = response.headers().get("Date") {
57//!     // we've got a `Date` header!
58//! }
59//!
60//! let body = response.body();
61//! // ...
62//! ```
63
64use std::any::Any;
65use std::convert::TryInto;
66use std::fmt;
67
68use crate::header::{HeaderMap, HeaderName, HeaderValue};
69use crate::status::StatusCode;
70use crate::version::Version;
71use crate::{Extensions, Result};
72
73/// Represents an HTTP response
74///
75/// An HTTP response consists of a head and a potentially optional body. The body
76/// component is generic, enabling arbitrary types to represent the HTTP body.
77/// For example, the body could be `Vec<u8>`, a `Stream` of byte chunks, or a
78/// value that has been deserialized.
79///
80/// Typically you'll work with responses on the client side as the result of
81/// sending a `Request` and on the server you'll be generating a `Response` to
82/// send back to the client.
83///
84/// # Examples
85///
86/// Creating a `Response` to return
87///
88/// ```
89/// use http::{Request, Response, StatusCode};
90///
91/// fn respond_to(req: Request<()>) -> http::Result<Response<()>> {
92///     let mut builder = Response::builder()
93///         .header("Foo", "Bar")
94///         .status(StatusCode::OK);
95///
96///     if req.headers().contains_key("Another-Header") {
97///         builder = builder.header("Another-Header", "Ack");
98///     }
99///
100///     builder.body(())
101/// }
102/// ```
103///
104/// A simple 404 handler
105///
106/// ```
107/// use http::{Request, Response, StatusCode};
108///
109/// fn not_found(_req: Request<()>) -> http::Result<Response<()>> {
110///     Response::builder()
111///         .status(StatusCode::NOT_FOUND)
112///         .body(())
113/// }
114/// ```
115///
116/// Or otherwise inspecting the result of a request:
117///
118/// ```no_run
119/// use http::{Request, Response};
120///
121/// fn get(url: &str) -> http::Result<Response<()>> {
122///     // ...
123/// # panic!()
124/// }
125///
126/// let response = get("https://www.rust-lang.org/").unwrap();
127///
128/// if !response.status().is_success() {
129///     panic!("failed to get a successful response status!");
130/// }
131///
132/// if let Some(date) = response.headers().get("Date") {
133///     // we've got a `Date` header!
134/// }
135///
136/// let body = response.body();
137/// // ...
138/// ```
139///
140/// Deserialize a response of bytes via json:
141///
142/// ```
143/// # extern crate serde;
144/// # extern crate serde_json;
145/// # extern crate http;
146/// use http::Response;
147/// use serde::de;
148///
149/// fn deserialize<T>(res: Response<Vec<u8>>) -> serde_json::Result<Response<T>>
150///     where for<'de> T: de::Deserialize<'de>,
151/// {
152///     let (parts, body) = res.into_parts();
153///     let body = serde_json::from_slice(&body)?;
154///     Ok(Response::from_parts(parts, body))
155/// }
156/// #
157/// # fn main() {}
158/// ```
159///
160/// Or alternatively, serialize the body of a response to json
161///
162/// ```
163/// # extern crate serde;
164/// # extern crate serde_json;
165/// # extern crate http;
166/// use http::Response;
167/// use serde::ser;
168///
169/// fn serialize<T>(res: Response<T>) -> serde_json::Result<Response<Vec<u8>>>
170///     where T: ser::Serialize,
171/// {
172///     let (parts, body) = res.into_parts();
173///     let body = serde_json::to_vec(&body)?;
174///     Ok(Response::from_parts(parts, body))
175/// }
176/// #
177/// # fn main() {}
178/// ```
179#[derive(Clone)]
180pub struct Response<T> {
181    head: Parts,
182    body: T,
183}
184
185/// Component parts of an HTTP `Response`
186///
187/// The HTTP response head consists of a status, version, and a set of
188/// header fields.
189#[derive(Clone)]
190pub struct Parts {
191    /// The response's status
192    pub status: StatusCode,
193
194    /// The response's version
195    pub version: Version,
196
197    /// The response's headers
198    pub headers: HeaderMap<HeaderValue>,
199
200    /// The response's extensions
201    pub extensions: Extensions,
202
203    _priv: (),
204}
205
206/// An HTTP response builder
207///
208/// This type can be used to construct an instance of `Response` through a
209/// builder-like pattern.
210#[derive(Debug)]
211pub struct Builder {
212    inner: Result<Parts>,
213}
214
215impl Response<()> {
216    /// Creates a new builder-style object to manufacture a `Response`
217    ///
218    /// This method returns an instance of `Builder` which can be used to
219    /// create a `Response`.
220    ///
221    /// # Examples
222    ///
223    /// ```
224    /// # use http::*;
225    /// let response = Response::builder()
226    ///     .status(200)
227    ///     .header("X-Custom-Foo", "Bar")
228    ///     .body(())
229    ///     .unwrap();
230    /// ```
231    #[inline]
232    pub fn builder() -> Builder {
233        Builder::new()
234    }
235}
236
237impl<T> Response<T> {
238    /// Creates a new blank `Response` with the body
239    ///
240    /// The component parts of this response will be set to their default, e.g.
241    /// the ok status, no headers, etc.
242    ///
243    /// # Examples
244    ///
245    /// ```
246    /// # use http::*;
247    /// let response = Response::new("hello world");
248    ///
249    /// assert_eq!(response.status(), StatusCode::OK);
250    /// assert_eq!(*response.body(), "hello world");
251    /// ```
252    #[inline]
253    pub fn new(body: T) -> Response<T> {
254        Response {
255            head: Parts::new(),
256            body,
257        }
258    }
259
260    /// Creates a new `Response` with the given head and body
261    ///
262    /// # Examples
263    ///
264    /// ```
265    /// # use http::*;
266    /// let response = Response::new("hello world");
267    /// let (mut parts, body) = response.into_parts();
268    ///
269    /// parts.status = StatusCode::BAD_REQUEST;
270    /// let response = Response::from_parts(parts, body);
271    ///
272    /// assert_eq!(response.status(), StatusCode::BAD_REQUEST);
273    /// assert_eq!(*response.body(), "hello world");
274    /// ```
275    #[inline]
276    pub fn from_parts(parts: Parts, body: T) -> Response<T> {
277        Response { head: parts, body }
278    }
279
280    /// Returns the `StatusCode`.
281    ///
282    /// # Examples
283    ///
284    /// ```
285    /// # use http::*;
286    /// let response: Response<()> = Response::default();
287    /// assert_eq!(response.status(), StatusCode::OK);
288    /// ```
289    #[inline]
290    pub fn status(&self) -> StatusCode {
291        self.head.status
292    }
293
294    /// Returns a mutable reference to the associated `StatusCode`.
295    ///
296    /// # Examples
297    ///
298    /// ```
299    /// # use http::*;
300    /// let mut response: Response<()> = Response::default();
301    /// *response.status_mut() = StatusCode::CREATED;
302    /// assert_eq!(response.status(), StatusCode::CREATED);
303    /// ```
304    #[inline]
305    pub fn status_mut(&mut self) -> &mut StatusCode {
306        &mut self.head.status
307    }
308
309    /// Returns a reference to the associated version.
310    ///
311    /// # Examples
312    ///
313    /// ```
314    /// # use http::*;
315    /// let response: Response<()> = Response::default();
316    /// assert_eq!(response.version(), Version::HTTP_11);
317    /// ```
318    #[inline]
319    pub fn version(&self) -> Version {
320        self.head.version
321    }
322
323    /// Returns a mutable reference to the associated version.
324    ///
325    /// # Examples
326    ///
327    /// ```
328    /// # use http::*;
329    /// let mut response: Response<()> = Response::default();
330    /// *response.version_mut() = Version::HTTP_2;
331    /// assert_eq!(response.version(), Version::HTTP_2);
332    /// ```
333    #[inline]
334    pub fn version_mut(&mut self) -> &mut Version {
335        &mut self.head.version
336    }
337
338    /// Returns a reference to the associated header field map.
339    ///
340    /// # Examples
341    ///
342    /// ```
343    /// # use http::*;
344    /// let response: Response<()> = Response::default();
345    /// assert!(response.headers().is_empty());
346    /// ```
347    #[inline]
348    pub fn headers(&self) -> &HeaderMap<HeaderValue> {
349        &self.head.headers
350    }
351
352    /// Returns a mutable reference to the associated header field map.
353    ///
354    /// # Examples
355    ///
356    /// ```
357    /// # use http::*;
358    /// # use http::header::*;
359    /// let mut response: Response<()> = Response::default();
360    /// response.headers_mut().insert(HOST, HeaderValue::from_static("world"));
361    /// assert!(!response.headers().is_empty());
362    /// ```
363    #[inline]
364    pub fn headers_mut(&mut self) -> &mut HeaderMap<HeaderValue> {
365        &mut self.head.headers
366    }
367
368    /// Returns a reference to the associated extensions.
369    ///
370    /// # Examples
371    ///
372    /// ```
373    /// # use http::*;
374    /// let response: Response<()> = Response::default();
375    /// assert!(response.extensions().get::<i32>().is_none());
376    /// ```
377    #[inline]
378    pub fn extensions(&self) -> &Extensions {
379        &self.head.extensions
380    }
381
382    /// Returns a mutable reference to the associated extensions.
383    ///
384    /// # Examples
385    ///
386    /// ```
387    /// # use http::*;
388    /// # use http::header::*;
389    /// let mut response: Response<()> = Response::default();
390    /// response.extensions_mut().insert("hello");
391    /// assert_eq!(response.extensions().get(), Some(&"hello"));
392    /// ```
393    #[inline]
394    pub fn extensions_mut(&mut self) -> &mut Extensions {
395        &mut self.head.extensions
396    }
397
398    /// Returns a reference to the associated HTTP body.
399    ///
400    /// # Examples
401    ///
402    /// ```
403    /// # use http::*;
404    /// let response: Response<String> = Response::default();
405    /// assert!(response.body().is_empty());
406    /// ```
407    #[inline]
408    pub fn body(&self) -> &T {
409        &self.body
410    }
411
412    /// Returns a mutable reference to the associated HTTP body.
413    ///
414    /// # Examples
415    ///
416    /// ```
417    /// # use http::*;
418    /// let mut response: Response<String> = Response::default();
419    /// response.body_mut().push_str("hello world");
420    /// assert!(!response.body().is_empty());
421    /// ```
422    #[inline]
423    pub fn body_mut(&mut self) -> &mut T {
424        &mut self.body
425    }
426
427    /// Consumes the response, returning just the body.
428    ///
429    /// # Examples
430    ///
431    /// ```
432    /// # use http::Response;
433    /// let response = Response::new(10);
434    /// let body = response.into_body();
435    /// assert_eq!(body, 10);
436    /// ```
437    #[inline]
438    pub fn into_body(self) -> T {
439        self.body
440    }
441
442    /// Consumes the response returning the head and body parts.
443    ///
444    /// # Examples
445    ///
446    /// ```
447    /// # use http::*;
448    /// let response: Response<()> = Response::default();
449    /// let (parts, body) = response.into_parts();
450    /// assert_eq!(parts.status, StatusCode::OK);
451    /// ```
452    #[inline]
453    pub fn into_parts(self) -> (Parts, T) {
454        (self.head, self.body)
455    }
456
457    /// Consumes the response returning a new response with body mapped to the
458    /// return type of the passed in function.
459    ///
460    /// # Examples
461    ///
462    /// ```
463    /// # use http::*;
464    /// let response = Response::builder().body("some string").unwrap();
465    /// let mapped_response: Response<&[u8]> = response.map(|b| {
466    ///   assert_eq!(b, "some string");
467    ///   b.as_bytes()
468    /// });
469    /// assert_eq!(mapped_response.body(), &"some string".as_bytes());
470    /// ```
471    #[inline]
472    pub fn map<F, U>(self, f: F) -> Response<U>
473    where
474        F: FnOnce(T) -> U,
475    {
476        Response {
477            body: f(self.body),
478            head: self.head,
479        }
480    }
481}
482
483impl<T: Default> Default for Response<T> {
484    #[inline]
485    fn default() -> Response<T> {
486        Response::new(T::default())
487    }
488}
489
490impl<T: fmt::Debug> fmt::Debug for Response<T> {
491    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
492        f.debug_struct("Response")
493            .field("status", &self.status())
494            .field("version", &self.version())
495            .field("headers", self.headers())
496            // omits Extensions because not useful
497            .field("body", self.body())
498            .finish()
499    }
500}
501
502impl Parts {
503    /// Creates a new default instance of `Parts`
504    fn new() -> Parts {
505        Parts {
506            status: StatusCode::default(),
507            version: Version::default(),
508            headers: HeaderMap::default(),
509            extensions: Extensions::default(),
510            _priv: (),
511        }
512    }
513}
514
515impl fmt::Debug for Parts {
516    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
517        f.debug_struct("Parts")
518            .field("status", &self.status)
519            .field("version", &self.version)
520            .field("headers", &self.headers)
521            // omits Extensions because not useful
522            // omits _priv because not useful
523            .finish()
524    }
525}
526
527impl Builder {
528    /// Creates a new default instance of `Builder` to construct either a
529    /// `Head` or a `Response`.
530    ///
531    /// # Examples
532    ///
533    /// ```
534    /// # use http::*;
535    ///
536    /// let response = response::Builder::new()
537    ///     .status(200)
538    ///     .body(())
539    ///     .unwrap();
540    /// ```
541    #[inline]
542    pub fn new() -> Builder {
543        Builder::default()
544    }
545
546    /// Set the HTTP status for this response.
547    ///
548    /// By default this is `200`.
549    ///
550    /// # Examples
551    ///
552    /// ```
553    /// # use http::*;
554    ///
555    /// let response = Response::builder()
556    ///     .status(200)
557    ///     .body(())
558    ///     .unwrap();
559    /// ```
560    pub fn status<T>(self, status: T) -> Builder
561    where
562        T: TryInto<StatusCode>,
563        <T as TryInto<StatusCode>>::Error: Into<crate::Error>,
564    {
565        self.and_then(move |mut head| {
566            head.status = status.try_into().map_err(Into::into)?;
567            Ok(head)
568        })
569    }
570
571    /// Set the HTTP version for this response.
572    ///
573    /// By default this is HTTP/1.1
574    ///
575    /// # Examples
576    ///
577    /// ```
578    /// # use http::*;
579    ///
580    /// let response = Response::builder()
581    ///     .version(Version::HTTP_2)
582    ///     .body(())
583    ///     .unwrap();
584    /// ```
585    pub fn version(self, version: Version) -> Builder {
586        self.and_then(move |mut head| {
587            head.version = version;
588            Ok(head)
589        })
590    }
591
592    /// Appends a header to this response builder.
593    ///
594    /// This function will append the provided key/value as a header to the
595    /// internal `HeaderMap` being constructed. Essentially this is equivalent
596    /// to calling `HeaderMap::append`.
597    ///
598    /// # Examples
599    ///
600    /// ```
601    /// # use http::*;
602    /// # use http::header::HeaderValue;
603    ///
604    /// let response = Response::builder()
605    ///     .header("Content-Type", "text/html")
606    ///     .header("X-Custom-Foo", "bar")
607    ///     .header("content-length", 0)
608    ///     .body(())
609    ///     .unwrap();
610    /// ```
611    pub fn header<K, V>(self, key: K, value: V) -> Builder
612    where
613        K: TryInto<HeaderName>,
614        <K as TryInto<HeaderName>>::Error: Into<crate::Error>,
615        V: TryInto<HeaderValue>,
616        <V as TryInto<HeaderValue>>::Error: Into<crate::Error>,
617    {
618        self.and_then(move |mut head| {
619            let name = key.try_into().map_err(Into::into)?;
620            let value = value.try_into().map_err(Into::into)?;
621            head.headers.try_append(name, value)?;
622            Ok(head)
623        })
624    }
625
626    /// Get header on this response builder.
627    ///
628    /// When builder has error returns None.
629    ///
630    /// # Example
631    ///
632    /// ```
633    /// # use http::Response;
634    /// # use http::header::HeaderValue;
635    /// let res = Response::builder()
636    ///     .header("Accept", "text/html")
637    ///     .header("X-Custom-Foo", "bar");
638    /// let headers = res.headers_ref().unwrap();
639    /// assert_eq!( headers["Accept"], "text/html" );
640    /// assert_eq!( headers["X-Custom-Foo"], "bar" );
641    /// ```
642    pub fn headers_ref(&self) -> Option<&HeaderMap<HeaderValue>> {
643        self.inner.as_ref().ok().map(|h| &h.headers)
644    }
645
646    /// Get header on this response builder.
647    /// when builder has error returns None
648    ///
649    /// # Example
650    ///
651    /// ```
652    /// # use http::*;
653    /// # use http::header::HeaderValue;
654    /// # use http::response::Builder;
655    /// let mut res = Response::builder();
656    /// {
657    ///   let headers = res.headers_mut().unwrap();
658    ///   headers.insert("Accept", HeaderValue::from_static("text/html"));
659    ///   headers.insert("X-Custom-Foo", HeaderValue::from_static("bar"));
660    /// }
661    /// let headers = res.headers_ref().unwrap();
662    /// assert_eq!( headers["Accept"], "text/html" );
663    /// assert_eq!( headers["X-Custom-Foo"], "bar" );
664    /// ```
665    pub fn headers_mut(&mut self) -> Option<&mut HeaderMap<HeaderValue>> {
666        self.inner.as_mut().ok().map(|h| &mut h.headers)
667    }
668
669    /// Adds an extension to this builder
670    ///
671    /// # Examples
672    ///
673    /// ```
674    /// # use http::*;
675    ///
676    /// let response = Response::builder()
677    ///     .extension("My Extension")
678    ///     .body(())
679    ///     .unwrap();
680    ///
681    /// assert_eq!(response.extensions().get::<&'static str>(),
682    ///            Some(&"My Extension"));
683    /// ```
684    pub fn extension<T>(self, extension: T) -> Builder
685    where
686        T: Clone + Any + Send + Sync + 'static,
687    {
688        self.and_then(move |mut head| {
689            head.extensions.insert(extension);
690            Ok(head)
691        })
692    }
693
694    /// Get a reference to the extensions for this response builder.
695    ///
696    /// If the builder has an error, this returns `None`.
697    ///
698    /// # Example
699    ///
700    /// ```
701    /// # use http::Response;
702    /// let res = Response::builder().extension("My Extension").extension(5u32);
703    /// let extensions = res.extensions_ref().unwrap();
704    /// assert_eq!(extensions.get::<&'static str>(), Some(&"My Extension"));
705    /// assert_eq!(extensions.get::<u32>(), Some(&5u32));
706    /// ```
707    pub fn extensions_ref(&self) -> Option<&Extensions> {
708        self.inner.as_ref().ok().map(|h| &h.extensions)
709    }
710
711    /// Get a mutable reference to the extensions for this response builder.
712    ///
713    /// If the builder has an error, this returns `None`.
714    ///
715    /// # Example
716    ///
717    /// ```
718    /// # use http::Response;
719    /// let mut res = Response::builder().extension("My Extension");
720    /// let mut extensions = res.extensions_mut().unwrap();
721    /// assert_eq!(extensions.get::<&'static str>(), Some(&"My Extension"));
722    /// extensions.insert(5u32);
723    /// assert_eq!(extensions.get::<u32>(), Some(&5u32));
724    /// ```
725    pub fn extensions_mut(&mut self) -> Option<&mut Extensions> {
726        self.inner.as_mut().ok().map(|h| &mut h.extensions)
727    }
728
729    /// "Consumes" this builder, using the provided `body` to return a
730    /// constructed `Response`.
731    ///
732    /// # Errors
733    ///
734    /// This function may return an error if any previously configured argument
735    /// failed to parse or get converted to the internal representation. For
736    /// example if an invalid `head` was specified via `header("Foo",
737    /// "Bar\r\n")` the error will be returned when this function is called
738    /// rather than when `header` was called.
739    ///
740    /// # Examples
741    ///
742    /// ```
743    /// # use http::*;
744    ///
745    /// let response = Response::builder()
746    ///     .body(())
747    ///     .unwrap();
748    /// ```
749    pub fn body<T>(self, body: T) -> Result<Response<T>> {
750        self.inner.map(move |head| Response { head, body })
751    }
752
753    // private
754
755    fn and_then<F>(self, func: F) -> Self
756    where
757        F: FnOnce(Parts) -> Result<Parts>,
758    {
759        Builder {
760            inner: self.inner.and_then(func),
761        }
762    }
763}
764
765impl Default for Builder {
766    #[inline]
767    fn default() -> Builder {
768        Builder {
769            inner: Ok(Parts::new()),
770        }
771    }
772}
773
774#[cfg(test)]
775mod tests {
776    use super::*;
777
778    #[test]
779    fn it_can_map_a_body_from_one_type_to_another() {
780        let response = Response::builder().body("some string").unwrap();
781        let mapped_response = response.map(|s| {
782            assert_eq!(s, "some string");
783            123u32
784        });
785        assert_eq!(mapped_response.body(), &123u32);
786    }
787}