Merge pull request #25 from arindas/docs/0.0.5

doc: adds documentation to prepare for 0.0.5 release
arindas · May 24, 2024 · 32dadc3 · 32dadc3
2 parents 0ea2395 + d363e69
commit 32dadc3
Show file tree

Hide file tree

Showing 17 changed files with 1,790 additions and 195 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -6,7 +6,7 @@ license = "MIT"
 categories = ["web-programming"]
 keywords = ["message-queue", "distributed-systems", "segmented-log", "io-uring"]
 exclude = [".github/", "assets/"]
-version = "0.0.5-rc2"
+version = "0.0.5"
 edition = "2021"
 rust-version = "1.62"
 
@@ -35,7 +35,7 @@ tower-service = "0.3.2"
 num = "0.4.0"
 futures-time = "3.0.0"
 async-io = "1.13.0"
-generational-cache = "0.2.0"
+generational-cache = "0.2.2"
 
 [lib]
 name = "laminarmq"
@@ -55,6 +55,15 @@ bench = false
 rlimit = "0.10.1"
 criterion = { version = "0.5", features = ["html_reports", "async_futures", "async_tokio"] }
 pprof = { version = "0.12", features = ["flamegraph", "criterion"] }
+axum = "0.6.20"
+crc32fast = "1.3.2"
+hyper = "0.14.27"
+serde = { version = "1.0.188", features = ["derive"] }
+tokio = { version = "1.32.0", features = ["rt", "rt-multi-thread", "sync", "net", "fs", "signal"] }
+tower = { version = "0.4.13", features = ["util", "timeout"] }
+tower-http = { version = "0.4.4", features = ["add-extension", "trace"] }
+tracing = "0.1.37"
+tracing-subscriber = { version = "0.3.17", features = ["env-filter"] }
 
 [[bench]]
 name = "commit_log_append"

diff --git a/README.md b/README.md
diff --git a/examples/laminarmq-tokio-commit-log-server/README.md b/examples/laminarmq-tokio-commit-log-server/README.md
@@ -0,0 +1,72 @@
+# laminarmq-tokio-commit-log-server
+
+A simple persistent commit log server using the tokio runtime.
+
+## Endpoints
+
+This server exposes the following HTTP endpoints:
+
+```rust
+.route("/index_bounds", get(index_bounds))  // obtain the index bounds
+.route("/records/:index", get(read))        // obtain the record at given index
+.route("/records", post(append))            // append a new record at the end of the commit log
+
+.route("/rpc/truncate", post(truncate))     // truncate the commit log
+                                            // expects JSON: { "truncate_index": <idx: number> }
+                                            // records starting from truncate_index are removed
+```
+
+## Usage
+
+Run the server as follows:
+
+```sh
+cargo run --example laminarmq-tokio-commit-log-server --release
+```
+
+The server optionally expects an environment variable: `STORAGE_DIRECTORY`.
+
+The default value is:
+
+```rust
+const DEFAULT_STORAGE_DIRECTORY: &str = "./.storage/laminarmq_tokio_commit_log_server/commit_log";
+```
+
+You may specify it as follows:
+
+```sh
+STORAGE_DIRECTORY="<storage directory>" cargo run --release
+```
+
+Once the server is running you may make requests as follows:
+
+```sh
+curl -w "\n" "http://127.0.0.1:3000/index_bounds"
+
+curl -w "\n" --request POST --data "Hello World" "http://127.0.0.1:3000/records"
+curl -w "\n" --request POST --data "Moshi moshi" "http://127.0.0.1:3000/records"
+curl -w "\n" --request POST --data "Bonjour  <3" "http://127.0.0.1:3000/records"
+
+curl -w "\n" "http://127.0.0.1:3000/index_bounds"
+
+curl -w "\n" "http://127.0.0.1:3000/records/1"
+
+curl -w "\n" --header "Content-Type: application/json" --request POST \
+    --data "{\"truncate_index\": 1}" \
+    "http://127.0.0.1:3000/rpc/truncate"
+
+curl -w "\n" "http://127.0.0.1:3000/index_bounds"
+```
+
+Here's what's happening above:
+
+- First request find the index_bounds, (highest_index) is exclusive
+- We append three records with the given data
+- We lookup the current index_bounds after appending to the commit_log
+- We read the record at index 1
+- We truncate the commit_log at index 1. All records starting from index 1 are
+  removed. After this operation the bounds are [0, 1)
+- We lookup the current index_bounds after truncating the commit_log
+
+> Note: The `-w "\n"` flag is for appending a "\n" to the output of curl. This way
+> the output is more readable.