Add an example and more documentation

Author: jtgeibel

examples/server.rs

@@ -0,0 +1,57 @@
+#![deny(warnings, clippy::all)]
+
+use conduit::{Handler, Request, Response};
+use conduit_hyper::Server;
+use conduit_router::RouteBuilder;
+use futures::Future;
+use tokio::runtime;
+
+use std::collections::HashMap;
+use std::io::{Cursor, Error};
+use std::thread::sleep;
+
+fn main() {
+    let app = build_conduit_handler();
+    let addr = ([127, 0, 0, 1], 12345).into();
+    let server = Server::bind(&addr, app).map_err(|e| {
+        eprintln!("server error: {}", e);
+    });
+
+    let mut rt = runtime::Builder::new()
+        // Set the max number of concurrent requests (tokio defaults to 100)
+        .blocking_threads(2)
+        .build()
+        .unwrap();
+    rt.spawn(server);
+    rt.shutdown_on_idle().wait().unwrap();
+}
+
+fn build_conduit_handler() -> impl Handler {
+    let mut router = RouteBuilder::new();
+    router.get("/", endpoint);
+    router.get("/panic", panic);
+    router
+}
+
+fn endpoint(_: &mut dyn Request) -> Result<Response, Error> {
+    let body = "Hello world!";
+
+    sleep(std::time::Duration::from_secs(2));
+
+    let mut headers = HashMap::new();
+    headers.insert(
+        "Content-Type".to_string(),
+        vec!["text/plain; charset=utf-8".to_string()],
+    );
+    headers.insert("Content-Length".to_string(), vec![body.len().to_string()]);
+    Ok(Response {
+        status: (200, "OK"),
+        headers,
+        body: Box::new(Cursor::new(body)),
+    })
+}
+
+fn panic(_: &mut dyn Request) -> Result<Response, Error> {
+    // For now, connection is immediately closed
+    panic!("message");
+}

src/lib.rs

@@ -1,5 +1,61 @@
 #![deny(warnings, clippy::all, missing_debug_implementations)]
 
+//! A wrapper for integrating `hyper 0.12` with a `conduit 0.8` blocking application stack.
+//!
+//! A `conduit::Handler` is allowed to block so the `Server` must be spawned on the (default)
+//! multi-threaded `Runtime` which allows (by default) 100 concurrent blocking threads.  Any excess
+//! requests will asynchronously wait for an available blocking thread.
+//!
+//! # Examples
+//!
+//! Try out the example with `cargo run --example server`.
+//!
+//! Typical usage:
+//!
+//! ```no_run
+//! use conduit::Handler;
+//! use conduit_hyper::Server;
+//! use futures::Future;
+//! use tokio::runtime::Runtime;
+//!
+//! fn main() {
+//!     let a = ();
+//!     let app = build_conduit_handler();
+//!     let addr = ([127, 0, 0, 1], 12345).into();
+//!     let server = Server::bind(&addr, app).map_err(|e| {
+//!         eprintln!("server error: {}", e);
+//!     });
+//!
+//!     let mut rt = Runtime::new().unwrap();
+//!     rt.spawn(server);
+//!     rt.shutdown_on_idle().wait().unwrap();
+//! }
+//!
+//! fn build_conduit_handler() -> impl Handler {
+//!     // ...
+//! #     Endpoint()
+//! }
+//! #
+//! # use std::collections::HashMap;
+//! # use std::error::Error;
+//! # use std::io::Cursor;
+//! #
+//! # use conduit::{Request, Response};
+//! #
+//! # struct Endpoint();
+//! #
+//! # impl Handler for Endpoint {
+//! #     fn call(&self, _: &mut dyn Request) -> Result<Response, Box<dyn Error + Send>> {
+//! #         let body = "";
+//! #         Ok(Response {
+//! #             status: (200, "OK"),
+//! #             headers: HashMap::new(),
+//! #             body: Box::new(Cursor::new(body)),
+//! #         })
+//! #     }
+//! # }
+//! ```
+
 #[cfg(test)]
 mod tests;