Update book (#28)

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

Author: declark1

book/src/SUMMARY.md

@@ -20,7 +20,15 @@
     - [Priority](./concepts/priority.md)
     - [Mock Server](./concepts/mock-server.md)
 - [Defining Mocks](./defining-mocks.md)
-- [Miscellaneous](./misc.md)
-    - [FAQ](./faq.md)
-    - [CHANGELOG](./CHANGELOG.md)
-    - [Contributing](./contributing.md)
+    - [Example: HTTP Simple](./defining-mocks/example-http-simple.md)
+    - [Example: HTTP Streaming (ndjson)](./defining-mocks/example-http-streaming-ndjson.md)
+    - [Example: HTTP Streaming (SSE)](./defining-mocks/example-http-streaming-sse.md)
+    - [Example: gRPC Unary](./defining-mocks/example-grpc-unary.md)
+    - [Example: gRPC Client Streaming](./defining-mocks/example-grpc-client-streaming.md)
+    - [Example: gRPC Server Streaming](./defining-mocks/example-grpc-server-streaming.md)
+    - [Example: gRPC Bidi Streaming](./defining-mocks/example-grpc-bidi-streaming.md)
+    - [Example: Custom Matcher](./defining-mocks/example-custom-matcher.md)
+---
+[FAQ](./FAQ.md)
+[CHANGELOG](./CHANGELOG.md)
+[CONTRIBUTING](./CONTRIBUTING.md)

book/src/concepts/matchers/any.md

@@ -5,4 +5,13 @@
 Matches any request. Should not be combined with other matchers.
 
 ### `When` method
-- `any()`
+#### `any()`
+Matches any request.
+
+Example:
+```rust
+let mock = Mock::new(|when, then| {
+    when.any();
+    then.ok();
+})
+```

book/src/concepts/matchers/body.md

@@ -5,13 +5,98 @@
 Matches a request by body.
 
 ### `When` methods:
-- `body()` *(primary)*
-- `empty()`
-- `bytes()`
-- `bytes_stream()`
-- `text()`
-- `text_stream()`
-- `json()`
-- `json_lines_stream()`
-- `pb()`
-- `pb_stream()`
+
+#### `body(body)` *(primary)*
+
+#### `empty()`
+An empty body.
+
+Example:
+```rust
+let mock = Mock::new(|when, then| {
+    when.empty();
+    then.ok();
+})
+```
+#### `bytes(body)`
+A raw bytes body. `body` is a type implementing `Into<Bytes>`.
+```rust
+let mock = Mock::new(|when, then| {
+    when.bytes("hello".as_bytes());
+    then.ok();
+})
+```
+#### `bytes_stream(messages)`
+A raw bytes streaming body. `messages` is an iterator of messages implementing `Into<Bytes>`.
+```rust
+let mock = Mock::new(|when, then| {
+    when.bytes_stream([
+        "msg1".as_bytes(), 
+        "msg2".as_bytes(), 
+        "msg3".as_bytes(),
+    ]);
+    then.ok();
+})
+```
+#### `text(body)`
+A text body. `body` is a type implementing `Into<String>`.
+```rust
+let mock = Mock::new(|when, then| {
+    when.text("hello");
+    then.ok();
+})
+```
+#### `text_stream(messages)`
+A text streaming body. `messages` is an iterator of `String` messages.
+```rust
+let mock = Mock::new(|when, then| {
+    when.text_stream([
+        "msg1", 
+        "msg2", 
+        "msg3"
+    ]);
+    then.ok();
+})
+```
+#### `json(body)`
+A json body. `body` is a type implementing `serde::Serialize`.
+```rust
+use serde_json::json;
+let mock = Mock::new(|when, then| {
+    when.json(json!({"message": "hello"}));
+    then.ok();
+})
+```
+#### `json_lines_stream(messages)`
+A newline delimited json streaming body. `messages` is an iterator of messages implementing `serde::Serialize`.
+```rust
+use serde_json::json;
+let mock = Mock::new(|when, then| {
+    when.json_lines_stream([
+        json!({"message": "msg1"}), 
+        json!({"message": "msg2"}), 
+        json!({"message": "msg3"}),
+    ]);
+    then.ok();
+})
+```
+#### `pb(body)`
+A protobuf body. `body` is a prost-generated type implementing `prost::Message`.
+```rust
+let mock = Mock::new(|when, then| {
+    when.pb(ExampleMessage { message: "msg" });
+    then.ok();
+})
+```
+#### `pb_stream(messages)`
+A protobuf streaming body. `messages` is an iterator of messages implementing `prost::Message`.
+```rust
+let mock = Mock::new(|when, then| {
+    when.pb_stream([
+        ExampleMessage { message: "msg1" }, 
+        ExampleMessage { message: "msg2" }, 
+        ExampleMessage { message: "msg3" },
+    ]);
+    then.ok();
+})
+```

book/src/concepts/matchers/custom.md

@@ -5,4 +5,5 @@
 Matches a request by a custom `Matcher` implementation.
 
 ### `When` method:
-- `matcher()`
+#### `matcher(matcher)`
+Custom matcher. `matcher` is type implementing `Matcher`.

book/src/concepts/matchers/headers.md

@@ -5,25 +5,29 @@
 Matches a request by headers. Returns `true` if the request headers are a *superset* of the headers, i.e. contains *at least* all of the headers.
 
 ### `When` method:
-- `headers()`
+#### `headers(headers)`
+Headers. `headers` is an iterator of name-value pairs.
 
 ## Headers Exact
 
 Matches a request by exact headers. Returns `true` if the request headers are *equal to* the headers.
 
 ### `When` method:
-- `headers_exact()`
+#### `headers_exact(headers)`
+Exact headers. `headers` is an iterator of name-value pairs.
 
 ## Header
 
 Matches a request by header. Returns `true` if the request contains a header *equal to* the header.
 
 ### `When` method:
-- `header()`
+#### `header(name, value)`
+Header. `name` and `value` are types implementing `Into<String>`.
 
 ## Header Exists
 
 Matches a request by header exists. Returns `true` if the request contains a header with the header name.
 
 ### `When` method:
-- `header_exists()`
+#### `header_exists(name)`
+Header exists. `name` is a type implementing `Into<String>`.

book/src/concepts/matchers/method.md

@@ -5,9 +5,60 @@
 Matches a request by HTTP method.
 
 ### `When` methods:
-- `method()` *(primary)*
-- `get()`
-- `post()`
-- `put()`
-- `head()`
-- `delete()`
+#### `method(method)` *(primary)*
+HTTP method.
+
+#### `get()`
+HTTP GET method.
+
+Example:
+```rust
+let mock = Mock::new(|when, then| {
+    when.get();
+    then.ok();
+})
+```
+
+#### `post()`
+HTTP POST method.
+
+Example:
+```rust
+let mock = Mock::new(|when, then| {
+    when.post();
+    then.ok();
+})
+```
+
+#### `put()`
+HTTP PUT method.
+
+Example:
+```rust
+let mock = Mock::new(|when, then| {
+    when.put();
+    then.ok();
+})
+```
+
+#### `head()`
+HTTP HEAD method.
+
+Example:
+```rust
+let mock = Mock::new(|when, then| {
+    when.head();
+    then.ok();
+})
+```
+
+#### `delete()`
+HTTP DELETE method.
+
+Example:
+```rust
+let mock = Mock::new(|when, then| {
+    when.delete();
+    then.ok();
+})
+```

book/src/concepts/matchers/path.md

@@ -5,11 +5,30 @@
 Matches a request by path.
 
 ### `When` method:
-- `path()`
+
+#### `path(path)`
+Path.
+
+Example:
+```rust
+let mock = Mock::new(|when, then| {
+    when.path("/path");
+    then.ok();
+})
+```
 
 ## Path Prefix
 
 Matches a request by path prefix. Returns `true` if the request path starts with prefix.
 
 ### `When` method:
-- `path_prefix()`
+#### `path_prefix(prefix)`
+Path prefix.
+
+Example:
+```rust
+let mock = Mock::new(|when, then| {
+    when.path("/p");
+    then.ok();
+})
+```

book/src/concepts/matchers/query-params.md

@@ -5,18 +5,21 @@
 Matches a request by query params. Returns `true` if the request query params are *equal to* the query params.
 
 ### `When` method:
-- `query_params()`
+#### `query_params(params)`
+Query params. `params` is an iterator of key-value pairs.
 
 ## Query Param
 
 Matches a request by query param. Returns `true` if the request contains a query param *equal to* the query param.
 
 ### `When` method:
-- `query_param()`
+#### `query_param(key, value)`
+Query param. `key` and `value` are types implementing `Into<String>`.
 
 ## Query Param Exists
 
 Matches a request by query param exists. Returns `true` if the request contains a query param with the query key.
 
 ### `When` method:
-- `query_param_exists()`
+#### `query_param_exists(key)`
+Query param exists. `key` is a type implementing `Into<String>`.

book/src/defining-mocks.md

@@ -1,34 +1,35 @@
 # Defining Mocks
 
-Mocks are defined in Rust using a simple, ergonomic builder-like API. See [Mock Builder](./concepts/mock-builder.md) for additional details.
+Mocks are defined in Rust using a simple, ergonomic [builder-like API](./concepts/mock-builder.md).
 
-You can define your mocks first, then create a mock server with your mock set.
+You can define your mocks first, then create a mock server with your mock set:
 ```rust
-    // Build and insert mocks using MockSet::mock()
+    // Create a mock set
     let mut mocks = MockSet::new();
+    // Build and insert a mock
     mocks.mock(|when, then| {
         when.get().path("/health");
         then.text("healthy!");
     });
-    // Alternatively, use Mock::new() and MockSet::insert()
+    // Alternatively, Mock::new() and mocks.insert(mock)
 
     // Create mock server with the mock set
     let mut server = MockServer::new("example").with_mocks(mocks);
     server.run().await?;
 ```
 
-Alternatively, you can create a mock server with a default (empty) mock set and register mocks directly to the server.
+Or, you can create a mock server with a default empty mock set and register mocks directly to the server:
 ```rust
-    // Create mock server (with a default empty mock set)
+    // Create mock server
     let mut server = MockServer::new("example");
     server.run().await?;
 
-    // Register mocks to the server directly using MockServer::mock()
+    // Build and insert a mock to the server's mock set
     server.mock(|when, then| {
         when.get().path("/health");
         then.text("healthy!");
     });
-    // Alternatively, use Mock::new() and MockServer::mocks().insert()
+    // Alternatively, use Mock::new() and server.mocks.insert(mock)
 ```
 
 

book/src/defining-mocks/example-custom-matcher.md

@@ -0,0 +1 @@
+# Example: Custom Matcher

book/src/defining-mocks/example-grpc-bidi-streaming.md

@@ -0,0 +1,3 @@
+# Example: gRPC Bidi Streaming
+
+TODO

book/src/defining-mocks/example-grpc-client-streaming.md

@@ -0,0 +1,3 @@
+# Example: gRPC Client Streaming
+
+TODO

book/src/defining-mocks/example-grpc-server-streaming.md

@@ -0,0 +1,3 @@
+# Example: gRPC Server Streaming
+
+TODO

book/src/defining-mocks/example-grpc-unary.md

@@ -0,0 +1,3 @@
+# Example: gRPC Unary
+
+TODO

book/src/defining-mocks/example-http-simple.md

@@ -0,0 +1,3 @@
+# Example: HTTP Simple
+
+TODO