docs: add Unix Domain Socket transport example

Added hello-unix-client and hello-unix-server examples demonstrating
wrpc transport over Unix Domain Sockets, matching the existing TCP
examples.

Closes #481

Signed-off-by: KuaaMU <138859253+KuaaMU@users.noreply.github.com>

Author: KuaaMU

Cargo.lock

@@ -0,0 +1,25 @@
+[package]
+name = "hello-unix-client"
+version = "0.1.0"
+
+authors.workspace = true
+categories.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+anyhow = { workspace = true }
+clap = { workspace = true, features = [
+    "color",
+    "derive",
+    "error-context",
+    "help",
+    "std",
+    "suggestions",
+    "usage",
+] }
+tokio = { workspace = true, features = ["rt-multi-thread"] }
+tracing-subscriber = { workspace = true, features = ["ansi", "fmt"] }
+wit-bindgen-wrpc = { workspace = true }
+wrpc-transport = { workspace = true, features = ["net"] }

examples/rust/hello-unix-client/Cargo.toml

@@ -0,0 +1,33 @@
+use std::path::PathBuf;
+
+use anyhow::Context as _;
+use clap::Parser;
+
+mod bindings {
+    wit_bindgen_wrpc::generate!({
+        with: {
+            "wrpc-examples:hello/handler": generate
+        }
+    });
+}
+
+#[derive(Parser, Debug)]
+#[command(author, version, about, long_about = None)]
+struct Args {
+    /// Path to invoke `wrpc-examples:hello/handler.hello` on
+    #[arg(default_value = "/tmp/wrpc/hello.sock")]
+    path: PathBuf,
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    tracing_subscriber::fmt().init();
+
+    let Args { path } = Args::parse();
+    let wrpc = wrpc_transport::unix::Client::from(path.as_path());
+    let hello = bindings::wrpc_examples::hello::handler::hello(&wrpc, ())
+        .await
+        .context("failed to invoke `wrpc-examples.hello/handler.hello`")?;
+    eprintln!("{hello}");
+    Ok(())
+}

examples/rust/hello-unix-client/src/main.rs

@@ -0,0 +1,4 @@
+[hello]
+path = "../../../wit/hello"
+sha256 = "3680bb734f3fa9f7325674142a2a9b558efd34ea2cb2df7ccb651ad869078d27"
+sha512 = "688fdae594dc43bd65bd15ea66b77a8f97cb4bc1c3629719e91d6c1391c66f7c8c6517d096f686cca996188f64f075c4ccb0d70a40097ce76b8b4bcc71dc7506"

examples/rust/hello-unix-client/wit/deps.lock

@@ -0,0 +1 @@
+hello = "../../../wit/hello"

examples/rust/hello-unix-client/wit/deps.toml

@@ -0,0 +1,13 @@
+package wrpc-examples:hello;
+
+interface handler {
+    hello: func() -> string;
+}
+
+world client {
+    import handler;
+}
+
+world server {
+    export handler;
+}

examples/rust/hello-unix-client/wit/deps/hello/hello.wit

@@ -0,0 +1,5 @@
+package wrpc-examples:hello-rust-client;
+
+world client {
+    include wrpc-examples:hello/client;
+}

examples/rust/hello-unix-client/wit/world.wit

@@ -0,0 +1,27 @@
+[package]
+name = "hello-unix-server"
+version = "0.1.0"
+
+authors.workspace = true
+categories.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+anyhow = { workspace = true }
+clap = { workspace = true, features = [
+    "color",
+    "derive",
+    "error-context",
+    "help",
+    "std",
+    "suggestions",
+    "usage",
+] }
+futures = { workspace = true }
+tokio = { workspace = true, features = ["fs", "rt-multi-thread", "net", "signal"] }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true, features = ["ansi", "fmt"] }
+wit-bindgen-wrpc = { workspace = true }
+wrpc-transport = { workspace = true, features = ["net"] }

examples/rust/hello-unix-server/Cargo.toml

