3 files changed, 32 insertions(+), 14 deletions(-)

M src/client.rs
M src/lib.rs
M src/server.rs

@@ 6,27 6,35 @@ use tokio_codec::{Decoder, Encoder};
 
 const NUL: u8 = b'\0';
 
+/// A parsed SCGI request header with key/value header data, and/or bytes from the raw request body.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub enum SCGIRequest {
-    /// The Vec contains the headers. The BytesMut optionally contains raw byte data to include in
-    /// the request body.
+    /// The Vec contains the headers. The BytesMut optionally contains raw byte data from
+    /// the request body, which may be followed by additional `BodyFragment`s in later calls.
+    /// The `Content-Length` header, required by SCGI, can be used to detect whether to wait for
+    /// additional `BodyFragment`s.
     Request(Vec<(String, String)>, BytesMut),
 
-    /// Additional body fragment(s) to be used for streaming request data.
+    /// Additional body fragment(s), used for streaming fragmented request body data. These should
+    /// only be relevant in cases where the leading `Request` value doesn't contain all of the body.
     BodyFragment(BytesMut),
 }
 
-/// A `Codec` implementation that creates and parses SCGI requests.
+/// A `Codec` implementation that creates SCGI requests for SCGI clients like web servers.
+/// The Encoder accepts `SCGIRequest` objects containing header/body request data and encodes them for
+/// sending to an SCGI server. The Decoder passes through the raw response returned by the SCGI server.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct SCGICodec {}
 
 impl SCGICodec {
-    /// Returns a `SCGIClientCodec` for creating SCGI-format requests.
+    /// Returns a client `SCGICodec` for creating SCGI-format requests for use by SCGI clients
+    /// like web servers.
     pub fn new() -> SCGICodec {
         SCGICodec {}
     }
 }
 
+/// Passes through any response data as-is. To be handled by the requesting client.
 impl Decoder for SCGICodec {
     type Item = BytesMut;
     type Error = io::Error;

@@ 2,11 2,11 @@
 
 //! SCGI request codec for Tokio.
 //!
-//! This crate provides codecs for creating and parsing SCGI requests, for use by web servers to query SCGI services and backend services to serve SCGI endpoints.
-//! Working examples are provided for asynchronous SCGI servers and clients. Tests meanwhile provide examples of invoking the codecs directly.
+//! This crate provides codecs for creating and parsing SCGI requests. Web servers can use this to query SCGI services as clients. Backend services can use this to serve SCGI endpoints to web servers. For example, you can build a backend service in Rust that serves responses over SCGI to a frontend NGINX server. Check the NGINX documentation for info on how to configure SCGI.
+//! Working examples of Tokio-based SCGI servers and clients are provided in the project examples. Tests meanwhile provide examples of invoking the codecs directly.
 
-/// For an SCGI server (usually a backend service): Parses SCGI requests and sends back raw byte responses.
+/// Codec for SCGI servers, such as backend services: Parses SCGI requests and sends back raw byte responses to forward back to querying clients.
 pub mod server;
 
-/// For an SCGI client (usually a web server): Builds SCGI requests and receives raw byte responses.
+/// Codec for SCGI clients, such as web servers: Builds SCGI requests and receives raw byte responses to forward back to querying clients.
 pub mod client;

@@ 12,16 12,21 @@ const MAX_HEADER_STRING_BYTES: usize = 32 * 1024;
 /// is enforced by most web servers.
 const MAX_HEADER_BYTES: usize = 256 * 1024;
 
+/// A parsed SCGI request header with key/value header data, and/or bytes from the raw request body.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub enum SCGIRequest {
-    /// The first Vec contains the headers. The second Vec optionally contains raw byte data from
-    /// the request body.
+    /// The Vec contains the headers. The BytesMut optionally contains raw byte data from
+    /// the request body, which may be followed by additional `BodyFragment`s in later calls.
+    /// The `Content-Length` header, required by SCGI, can be used to detect whether to wait for
+    /// additional `BodyFragment`s.
     Request(Vec<(String, String)>, BytesMut),
 
-    /// Additional body fragment(s) to be used for streaming request data.
+    /// Additional body fragment(s), used for streaming fragmented request body data. These should
+    /// only be relevant in cases where the leading `Request` value doesn't contain all of the body.
     BodyFragment(BytesMut),
 }
 
+/// Internal state while parsing the SCGI request
 #[derive(Clone, Debug, Eq, PartialEq)]
 enum CodecState {
     /// Getting the initial netstring size.


@@ 46,7 51,10 @@ enum CodecState {
     Content,
 }
 
-/// A `Codec` implementation that creates and parses SCGI requests.
+/// A `Codec` implementation that parses SCGI requests for SCGI servers like backend services.
+/// The Decoder parses and returns `SCGIRequest` objects containing header/body request data from an
+/// SCGI client such as a frontend web server. The Encoder passes through the raw response to be sent
+/// back to the SCGI client.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct SCGICodec {
     /// Decoder state. See `CodecState` for transition info.


@@ 69,12 77,14 @@ pub struct SCGICodec {
     next_search_index: usize,
 }
 
+/// Macro for simplifying creation of io::Errors
 macro_rules! io_err {
     ($($arg:tt)*) => (Err(io::Error::new(io::ErrorKind::InvalidData, format!($($arg)+))))
 }
 
 impl SCGICodec {
-    /// Returns a `SCGIServerCodec` for accepting and parsing SCGI-format requests.
+    /// Returns a client `SCGICodec` for accepting and parsing SCGI-format requests by SCGI servers
+    /// like backend services.
     pub fn new() -> SCGICodec {
         SCGICodec {
             decoder_state: CodecState::HeaderSize,