Added documentation & print statements to redis examples

README.md

@@ -9,19 +9,77 @@ The _WebAssembly Secure Capabilities Connector_ (waSCC) host library allows cons
 
 For more information on concepts, architecture, and tutorials, check out [wascc.dev](https://wascc.dev).
 
-## Examples
+## Tutorials
 
-To run the examples, simply issue the following command (assuming you have the latest version of Rust installed) from the root `wascc-host` directory:
+- [Build your first actor](https://wascc.dev/tutorials/first-actor/)
+- [Create a capability provider](https://wascc.dev/tutorials/native-provider/)
+
+## Building the `wascc-host` binary
+
+To build the optional `wascc-host` binary, run the following command from the project root:
+
+```
+$ cargo build --bin wascc-host --features "bin manifest"
+```
+
+## Running the examples
+
+To run the examples, issue the following command from the root `wascc-host` directory:
 
 ```
-$ RUST_LOG=wascc_host=info cargo run --example [example name]
+$ cargo run --example [example name]
 ```
 
-Where the example name is the name (without the `.rs`) of any of the examples in the examples folder.
+Where the example name is the name (without the `.rs`) of any of the examples in the examples folder. The examples use `env_logger` so you can adjust log levels with the `RUST_LOG` environment variable
+
+e.g.
+
+```
+$ RUST_LOG=wascc_host=trace cargo run --example kvcounter
+```
+
+## Prerequisites
+
+- The latest version of Rust.
+- For some examples (subscriber, lattice, et al), you will need an instance of [NATS](https://nats.io) running locally.
+- For some examples (kvcounter, replace, start_stop, et al), you will need [Redis](https://redis.io/) running locally on the default port.
+- For the [`lattice`](https://wascc.dev/docs/lattice/overview/) examples, in addition to the local [NATS](https://nats.io) server you will need to build `wascc-host` with the `lattice` feature.
+
+**NOTE** - All of the rust examples use _native_ capability providers, and therefore utilize the linux dynamic libraries (`.so` files). To use these examples on a Mac, you will need to manully build Mac dynamic libraries (`.dylib` files) and modify the examples to read those files instead.
+
+## FAQ
+
+### The examples don't do anything
+
+Some examples don't produce interesting output by default, they create servers or perform other invisible tasks. Try increasing the log output by setting the `RUST_LOG` environment variable (e.g. `RUST_LOG=wascc_host cargo run ...`) and tailing logs for related services like redis or nats-server.
+
+### I'm getting the error: "no suitable image found"
+
+The pre-compiled libraries included in `./examples/.assets` don't work for your system. See the note in [prerequisites](#prerequisites). You will need to clone the repository for the associated provider and compile it manually. For example, to build a compatible version of "libwascc_httpsrv.so" on a Mac:
+
+- clone [[email protected]:wascc/http-server-provider.git](https://github.com/wascc/http-server-provider)
+- run `cargo build` in the cloned repository
+- modify the example, replacing `"libwascc_httpsrv.so"` with `"./http-server-provider/target/debug/libwascc_httpsrv.dylib"`
+
+### The lattice example fails with "waSCC Host Error: Attempted bus call for wasmbus.provider.wascc.http_server.default with no subscribers"
+
+You need to build `wascc-host` with the `lattice` feature:
+
+```
+$ cargo build --bin wascc-host --features "bin manifest lattice"
+```
+
+### I'm getting the error: "Failed to establish TCP connection: Connection refused"
+
+You are probably trying to run an example that depends on [NATS](https://nats.io) without a local nats-server. Check that you have `nats-server` running on the default port or change the example to point to a running NATS server.
+
+### The redis example returns "Failed to handle request"
+
+The example can not connect to a redis server. Ensure your local server is running on the default port or change the example source to point to a running redis server.
 
-**Pre-Requisites** - For the `subscriber` example, you will need an instance of [NATS](https://nats.io) running locally. For the `kvcounter` example, you will need **Redis** running locally on the default port.
+### I'm getting an error: target `[example]` in package `wascc-host` requires the features: `[feature]`
 
-**NOTE** - All of these examples use _native_ capability providers, and therefore utilize the linux dynamic libraries (`.so` files). To use these examples on a Mac, you will need to manully build Mac dynamic libraries (`.dylib` files) and modify the examples to read those files instead.
+Some examples require optional features of `wascc-host`. Enable the specified feature to proceed, e.g. `cargo run --example kvcounter_manifest --features=manifest`. Cargo's output will give you the exact flag to add.
 
 ## waSCC on Kubernetes
 

examples/kvcounter.rs

@@ -27,6 +27,8 @@ fn main() -> std::result::Result<(), Box<dyn std::error::Error + Send + Sync>> {
         http_config(),
     )?;
 
+    println!("**> curl localhost:8081/counter1 to test");
+
     std::thread::park();
 
     Ok(())

examples/kvcounter_manifest.rs

@@ -17,6 +17,8 @@ fn main() -> std::result::Result<(), Box<dyn std::error::Error + Send + Sync>> {
         true,
     )?)?;
 
+    println!("**> curl localhost:8081/counter1 to test");
+
     std::thread::park();
     Ok(())
 }