Merge pull request #55 from yoshuawuyts/simplify-examples

Simplify examples

Author: yoshuawuyts

Cargo.toml

@@ -14,7 +14,7 @@ edition = "2018"
 [dependencies]
 url = "2.1.0"
 httparse = "1.3.3"
-async-std = { version = "1.4.0", default-features = false }
+async-std = { version = "1.5.0", features = ["unstable"] }
 http-types = { path = '../http-types' }
 pin-project-lite = "0.1.1"
 byte-pool = "0.2.1"

examples/client.rs

@@ -1,55 +1,19 @@
-use std::pin::Pin;
-use std::sync::Arc;
-
 use async_h1::client;
-use async_std::io::{self, Read, Write};
-use async_std::net::{self, TcpStream};
-use async_std::task::{self, Context, Poll};
+use async_std::net::{TcpStream};
 use http_types::{Error, Method, Request, Url};
 
-fn main() -> Result<(), Error> {
-    task::block_on(async {
-        let stream = net::TcpStream::connect("127.0.0.1:8080").await?;
-        let peer_addr = stream.peer_addr()?;
-        println!("connecting to {}", peer_addr);
-
-        // TODO: Delete this line when we implement `Clone` for `TcpStream`.
-        let stream = Stream(Arc::new(stream));
-
-        for i in 0usize..2 {
-            println!("making request {}/2", i + 1);
-            let url = Url::parse(&format!("http://{}/foo", peer_addr)).unwrap();
-            let req = Request::new(Method::Get, dbg!(url));
-            let res = client::connect(stream.clone(), req).await?;
-            println!("{:?}", res);
-        }
-        Ok(())
-    })
-}
-
-#[derive(Clone)]
-struct Stream(Arc<TcpStream>);
-
-impl Read for Stream {
-    fn poll_read(
-        self: Pin<&mut Self>,
-        cx: &mut Context,
-        buf: &mut [u8],
-    ) -> Poll<io::Result<usize>> {
-        Pin::new(&mut &*self.0).poll_read(cx, buf)
-    }
-}
-
-impl Write for Stream {
-    fn poll_write(self: Pin<&mut Self>, cx: &mut Context, buf: &[u8]) -> Poll<io::Result<usize>> {
-        Pin::new(&mut &*self.0).poll_write(cx, buf)
-    }
-
-    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context) -> Poll<io::Result<()>> {
-        Pin::new(&mut &*self.0).poll_flush(cx)
-    }
-
-    fn poll_close(self: Pin<&mut Self>, cx: &mut Context) -> Poll<io::Result<()>> {
-        Pin::new(&mut &*self.0).poll_close(cx)
+#[async_std::main]
+async fn main() -> Result<(), Error> {
+    let stream = TcpStream::connect("127.0.0.1:8080").await?;
+    let peer_addr = stream.peer_addr()?;
+    println!("connecting to {}", peer_addr);
+
+    for i in 0usize..2 {
+        println!("making request {}/2", i + 1);
+        let url = Url::parse(&format!("http://{}/foo", peer_addr)).unwrap();
+        let req = Request::new(Method::Get, url);
+        let res = client::connect(stream.clone(), req).await?;
+        println!("{:?}", res);
     }
+    Ok(())
 }

examples/server.rs

@@ -1,83 +1,38 @@
-use std::pin::Pin;
-use std::str::FromStr;
-use std::sync::Arc;
-
-use async_h1::server;
-use async_std::io::{self, Read, Write};
-use async_std::net::{self, TcpStream};
+use async_std::net::{TcpStream, TcpListener};
 use async_std::prelude::*;
-use async_std::task::{self, Context, Poll};
-use http_types::headers::{HeaderName, HeaderValue};
-use http_types::{Error, Response, StatusCode};
-
-async fn accept(addr: String, stream: TcpStream) -> Result<(), Error> {
-    // println!("starting new connection from {}", stream.peer_addr()?);
-
-    // TODO: Delete this line when we implement `Clone` for `TcpStream`.
-    let stream = Stream(Arc::new(stream));
-
-    server::accept(&addr, stream.clone(), |req| {
-        async move {
-            dbg!(req.method());
-            let mut resp = Response::new(StatusCode::Ok);
-            resp.insert_header(
-                HeaderName::from_str("Content-Type")?,
-                HeaderValue::from_str("text/plain")?,
-            )?;
-            resp.set_body("Hello");
-            // To try chunked encoding, replace `set_body_string` with the following method call
-            // .set_body(io::Cursor::new(vec![
-            //     0x48u8, 0x65, 0x6C, 0x6C, 0x6F, 0x20, 0x77, 0x6F, 0x72, 0x6C, 0x64, 0x21,
-            // ]));
-            Ok(resp)
-        }
-    })
-    .await
-}
-
-fn main() -> Result<(), Error> {
-    task::block_on(async {
-        let listener = net::TcpListener::bind(("127.0.0.1", 8080)).await?;
-        let addr = format!("http://{}", listener.local_addr()?);
-        println!("listening on {}", addr);
-        let mut incoming = listener.incoming();
-
-        while let Some(stream) = incoming.next().await {
-            let stream = stream?;
-            let addr = addr.clone();
-            task::spawn(async {
-                if let Err(err) = accept(addr, stream).await {
-                    eprintln!("{}", err);
-                }
-            });
-        }
-        Ok(())
-    })
-}
-
-#[derive(Clone)]
-struct Stream(Arc<TcpStream>);
-
-impl Read for Stream {
-    fn poll_read(
-        self: Pin<&mut Self>,
-        cx: &mut Context,
-        buf: &mut [u8],
-    ) -> Poll<io::Result<usize>> {
-        Pin::new(&mut &*self.0).poll_read(cx, buf)
+use async_std::task;
+use http_types::{Response, StatusCode};
+
+#[async_std::main]
+async fn main() -> http_types::Result<()> {
+    // Open up a TCP connection and create a URL.
+    let listener = TcpListener::bind(("127.0.0.1", 8080)).await?;
+    let addr = format!("http://{}", listener.local_addr()?);
+    println!("listening on {}", addr);
+
+    // For each incoming TCP connection, spawn a task and call `accept`.
+    let mut incoming = listener.incoming();
+    while let Some(stream) = incoming.next().await {
+        let stream = stream?;
+        let addr = addr.clone();
+        task::spawn(async {
+            if let Err(err) = accept(addr, stream).await {
+                eprintln!("{}", err);
+            }
+        });
     }
+    Ok(())
 }
 
-impl Write for Stream {
-    fn poll_write(self: Pin<&mut Self>, cx: &mut Context, buf: &[u8]) -> Poll<io::Result<usize>> {
-        Pin::new(&mut &*self.0).poll_write(cx, buf)
-    }
-
-    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context) -> Poll<io::Result<()>> {
-        Pin::new(&mut &*self.0).poll_flush(cx)
-    }
-
-    fn poll_close(self: Pin<&mut Self>, cx: &mut Context) -> Poll<io::Result<()>> {
-        Pin::new(&mut &*self.0).poll_close(cx)
-    }
+// Take a TCP stream, and convert it into sequential HTTP request / response pairs.
+async fn accept(addr: String, stream: TcpStream) -> http_types::Result<()> {
+    println!("starting new connection from {}", stream.peer_addr()?);
+    async_h1::accept(&addr, stream.clone(), |_req| async move {
+        let mut res = Response::new(StatusCode::Ok);
+        res.insert_header("Content-Type", "text/plain")?;
+        res.set_body("Hello");
+        Ok(res)
+    })
+    .await?;
+    Ok(())
 }

src/check.rs

@@ -18,6 +18,7 @@ use crate::date::fmt_http_date;
 use crate::MAX_HEADERS;
 
 /// An HTTP encoder.
+#[doc(hidden)]
 #[derive(Debug)]
 pub struct Encoder {
     /// Keep track how far we've indexed into the headers + body.
@@ -48,7 +49,7 @@ impl Encoder {
     }
 }
 
-/// Send an HTTP request over a stream.
+/// Opens an HTTP/1.1 connection to a remote host.
 pub async fn connect<RW>(mut stream: RW, req: Request) -> Result<Response, Error>
 where
     RW: Read + Write + Send + Sync + Unpin + 'static,
@@ -65,7 +66,8 @@ where
 }
 
 /// Encode an HTTP request on the client.
-pub async fn encode(req: Request) -> Result<Encoder, Error> {
+#[doc(hidden)]
+async fn encode(req: Request) -> Result<Encoder, Error> {
     let mut buf: Vec<u8> = vec![];
 
     let mut url = req.url().path().to_owned();
@@ -132,6 +134,7 @@ pub async fn encode(req: Request) -> Result<Encoder, Error> {
 }
 
 /// Decode an HTTP response on the client.
+#[doc(hidden)]
 pub async fn decode<R>(reader: R) -> Result<Response, Error>
 where
     R: Read + Unpin + Send + Sync + 'static,

src/client.rs

@@ -38,6 +38,7 @@ pub struct HttpDate {
 /// Supports the preferred IMF-fixdate and the legacy RFC 805 and
 /// ascdate formats. Two digit years are mapped to dates between
 /// 1970 and 2069.
+#[allow(dead_code)]
 pub(crate) fn parse_http_date(s: &str) -> Result<SystemTime, Error> {
     s.parse::<HttpDate>().map(|d| d.into())
 }

src/date.rs

@@ -24,8 +24,71 @@
 //!
 //! # Example
 //!
+//! __HTTP client__
+//!
+//! ```no_run
+//! use async_h1::client;
+//! use async_std::net::{TcpStream};
+//! use http_types::{Error, Method, Request, Url};
+//! 
+//! #[async_std::main]
+//! async fn main() -> Result<(), Error> {
+//!     let stream = TcpStream::connect("127.0.0.1:8080").await?;
+//!     let peer_addr = stream.peer_addr()?;
+//!     println!("connecting to {}", peer_addr);
+//! 
+//!     for i in 0usize..2 {
+//!         println!("making request {}/2", i + 1);
+//!         let url = Url::parse(&format!("http://{}/foo", peer_addr)).unwrap();
+//!         let req = Request::new(Method::Get, dbg!(url));
+//!         let res = client::connect(stream.clone(), req).await?;
+//!         println!("{:?}", res);
+//!     }
+//!     Ok(())
+//! }
 //! ```
-//! // tbi
+//!
+//! __HTTP Server__
+//!
+//! ```no_run
+//! use async_std::net::{TcpStream, TcpListener};
+//! use async_std::prelude::*;
+//! use async_std::task;
+//! use http_types::{Response, StatusCode};
+//! 
+//! #[async_std::main]
+//! async fn main() -> http_types::Result<()> {
+//!     // Open up a TCP connection and create a URL.
+//!     let listener = TcpListener::bind(("127.0.0.1", 8080)).await?;
+//!     let addr = format!("http://{}", listener.local_addr()?);
+//!     println!("listening on {}", addr);
+//! 
+//!     // For each incoming TCP connection, spawn a task and call `accept`.
+//!     let mut incoming = listener.incoming();
+//!     while let Some(stream) = incoming.next().await {
+//!         let stream = stream?;
+//!         let addr = addr.clone();
+//!         task::spawn(async {
+//!             if let Err(err) = accept(addr, stream).await {
+//!                 eprintln!("{}", err);
+//!             }
+//!         });
+//!     }
+//!     Ok(())
+//! }
+//! 
+//! // Take a TCP stream, and convert it into sequential HTTP request / response pairs.
+//! async fn accept(addr: String, stream: TcpStream) -> http_types::Result<()> {
+//!     println!("starting new connection from {}", stream.peer_addr()?);
+//!     async_h1::accept(&addr, stream.clone(), |_req| async move {
+//!         let mut res = Response::new(StatusCode::Ok);
+//!         res.insert_header("Content-Type", "text/plain")?;
+//!         res.set_body("Hello");
+//!         Ok(res)
+//!     })
+//!     .await?;
+//!     Ok(())
+//! }
 //! ```
 
 // #![forbid(unsafe_code, rust_2018_idioms)]
@@ -36,12 +99,12 @@
 /// The maximum amount of headers parsed on the server.
 const MAX_HEADERS: usize = 128;
 
-pub use check::check;
-
-mod check;
+mod server;
+mod chunked;
+mod date;
 
+#[doc(hidden)]
 pub mod client;
-pub mod server;
 
-mod chunked;
-mod date;
+pub use client::connect;
+pub use server::accept;

src/lib.rs

@@ -20,7 +20,7 @@ use crate::MAX_HEADERS;
 const CR: u8 = b'\r';
 const LF: u8 = b'\n';
 
-/// Parse an incoming HTTP connection.
+/// Accept a new incoming HTTP/1.1 connection.
 ///
 /// Supports `KeepAlive` requests by default.
 pub async fn accept<RW, F, Fut>(addr: &str, mut io: RW, endpoint: F) -> http_types::Result<()>

src/server.rs

@@ -22,10 +22,12 @@ pub struct TestCase {
 }
 
 impl TestCase {
+    #[allow(dead_code)]
     pub async fn new_server(request_file_path: &str, response_file_path: &str) -> TestCase {
         Self::new(Direction::Server, request_file_path, response_file_path).await
     }
 
+    #[allow(dead_code)]
     pub async fn new_client(request_file_path: &str, response_file_path: &str) -> TestCase {
         Self::new(Direction::Client, request_file_path, response_file_path).await
     }

tests/common/mod.rs

@@ -1,4 +1,3 @@
-use async_h1::server;
 use async_std::io::Cursor;
 use async_std::prelude::*;
 use common::TestCase;
@@ -11,7 +10,7 @@ async fn test_basic_request() {
     let case = TestCase::new_server("fixtures/request1.txt", "fixtures/response1.txt").await;
     let addr = "http://example.com";
 
-    server::accept(addr, case.clone(), |_req| async {
+    async_h1::accept(addr, case.clone(), |_req| async {
         let mut resp = Response::new(StatusCode::Ok);
         resp.set_body("");
         Ok(resp)
@@ -31,7 +30,7 @@ async fn test_chunked_basic() {
     .await;
     let addr = "http://example.com";
 
-    server::accept(addr, case.clone(), |_req| async {
+    async_h1::accept(addr, case.clone(), |_req| async {
         let mut resp = Response::new(StatusCode::Ok);
         resp.set_body(Body::from_reader(
             Cursor::new(b"Mozilla")
@@ -57,7 +56,7 @@ async fn test_chunked_echo() {
     .await;
     let addr = "http://example.com";
 
-    server::accept(addr, case.clone(), |req| async {
+    async_h1::accept(addr, case.clone(), |req| async {
         let mut resp = Response::new(StatusCode::Ok);
         let ct = req.content_type();
         let body: Body = req.into();