Merge pull request #60 from yoshuawuyts/trailers

Trailers

Author: yoshuawuyts

src/lib.rs

@@ -120,7 +120,6 @@ mod method;
 mod request;
 mod response;
 mod status_code;
-mod trailers;
 mod version;
 
 pub use body::Body;
@@ -144,5 +143,8 @@ pub use crate::url::Url;
 #[doc(inline)]
 pub use crate::cookies::Cookie;
 
+#[doc(inline)]
+pub mod trailers;
+
 #[cfg(feature = "hyperium_http")]
 mod hyperium_http;

src/request.rs

@@ -9,8 +9,8 @@ use crate::headers::{
     self, HeaderName, HeaderValue, Headers, Names, ToHeaderValues, Values, CONTENT_TYPE,
 };
 use crate::mime::Mime;
+use crate::trailers::{Trailers, TrailersSender};
 use crate::Cookie;
-use crate::Trailers;
 use crate::{Body, Method, Url, Version};
 
 pin_project_lite::pin_project! {
@@ -30,7 +30,7 @@ pin_project_lite::pin_project! {
         url: Url,
         headers: Headers,
         version: Option<Version>,
-        sender: sync::Sender<io::Result<Trailers>>,
+        sender: Option<sync::Sender<io::Result<Trailers>>>,
         receiver: sync::Receiver<io::Result<Trailers>>,
         #[pin]
         body: Body,
@@ -47,7 +47,7 @@ impl Request {
             headers: Headers::new(),
             version: None,
             body: Body::empty(),
-            sender,
+            sender: Some(sender),
             receiver,
         }
     }
@@ -376,8 +376,12 @@ impl Request {
     }
 
     /// Sends trailers to the a receiver.
-    pub async fn send_trailers(&self, trailers: io::Result<Trailers>) {
-        self.sender.send(trailers).await;
+    pub fn send_trailers(&mut self) -> TrailersSender {
+        let sender = self
+            .sender
+            .take()
+            .expect("Trailers sender can only be constructed once");
+        TrailersSender::new(sender)
     }
 
     /// Receive trailers from a sender.

src/response.rs

@@ -9,7 +9,7 @@ use crate::headers::{
     self, HeaderName, HeaderValue, Headers, Names, ToHeaderValues, Values, CONTENT_TYPE,
 };
 use crate::mime::Mime;
-use crate::Trailers;
+use crate::trailers::{Trailers, TrailersSender};
 use crate::{Body, Cookie, StatusCode, Version};
 
 pin_project_lite::pin_project! {
@@ -32,7 +32,7 @@ pin_project_lite::pin_project! {
         status: StatusCode,
         headers: Headers,
         version: Option<Version>,
-        sender: sync::Sender<io::Result<Trailers>>,
+        sender: Option<sync::Sender<io::Result<Trailers>>>,
         receiver: sync::Receiver<io::Result<Trailers>>,
         #[pin]
         body: Body,
@@ -48,7 +48,7 @@ impl Response {
             headers: Headers::new(),
             version: None,
             body: Body::empty(),
-            sender,
+            sender: Some(sender),
             receiver,
         }
     }
@@ -329,8 +329,12 @@ impl Response {
     }
 
     /// Sends trailers to the a receiver.
-    pub async fn send_trailers(&self, trailers: io::Result<Trailers>) {
-        self.sender.send(trailers).await;
+    pub fn send_trailers(&mut self) -> TrailersSender {
+        let sender = self
+            .sender
+            .take()
+            .expect("Trailers sender can only be constructed once");
+        TrailersSender::new(sender)
     }
 
     /// Receive trailers from a sender.

src/trailers.rs

@@ -1,6 +1,58 @@
+//! HTTP trailing headers.
+//!
+//! Trailing headers are headers that are send *after* the body payload has
+//! been sent. This is for example useful for sending integrity checks of
+//! streamed payloads that are computed on the fly.
+//!
+//! The way trailing headers are sent over the wire varies per protocol. But in
+//! `http-types` we provide a `Trailers` struct that's used to contain the headers.
+//!
+//! To send trailing headers, see `Request::{`[`send_trailers, `][req_send]
+//! [`recv_trailers`][req_recv]`}` and
+//! `Response::{`[`send_trailers, `][res_send][`recv_trailers`][res_recv]`}`.
+//!
+//! [req_send]: ../struct.Request.html#method.send_trailers
+//! [req_recv]: ../struct.Request.html#method.recv_trailers
+//! [res_send]: ../struct.Response.html#method.send_trailers
+//! [res_recv]: ../struct.Response.html#method.recv_trailers
+//!
+//! ## Example
+//!
+//! ```
+//! # fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
+//! # async_std::task::block_on(async {
+//! #
+//! use http_types::{Url, Method, Request, Trailers};
+//! use http_types::headers::{HeaderName, HeaderValue};
+//! use async_std::task;
+//! use std::str::FromStr;
+//!
+//! let mut req = Request::new(Method::Get, Url::parse("https://example.com").unwrap());
+//!
+//! let sender = req.send_trailers();
+//! let mut trailers = Trailers::new();
+//! trailers.insert(
+//!     HeaderName::from_str("Content-Type")?,
+//!     "text/plain",
+//! );
+//!
+//! task::spawn(async move {
+//!     let _trailers = req.recv_trailers().await;
+//! });
+//!
+//! sender.send(Ok(trailers)).await;
+//! #
+//! # Ok(()) })}
+//! ```
+//!
+//! ## See Also
+//! - [MDN HTTP Headers: Trailer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Trailer)
+//! - [HTTP/2 spec: HTTP Sequence](https://http2.github.io/http2-spec/#HttpSequence)
+
 use crate::headers::{
     HeaderName, HeaderValue, Headers, Iter, IterMut, Names, ToHeaderValues, Values,
 };
+use async_std::sync::Sender;
 
 use std::io;
 use std::ops::{Deref, DerefMut};
@@ -96,3 +148,27 @@ impl DerefMut for Trailers {
         &mut self.headers
     }
 }
+
+/// The sending half of a channel to send trailers.
+///
+/// Unlike `async_std::sync::channel` the `send` method on this type can only be
+/// called once, and cannot be cloned. That's because only a single instance of
+/// `Trailers` should be created.
+#[derive(Debug)]
+pub struct TrailersSender {
+    sender: Sender<io::Result<Trailers>>,
+}
+
+impl TrailersSender {
+    /// Create a new instance of `TrailersSender`.
+    pub(crate) fn new(sender: Sender<io::Result<Trailers>>) -> Self {
+        Self { sender }
+    }
+
+    /// Send a `Trailer`.
+    ///
+    /// The channel will be consumed after having sent trailers.
+    pub async fn send(self, trailers: io::Result<Trailers>) {
+        self.sender.send(trailers).await
+    }
+}