doc updates (#62)

Cargo.toml

@@ -5,3 +5,7 @@ resolver = "2"
 [workspace.package]
 edition = "2021"
 rust-version = "1.73.0"
+authors = ["Rohan Krishnaswamy <[email protected]>"]
+description = "Kiwi is a fast and extensible WebSocket gateway for real-time event sources"
+repository = "https://github.com/rkrishn7/kiwi"
+license = "MIT"

examples/README.md

@@ -0,0 +1,7 @@
+# Examples of running Kiwi 🥝
+
+This directory contains examples of running Kiwi in various configurations. Each example is self-contained and includes a `README.md` file with instructions on how to run it.
+
+## Examples
+
+- [Intercept (Simple)](./intercept-simple): A simple example that demonstrates how to write WASM hooks using the Kiwi SDK and load them into the Kiwi runtime.

examples/intercept-simple/README.md

@@ -1,9 +1,73 @@
-TODO: Add docs
+# Intercept (Simple)
 
-Cmd:
+This example highlights how to write a simple WebAssembly (WASM) hook using the Kiwi SDK and load it into the Kiwi runtime. The hook is a simple plugin that intercepts all all events emitted by counter sources and discards them if they are odd.
 
+- [Intercept (Simple)](#intercept-simple)
+  - [Running the Example](#running-the-example)
+    - [Prerequisites](#prerequisites)
+    - [Building the WASM Hook](#building-the-wasm-hook)
+    - [Running Kiwi](#running-kiwi)
+    - [Interacting with Kiwi](#interacting-with-kiwi)
+  - [Recap](#recap)
+
+## Running the Example
+
+> **NOTE**: The commands in this example should be run from this directory (`examples/intercept-simple`).
+
+### Prerequisites
+
+- [Rust](https://www.rust-lang.org/tools/install) - The Rust toolchain is required to build the WASM hook.
+- [Docker](https://docs.docker.com/get-docker/) - Docker is utilized in this example as a simple way to run Kiwi.
+- [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) - The Node.js package manager is required to install [wscat](https://www.npmjs.com/package/wscat), a WebSocket client used to interact with the Kiwi server.
+
+### Building the WASM Hook
+
+The `wasm32-wasi` target is required to build the WASM hook. This target is not installed by default, so it must be added using the following command:
+
+```sh
+rustup target add wasm32-wasi
 ```
+
+Once the target is installed, the WASM hook can be built using the following command:
+
+```sh
+cargo build --target wasm32-wasi
+```
+
+This command will produce the WASM hook at `target/wasm32-wasi/debug/intercept.wasm`.
+
+### Running Kiwi
+
+Now that the WASM hook is built, it can be run with Kiwi. The following command will run Kiwi with the WASM hook and the provided configuration file:
+
+```sh
 docker run -p 8000:8000 -v $(pwd)/kiwi.yml:/etc/kiwi/config/kiwi.yml \
     -v $(pwd)/target/wasm32-wasi/debug/intercept.wasm:/etc/kiwi/hook/intercept.wasm \
-    kiwi:latest
+    ghcr.io/rkrishn7/kiwi:main
 ```
+
+### Interacting with Kiwi
+
+The Kiwi server is now running with the WASM hook loaded. To interact with it, let's go ahead and install [wscat](https://github.com/websockets/wscat):
+
+```sh
+npm install -g wscat
+```
+
+Awesome! Now we can interact with the Kiwi server at `http://localhost:8000`. Let's try it out by subscribing to a counter source and emitting some events. First, let's connect to the server using `wscat`:
+
+```sh
+wscat -c ws://127.0.0.1:8000
+```
+
+Now that we're connected, let's subscribe to the counter source. In the `wscat` terminal, send the following message:
+
+```json
+{"type":"SUBSCRIBE","sourceId":"counter1"}
+```
+
+The server should respond with a message indicating that the subscription was successful. After this, you should start receiving events from the counter source. Note that even though the counter source is emitting all the natural numbers, the WASM hook is intercepting and discarding all odd numbers. Thus, you only see the even numbers in the terminal!
+
+## Recap
+
+This example demonstrated how to write a simple WebAssembly (WASM) hook using the Kiwi SDK and load it into Kiwi for execution.

examples/intercept-simple/src/lib.rs

@@ -1,16 +1,24 @@
+//! A simple intercept hook that discards odd numbers from all counter sources
+
 use kiwi_sdk::hook;
 use kiwi_sdk::types::intercept::{Action, Context, CounterEventCtx, EventCtx};
 
+/// You must use the `#[hook::intercept]` attribute to define an intercept hook.
 #[hook::intercept]
 fn handle(ctx: Context) -> Action {
     match ctx.event {
+        // We only care about counter sources in this example
         EventCtx::Counter(CounterEventCtx {
             source_id: _,
             count,
         }) => {
             if count % 2 == 0 {
+                // Returning `Action::Forward` instructs Kiwi to forward the event
+                // to the associated client.
                 return Action::Forward;
             } else {
+                // Returning `Action::Discard` instructs Kiwi to discard the event,
+                // preventing it from reaching the associated client.
                 return Action::Discard;
             }
         }

src/kiwi-sdk/Cargo.toml

@@ -3,8 +3,9 @@ name = "kiwi-sdk"
 version = "0.1.0"
 edition.workspace = true
 rust-version.workspace = true
-
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+authors.workspace = true
+license.workspace = true
+description = "The Kiwi SDK allows you to write pluggable modules that hook into the Kiwi runtime."
 
 [dependencies]
 kiwi-macro = { path = "./macro" }