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

examples/consumer/imports/notes.json

@@ -28,10 +28,6 @@
           "count"
         ],
         "type": "object"
-      },
-      "Empty": {
-        "description": "Empty parameters for methods without arguments.",
-        "type": "object"
       }
     }
   },
@@ -80,10 +76,7 @@
           "type": "array"
         }
       },
-      "summary": "List all notes, oldest first.",
-      "x-sausage-params": {
-        "$ref": "#/components/schemas/Empty"
-      }
+      "summary": "List all notes, oldest first."
     }
   ],
   "openrpc": "1.2.6",

examples/consumer/imports/secrets.json

@@ -1,10 +1,6 @@
 {
   "components": {
     "schemas": {
-      "Empty": {
-        "description": "Empty parameters for methods without arguments.",
-        "type": "object"
-      },
       "GetParams": {
         "description": "The name of a secret to read.",
         "properties": {
@@ -54,10 +50,7 @@
           "type": "null"
         }
       },
-      "summary": "Open the in-memory vault and publish its endpoint.",
-      "x-sausage-params": {
-        "$ref": "#/components/schemas/Empty"
-      }
+      "summary": "Open the in-memory vault and publish its endpoint."
     }
   ],
   "openrpc": "1.2.6",

examples/consumer/imports/www.json

@@ -1,10 +1,6 @@
 {
   "components": {
     "schemas": {
-      "Empty": {
-        "description": "Empty parameters for methods without arguments.",
-        "type": "object"
-      },
       "StartParams": {
         "description": "The server configuration.",
         "properties": {
@@ -75,10 +71,7 @@
               "type": "integer"
             }
           },
-          "summary": "Count the HTTP requests this server answered.",
-          "x-sausage-params": {
-            "$ref": "#/components/schemas/Empty"
-          }
+          "summary": "Count the HTTP requests this server answered."
         },
         {
           "description": "End this process after the response reaches the client.",
@@ -91,10 +84,7 @@
               "type": "null"
             }
           },
-          "summary": "End this process after the response reaches the client.",
-          "x-sausage-params": {
-            "$ref": "#/components/schemas/Empty"
-          }
+          "summary": "End this process after the response reaches the client."
         }
       ]
     }

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
+        );
+    }
+}