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

examples/consumer/src/main.rs

@@ -1,10 +1,19 @@
 //! Use typed calls from discovered provider documents in `imports/`.
+//! Generated modules own the wire types, so calls need no manual JSON.
+//! The detached HTTP service survives this consumer. Its endpoint refers to that service's process-local state.
 //! Copy fresh documents from `/proc/core/plugins/<provider>/discover.json` after an interface changes.
 use sausage_plugin::{Result, rpc, schema};
 sausage_plugin::import!("notes");
 sausage_plugin::import!("www");
 sausage_plugin::import!("secrets");
+/// Demonstrate typed imports without manual JSON messages.
 struct Consumer;
+/// A note for the imported notes plugin.
+#[schema]
+struct NoteParams {
+    /// The text to append.
+    text: String,
+}
 /// The text and HTTP port for this demonstration.
 #[schema]
 struct DemoParams {
@@ -15,6 +24,10 @@ struct DemoParams {
 }
 #[rpc]
 impl Consumer {
+    /// Add a note through the generated import and return its count.
+    async fn note(&self, p: NoteParams) -> Result<usize> {
+        Ok(notes::add(notes::AddParams { text: p.text }).await?.count as usize)
+    }
     /// Add a note, start a server, and inspect its control endpoint.
     async fn demo(&self, p: DemoParams) -> Result<u64> {
         let added = notes::add(notes::AddParams { text: p.text }).await?;
@@ -42,6 +55,34 @@ impl Consumer {
             .await
     }
 }
+/// Start the SDK transport for this plugin.
 fn main() {
     sausage_plugin::run(Consumer)
 }
+/// Tests demonstrate generated params and calls through the test core.
+#[cfg(test)]
+mod tests {
+    use super::*;
+    /// Generated params retain their wire field names.
+    #[test]
+    fn generated_params_use_text() {
+        let value = sausage_plugin::serde_json::to_value(notes::AddParams {
+            text: "milk".into(),
+        })
+        .unwrap();
+        assert_eq!(value, sausage_plugin::serde_json::json!({"text":"milk"}));
+    }
+    /// A typed import reaches the notes plugin through the test core.
+    #[sausage_plugin::test]
+    async fn imports_notes() {
+        assert_eq!(
+            Consumer
+                .note(NoteParams {
+                    text: "milk".into()
+                })
+                .await
+                .unwrap(),
+            1
+        );
+    }
+}