Improve module structure, reorganize exports, add doc comments, update README.md

Signed-off-by: declark1 <[email protected]>

Author: declark1

Cargo.lock

@@ -1,31 +1,36 @@
 # mocktail
-
-mocktail is a minimal framework for mocking HTTP and gRPC services in Rust with support for streaming.
-
-<!-- [![Crates.io](https://img.shields.io/crates/v/mocktail)](https://crates.io/crates/mocktail)
+[![Crates.io](https://img.shields.io/crates/v/mocktail)](https://crates.io/crates/mocktail)
 [![Documentation](https://docs.rs/mocktail/badge.svg)](https://docs.rs/mocktail)
-[![Crates.io](https://img.shields.io/crates/l/mocktail)](LICENSE) -->
+[![Crates.io](https://img.shields.io/crates/l/mocktail)](LICENSE)
+
+mocktail is a **minimal** crate for mocking HTTP and gRPC servers in Rust with support for streaming.
 
 # Table of contents
 * [Features](#features)
-* [Usage](#usage)
+* [Getting Started](#getting-started)
 * [Examples](#examples)
 
 # Features
 - Mocks HTTP and gRPC servers
 - Mocks defined in Rust using a simple, ergonomic API
 - Supports HTTP streaming
 - Supports gRPC unary, client-streaming, server-streaming, and bidirectional-streaming methods
-- Performs matching using built-in matchers or custom matchers
+- Match requests to mock responses using built-in matchers or custom matchers
 
-# Usage
+# Getting Started
 1. Add `mocktail` to `Cargo.toml` as a development dependency:
     ```toml
     [dev-dependencies]
-    mocktail = { git = "https://github.com/IBM/mocktail.git", version = "0.2.0-alpha" }
+    mocktail = { git = "https://github.com/IBM/mocktail.git", version = "0.2.1-alpha" }
     ```
 
-2. See [mocktail-tests](/mocktail-tests/) crate for usage examples.
+2. For now, see [examples](/mocktail-tests/tests/examples) in the `mocktail-tests` crate. Additional documentation coming soon.
 
 # Examples
-See [mocktail-tests](/mocktail-tests/) crate.
+See [examples](/mocktail-tests/tests/examples) in the `mocktail-tests` crate.
+
+# Related projects
+This crate takes inspiration from other great mocking libraries including:
+- [wiremock](https://github.com/wiremock/wiremock)
+- [wiremock-rs](https://github.com/LukeMathWalker/wiremock-rs)
+- [httpmock](https://github.com/alexliesenfeld/httpmock)

README.md

@@ -1,6 +1,6 @@
 [package]
 name = "mocktail"
-version = "0.2.0-alpha"
+version = "0.2.1-alpha"
 edition = "2021"
 authors = ["Dan Clark"]
 description = "HTTP & gRPC server mocking for Rust"

mocktail/Cargo.toml

@@ -1,12 +1,16 @@
+//! Mock body
 use std::{collections::vec_deque, convert::Infallible, pin::Pin, task::Poll};
 
 use bytes::{Buf, Bytes};
 use futures::Stream;
 use http_body::Frame;
 
-use crate::{buf_list::BufList, ext::MessageExt};
+use crate::ext::MessageExt;
 
-/// A mock body.
+mod buf_list;
+use buf_list::BufList;
+
+/// The body of a mock request or response.
 #[derive(Default, Debug, Clone)]
 pub struct Body {
     bufs: BufList,

mocktail/src/body.rs

@@ -1,3 +1,4 @@
+//! Extension traits
 use bytes::{BufMut, Bytes, BytesMut};
 use http::status::InvalidStatusCode;
 use prost::Message;

mocktail/src/buf_list.rs mocktail/src/body/buf_list.rs

@@ -1,4 +1,5 @@
-/// A representation of HTTP headers.
+//! Headers
+/// Represents HTTP headers.
 #[derive(Default, Debug, Clone, PartialEq)]
 pub struct Headers(Vec<(HeaderName, HeaderValue)>);
 
@@ -145,6 +146,7 @@ impl From<Headers> for tonic::metadata::MetadataMap {
     }
 }
 
+/// Represents a HTTP header name.
 #[derive(Default, Debug, Clone, PartialEq)]
 pub struct HeaderName(String);
 
@@ -210,6 +212,7 @@ impl From<&http::HeaderName> for HeaderName {
     }
 }
 
+/// Represents a HTTP header value.
 #[derive(Default, Debug, Clone, PartialEq)]
 pub struct HeaderValue(String);
 

mocktail/src/ext.rs

@@ -1,34 +1,34 @@
 #![doc = include_str!("../README.md")]
-mod body;
-pub use body::Body;
+pub mod body;
 mod headers;
-pub use headers::*;
-mod matchers;
-pub use matchers::*;
+pub use headers::{HeaderName, HeaderValue, Headers};
+pub mod matchers;
 mod mock;
 pub use mock::Mock;
+pub mod mock_builder;
 mod mock_set;
 pub use mock_set::MockSet;
 mod request;
-pub use request::Request;
+pub use request::{Method, Request};
 mod response;
 pub use response::{Response, StatusCode};
-mod when;
-pub use when::When;
-mod then;
-pub use then::Then;
-mod server;
-pub use server::MockServer;
-mod buf_list;
-mod ext;
-mod service;
+pub mod server;
 pub mod prelude {
     pub use crate::{
-        matchers::*, Body, HeaderName, HeaderValue, Headers, Mock, MockServer, MockSet, Request,
-        Response, StatusCode, Then, When,
+        body::Body,
+        headers::{HeaderName, HeaderValue, Headers},
+        matchers::*,
+        mock::Mock,
+        mock_set::MockSet,
+        request::{Method, Request},
+        response::{Response, StatusCode},
+        server::MockServer,
     };
 }
+mod ext;
+mod service;
 
+/// Represents errors that can occur while serving mocks.
 #[derive(thiserror::Error, Debug)]
 pub enum Error {
     #[error("invalid: {0}")]

mocktail/src/headers.rs

@@ -1,3 +1,4 @@
+//! Mock request matchers
 use super::{body::Body, headers::Headers, request::Request};
 use crate::request::Method;
 use std::cmp::Ordering;

mocktail/src/lib.rs

@@ -1,4 +1,10 @@
-use crate::{Matcher, Request, Response, Then, When};
+//! Mock
+use crate::{
+    matchers::Matcher,
+    mock_builder::{Then, When},
+    request::Request,
+    response::Response,
+};
 
 const DEFAULT_PRIORITY: u8 = 5;
 

mocktail/src/matchers.rs

@@ -0,0 +1,5 @@
+//! Mock builder types
+mod then;
+pub use then::Then;
+mod when;
+pub use when::When;

mocktail/src/mock.rs

@@ -1,3 +1,4 @@
+//! Then
 use std::{cell::Cell, rc::Rc};
 
 use bytes::Bytes;

mocktail/src/mock_builder.rs

@@ -1,9 +1,11 @@
+//! When
 use std::{cell::Cell, rc::Rc};
 
 use bytes::Bytes;
 
 use crate::{
-    body::Body, headers::Headers, matchers, request::Method, HeaderName, HeaderValue, Matcher,
+    body::Body, headers::HeaderName, headers::HeaderValue, headers::Headers, matchers,
+    matchers::Matcher, request::Method,
 };
 
 /// A request match conditions builder.

mocktail/src/then.rs mocktail/src/mock_builder/then.rs

@@ -1,5 +1,10 @@
-use super::{request::Request, response::Response, Mock};
-use crate::{Then, When};
+//! Mock set
+use crate::{
+    mock::Mock,
+    mock_builder::{Then, When},
+    request::Request,
+    response::Response,
+};
 
 /// A set of mocks.
 #[derive(Default, Debug)]

mocktail/src/when.rs mocktail/src/mock_builder/when.rs

@@ -1,6 +1,7 @@
-use crate::{Body, Headers};
+//! Mock request
+use crate::{body::Body, headers::Headers};
 
-/// A representation of a HTTP request.
+/// Represents a HTTP request.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Request {
     pub method: Method,
@@ -63,7 +64,7 @@ impl Request {
     }
 }
 
-/// A representation of an HTTP method.
+/// Represents a HTTP method.
 #[allow(clippy::upper_case_acronyms)]
 #[derive(Default, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum Method {

mocktail/src/mock_set.rs

@@ -1,9 +1,10 @@
+//! Mock response
 use std::num::NonZeroU16;
 
 use super::{body::Body, headers::Headers};
 use crate::{ext::CodeExt, Error};
 
-/// A representation of a HTTP response.
+/// Represents a HTTP response.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Response {
     pub status: StatusCode,
@@ -73,7 +74,7 @@ impl Default for Response {
     }
 }
 
-/// A representation of a HTTP status code.
+/// Represents a HTTP status code.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct StatusCode(NonZeroU16);
 

mocktail/src/request.rs

@@ -1,3 +1,4 @@
+//! Mock server
 use http_body::Body;
 use hyper::{body::Incoming, service::Service};
 use hyper_util::{
@@ -16,8 +17,11 @@ use tracing::{debug, error, info, warn};
 use url::Url;
 
 use crate::{
+    mock::Mock,
+    mock_builder::{Then, When},
+    mock_set::MockSet,
     service::{GrpcMockService, HttpMockService},
-    Error, Mock, MockSet, Then, When,
+    Error,
 };
 
 /// A mock server.

mocktail/src/response.rs

@@ -1,3 +1,4 @@
+//! Mock services
 pub mod grpc;
 pub use grpc::GrpcMockService;
 pub mod http;

mocktail/src/server.rs

@@ -1,3 +1,4 @@
+//! Mock gRPC service
 use std::{
     convert::Infallible,
     sync::{Arc, RwLock},
@@ -14,8 +15,9 @@ use tokio_stream::wrappers::ReceiverStream;
 use tonic::body::BoxBody;
 use tracing::debug;
 
-use crate::{Headers, MockSet, Request};
+use crate::{headers::Headers, mock_set::MockSet, request::Request};
 
+/// Mock gRPC service.
 #[derive(Debug, Clone)]
 pub struct GrpcMockService {
     pub mocks: Arc<RwLock<MockSet>>,

mocktail/src/service.rs

@@ -1,3 +1,4 @@
+//! Mock HTTP service
 use std::{
     convert::Infallible,
     sync::{Arc, RwLock},
@@ -13,10 +14,11 @@ use tokio::sync::mpsc;
 use tokio_stream::wrappers::ReceiverStream;
 use tracing::debug;
 
-use crate::{MockSet, Request};
+use crate::{mock_set::MockSet, request::Request};
 
 type BoxBody = http_body_util::combinators::BoxBody<Bytes, hyper::Error>;
 
+/// Mock HTTP service.
 #[derive(Debug, Clone)]
 pub struct HttpMockService {
     pub mocks: Arc<RwLock<MockSet>>,