Document examples and add local remote shell endpoint demo

examples/protocol/remote_shell_single_endpoint.rs

@@ -0,0 +1,46 @@
+//! Smallest in-process `RemoteShellLeaf` endpoint example.
+//!
+//! This example hosts exactly one protocol endpoint with exactly one leaf, `RemoteShellLeaf`, and
+//! performs a local introspection request against that leaf. It does not open any sockets or spawn
+//! a shell process, so it is the easiest place to see how the endpoint and leaf metadata fit
+//! together.
+
+#[path = "../../src/leaf/remote_shell/mod.rs"]
+mod remote_shell;
+
+use std::error::Error;
+
+use unshell::protocol::tree::{EndpointOutcome, LocalEvent, ProtocolEndpoint};
+use unshell::protocol::{LeafIntrospection, INTROSPECTION_PROCEDURE_ID};
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let mut endpoint = ProtocolEndpoint::new(
+        remote_shell::agent_path(),
+        Some(Vec::new()),
+        Vec::new(),
+        vec![unshell::protocol::tree::LeafSpec {
+            name: remote_shell::shell_leaf_name(),
+            procedures: vec![remote_shell::shell_open_procedure()],
+        }],
+    );
+
+    let hook_id = endpoint.allocate_hook_id();
+    let outcome = endpoint.send_call(
+        remote_shell::agent_path(),
+        Some(remote_shell::shell_leaf_name()),
+        INTROSPECTION_PROCEDURE_ID,
+        Some(hook_id),
+        Vec::new(),
+    )?;
+
+    let EndpointOutcome::Local(LocalEvent::Data { message, .. }) = outcome else {
+        return Err("expected one local introspection response".into());
+    };
+
+    let payload = unshell::protocol::tree::decode_call_input::<LeafIntrospection>(&message.data)?;
+    println!("remote-shell examples normally listen on {}", remote_shell::LISTEN_ADDR);
+    println!("endpoint path: {:?}", remote_shell::agent_path());
+    println!("leaf: {}", payload.leaf_name);
+    println!("procedures: {:?}", payload.procedures);
+    Ok(())
+}