Add example (and doc reference) for warp::body::stream() (#1061)

* Add example (and doc reference) for warp::body::stream()

As of right now it didn't look like there was example usage for this functionality. It took me some trial and error to figure out the typing for the Stream so that I could pass it into a handler function like this. This example hopefully avoids similar headaches for others.

* cargo fmt

examples/stream.rs

@@ -0,0 +1,30 @@
+use bytes::Buf;
+use futures_util::{Stream, StreamExt};
+use warp::{reply::Response, Filter, Reply};
+
+#[tokio::main]
+async fn main() {
+    // Running curl -T /path/to/a/file 'localhost:3030/' should echo back the content of the file,
+    // or an HTTP 413 error if the configured size limit is exceeded.
+    let route = warp::body::content_length_limit(65536)
+        .and(warp::body::stream())
+        .then(handler);
+    warp::serve(route).run(([127, 0, 0, 1], 3030)).await;
+}
+
+async fn handler(
+    mut body: impl Stream<Item = Result<impl Buf, warp::Error>> + Unpin + Send + Sync,
+) -> Response {
+    let mut collected: Vec<u8> = vec![];
+    while let Some(buf) = body.next().await {
+        let mut buf = buf.unwrap();
+        while buf.remaining() > 0 {
+            let chunk = buf.chunk();
+            let chunk_len = chunk.len();
+            collected.extend_from_slice(chunk);
+            buf.advance(chunk_len);
+        }
+    }
+    println!("Sending {} bytes", collected.len());
+    collected.into_response()
+}

src/filters/body.rs

@@ -70,6 +70,8 @@ pub fn content_length_limit(limit: u64) -> impl Filter<Extract = (), Error = Rej
 /// If other filters have already extracted the body, this filter will reject
 /// with a `500 Internal Server Error`.
 ///
+/// For example usage, please take a look at [examples/stream.rs](https://github.com/seanmonstar/warp/blob/master/examples/stream.rs).
+///
 /// # Warning
 ///
 /// This does not have a default size limit, it would be wise to use one to