sdk: readable clients (no Empty wrapper, no unused error module), documented examples with tests

examples/notes/src/main.rs

@@ -1,6 +1,9 @@
-//! Persistent notes. Each request reads the shared file instead of process memory.
+//! Persistent notes in `/state/notes/notes.json`.
+//! Each call has its own process. The add method locks the file before its read-modify-write operation.
+//! Atomic replacement lets readers observe a complete list without a lock.
 use sausage_plugin::serde_json;
 use sausage_plugin::{Result, lock, rpc, schema, state_dir, write_atomic};
+/// The stateless notes plugin reads its file on each call.
 struct Notes;
 /// Parameters for a new note.
 #[schema]
@@ -31,6 +34,7 @@ impl Notes {
         load()
     }
 }
+/// Read the list, or return an empty list when the file does not exist.
 fn load() -> Result<Vec<String>> {
     match std::fs::read(state_dir().join("notes.json")) {
         Ok(bytes) => Ok(serde_json::from_slice(&bytes)?),
@@ -38,6 +42,43 @@ fn load() -> Result<Vec<String>> {
         Err(e) => Err(e.into()),
     }
 }
+/// Start the SDK transport for notes.
 fn main() {
     sausage_plugin::run(Notes)
 }
+
+/// Tests run in fresh worlds under the WASI test runner.
+#[cfg(test)]
+mod tests {
+    use super::*;
+    /// The core lock protects two sequential additions and their counts.
+    #[sausage_plugin::test]
+    async fn add_appends_and_counts() {
+        assert_eq!(
+            Notes
+                .add(AddParams {
+                    text: "milk".into()
+                })
+                .await
+                .unwrap()
+                .count,
+            1
+        );
+        assert_eq!(
+            Notes
+                .add(AddParams {
+                    text: "eggs".into()
+                })
+                .await
+                .unwrap()
+                .count,
+            2
+        );
+        assert_eq!(Notes.list().unwrap(), ["milk", "eggs"]);
+    }
+    /// A fresh test world has no notes file.
+    #[test]
+    fn list_is_empty_without_a_file() {
+        assert!(Notes.list().unwrap().is_empty());
+    }
+}