@@ -0,0 +1,117 @@
+use core::pin::pin;
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use anyhow::Context as _;
+use clap::Parser;
+use futures::stream::select_all;
+use futures::StreamExt as _;
+use tokio::task::JoinSet;
+use tokio::{fs, select, signal};
+use tracing::{debug, error, info, warn};
+
+mod bindings {
+    wit_bindgen_wrpc::generate!({
+        with: {
+            "wrpc-examples:hello/handler": generate,
+        }
+    });
+}
+
+#[derive(Parser, Debug)]
+#[command(author, version, about, long_about = None)]
+struct Args {
+    /// Path to serve `wrpc-examples:hello/handler.hello` on
+    #[arg(default_value = "/tmp/wrpc/hello.sock")]
+    path: PathBuf,
+}
+
+#[derive(Clone, Copy)]
+struct Server;
+
+impl bindings::exports::wrpc_examples::hello::handler::Handler<tokio::net::unix::SocketAddr>
+    for Server
+{
+    async fn hello(&self, _: tokio::net::unix::SocketAddr) -> anyhow::Result<String> {
+        Ok("hello from Rust".to_string())
+    }
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    tracing_subscriber::fmt().init();
+
+    let Args { path } = Args::parse();
+
+    if let Some(dir) = path.parent() {
+        if !dir.exists() {
+            fs::create_dir_all(dir)
+                .await
+                .with_context(|| format!("failed to create `{}`", dir.display()))?
+        }
+    }
+    let lis = tokio::net::UnixListener::bind(&path)
+        .with_context(|| format!("failed to bind Unix listener on `{}`", path.display()))?;
+    let srv = Arc::new(wrpc_transport::Server::default());
+    let accept = tokio::spawn({
+        let srv = Arc::clone(&srv);
+        async move {
+            loop {
+                if let Err(err) = srv.accept(&lis).await {
+                    error!(?err, "failed to accept Unix connection");
+                }
+            }
+        }
+    });
+
+    let invocations = bindings::serve(srv.as_ref(), Server)
+        .await
+        .context("failed to serve `wrpc-examples.hello/handler.hello`")?;
+    // NOTE: This will conflate all invocation streams into a single stream via `futures::stream::SelectAll`,
+    // to customize this, iterate over the returned `invocations` and set up custom handling per export
+    let mut invocations = select_all(
+        invocations
+            .into_iter()
+            .map(|(instance, name, invocations)| invocations.map(move |res| (instance, name, res))),
+    );
+    let shutdown = signal::ctrl_c();
+    let mut shutdown = pin!(shutdown);
+    let mut tasks = JoinSet::new();
+    loop {
+        select! {
+            Some((instance, name, res)) = invocations.next() => {
+                match res {
+                    Ok(fut) => {
+                        debug!(instance, name, "invocation accepted");
+                        tasks.spawn(async move {
+                            if let Err(err) = fut.await {
+                                warn!(?err, "failed to handle invocation");
+                            } else {
+                                info!(instance, name, "invocation successfully handled");
+                            }
+                        });
+                    }
+                    Err(err) => {
+                        warn!(?err, instance, name, "failed to accept invocation");
+                    }
+                }
+            }
+            Some(res) = tasks.join_next() => {
+                if let Err(err) = res {
+                    error!(?err, "failed to join task");
+                }
+            }
+            res = &mut shutdown => {
+                accept.abort();
+                // wait for all invocations to complete
+                while let Some(res) = tasks.join_next().await {
+                    if let Err(err) = res {
+                        error!(?err, "failed to join task");
+                    }
+                }
+                return res.context("failed to listen for ^C")
+            }
+        }
+    }
+}

examples/rust/hello-unix-server/src/main.rs

@@ -0,0 +1,4 @@
+[hello]
+path = "../../../wit/hello"
+sha256 = "3680bb734f3fa9f7325674142a2a9b558efd34ea2cb2df7ccb651ad869078d27"
+sha512 = "688fdae594dc43bd65bd15ea66b77a8f97cb4bc1c3629719e91d6c1391c66f7c8c6517d096f686cca996188f64f075c4ccb0d70a40097ce76b8b4bcc71dc7506"