feat: add AsyncVarlinkService for async introspection support (#139)

Add introspection support (GetInfo, GetInterfaceDescription) for async
varlink services, addressing issue #138.

Changes:
- Add AsyncInterface trait extending AsyncConnectionHandler with
get_name() and get_description() methods
- Add AsyncVarlinkService struct that wraps async handlers and provides
org.varlink.service introspection methods
- Add push_request() method to sansio::Server for request delegation
- Update code generator to implement AsyncInterface for async handlers
- Update async_ping example to demonstrate introspection usage
- Update documentation to show AsyncVarlinkService as the recommended
approach for async servers

Closes #138

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: haraldh

Cargo.lock

@@ -175,10 +175,12 @@ varlink-rust-generator --async src/org.example.ping.varlink > org_example_ping_a
 
 #### Server Implementation
 
+Use `AsyncVarlinkService` to create an async server with full introspection support (`org.varlink.service.GetInfo` and `GetInterfaceDescription`):
+
 ```rust
 use async_trait::async_trait;
 use std::sync::Arc;
-use varlink::{listen_async, ListenAsyncConfig};
+use varlink::{listen_async, AsyncVarlinkService, ListenAsyncConfig};
 
 // Include generated code
 mod org_example_ping;
@@ -204,8 +206,17 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let service = Arc::new(PingService);
     let handler = Arc::new(org_example_ping::new(service));
 
+    // Create service with introspection support
+    let varlink_service = Arc::new(AsyncVarlinkService::new(
+        "org.example",           // vendor
+        "My Ping Service",       // product
+        "1.0",                   // version
+        "https://example.org",   // url
+        vec![handler],           // list of interface handlers
+    ));
+
     listen_async(
-        handler,
+        varlink_service,
         "tcp:127.0.0.1:12345",
         &ListenAsyncConfig::default(),
     )

README.md

@@ -15,6 +15,7 @@ tokio = []
 anyhow = { workspace = true }
 async-trait = { workspace = true }
 varlink = { workspace = true, features = ["tokio"] }
+varlink_stdinterfaces = { workspace = true, features = ["tokio"] }
 serde = { workspace = true }
 serde_derive = { workspace = true }
 serde_json = { workspace = true }

examples/async_ping/Cargo.toml

@@ -1,62 +1,69 @@
 # Async Varlink Example with Tokio
 
-This example demonstrates how to use the varlink sans-io state machines with Tokio's async I/O.
+This example demonstrates how to use the varlink async API with Tokio, including full introspection support.
 
 ## Overview
 
 The sans-io architecture in varlink separates protocol logic from I/O operations, making it easy to integrate with any async runtime. This example shows:
 
-- **Async Server**: Uses `varlink::sansio::Server` with `tokio::net::TcpListener`
-- **Async Client**: Uses `varlink::sansio::Client` with `tokio::net::TcpStream`
+- **Async Server with Introspection**: Uses `AsyncVarlinkService` to provide `org.varlink.service.GetInfo` and `GetInterfaceDescription`
+- **Async Client**: Uses the generated `VarlinkClient` with `AsyncConnection`
 - **Concurrent Connections**: Server handles multiple clients concurrently using `tokio::spawn`
-- **Poll-based API**: Demonstrates the complete event loop pattern
+- **Service Discovery**: Demonstrates how clients can discover available interfaces
 
 ## Key Features
 
-### Sans-IO State Machines
+### AsyncVarlinkService with Introspection
 
-The example uses the pure protocol state machines that operate independently of I/O:
+The example uses `AsyncVarlinkService` to wrap interface handlers and provide standard introspection:
 
 ```rust
-// Server side
-let mut server = Server::new();
+use varlink::{listen_async, AsyncVarlinkService, ListenAsyncConfig};
+
+// Create the interface handler
+let ping_service = Arc::new(PingService);
+let ping_handler = Arc::new(org_example_ping::new(ping_service));
+
+// Wrap with AsyncVarlinkService for introspection support
+let service = Arc::new(AsyncVarlinkService::new(
+    "org.example",
+    "Async Ping Example",
+    "1.0",
+    "https://github.com/varlink/rust",
+    vec![ping_handler],
+));
+
+// Start listening
+listen_async(service, "tcp:127.0.0.1:9999", &ListenAsyncConfig::default()).await?;
+```
 
-// Feed data from the network
-server.handle_input(&buf[..n])?;
+### Async Client
 
-// Process protocol events
-while let Some(event) = server.poll_event() {
-    // Handle requests and send replies
-}
+```rust
+// Connect to the service
+let connection = varlink::AsyncConnection::with_address("tcp:127.0.0.1:9999").await?;
+let client = org_example_ping::VarlinkClient::new(connection);
 
-// Get data to send over the network
-while let Some(transmit) = server.poll_transmit() {
-    stream.write_all(&transmit.payload).await?;
-}
+// Make a request
+let reply = client.ping("Hello!".to_string()).call().await?;
+println!("Response: {}", reply.pong);
 ```
 
-### Async Client
+### Service Discovery via Introspection
 
 ```rust
-// Client side
-let mut client = Client::new();
-
-// Send a request
-client.send_request(method, request)?;
+use varlink_stdinterfaces::org_varlink_service_async::VarlinkClientInterface;
 
-// Transmit outgoing data
-while let Some(transmit) = client.poll_transmit() {
-    stream.write_all(&transmit.payload).await?;
-}
+let connection = varlink::AsyncConnection::with_address("tcp:127.0.0.1:9999").await?;
+let client = varlink_stdinterfaces::org_varlink_service_async::VarlinkClient::new(connection);
 
-// Receive response
-let n = stream.read(&mut buf).await?;
-client.handle_input(&buf[..n])?;
+// Discover service info
+let info = client.get_info().call().await?;
+println!("Interfaces: {:?}", info.interfaces);
 
-// Process events
-while let Some(event) = client.poll_event() {
-    // Handle replies
-}
+// Get interface description
+let desc = client.get_interface_description("org.example.ping".to_string()).call().await?;
+println!("IDL: {}", desc.description);
 ```
 
 ## Running the Example
@@ -72,25 +79,40 @@ cargo test --package async_ping
 ## Expected Output
 
 ```
-Server: Listening on 127.0.0.1:9999
+Server: Listening on 127.0.0.1:9999 (with introspection)
+
+=== Running Introspection Example ===
+
+Client: Connecting to 127.0.0.1:9999 for introspection
+Client: Calling org.varlink.service.GetInfo...
+  Vendor: org.example
+  Product: Async Ping Example
+  Version: 1.0
+  URL: https://github.com/varlink/rust
+  Interfaces: ["org.varlink.service", "org.example.ping"]
+
+Client: Calling org.varlink.service.GetInterfaceDescription for 'org.example.ping'...
+  Description:
+# Example async service
+interface org.example.ping
+
+# Returns the same string
+method Ping(ping: string) -> (pong: string)
+
+error PingError(parameter: int)
 
 === Running Client Example ===
 
 Client: Connecting to 127.0.0.1:9999
-Server: New client connected
 Client: Sending Ping request: 'Hello, Async Varlink!'
-Server: Received request: "org.example.ping.Ping"
 Server: Ping request with: 'Hello, Async Varlink!'
-Client: Received reply for method: org.example.ping.Ping
 Client: Pong response: 'Hello, Async Varlink!'
 
 === Running Second Client Example ===
 
 Client: Connecting to 127.0.0.1:9999
 Client: Sending Ping request: 'Testing sans-io with Tokio'
-Server: Received request: "org.example.ping.Ping"
 Server: Ping request with: 'Testing sans-io with Tokio'
-Client: Received reply for method: org.example.ping.Ping
 Client: Pong response: 'Testing sans-io with Tokio'
 
 === Example Complete ===
@@ -101,10 +123,10 @@ Client: Pong response: 'Testing sans-io with Tokio'
 The example is structured as follows:
 
 1. **Protocol Definition**: `org.example.ping.varlink` defines the Ping method
-2. **Generated Code**: `build.rs` generates Rust bindings using `varlink_generator`
-3. **Async Server**: `handle_client()` processes connections using the sans-io Server
-4. **Async Client**: `run_client()` makes requests using the sans-io Client
-5. **Main Function**: Coordinates server startup and client requests
+2. **Generated Code**: `build.rs` generates async Rust bindings using `varlink_generator`
+3. **Async Server**: `AsyncVarlinkService` wraps interface handlers and provides introspection
+4. **Async Client**: `VarlinkClient` makes requests using `AsyncConnection`
+5. **Main Function**: Demonstrates introspection and regular method calls
 
 ## Benefits of Sans-IO with Async
 

examples/async_ping/README.md

@@ -1,11 +1,13 @@
 //! Async Varlink Client Example using Tokio
 //!
-//! This example demonstrates how to use the generated async client and server API.
+//! This example demonstrates how to use the generated async client and server API,
+//! including introspection support via AsyncVarlinkService.
 
 use anyhow::Result;
 use async_trait::async_trait;
 use std::sync::Arc;
-use varlink::{listen_async, ListenAsyncConfig};
+use varlink::{listen_async, AsyncVarlinkService, ListenAsyncConfig};
+use varlink_stdinterfaces::org_varlink_service_async::VarlinkClientInterface as ServiceClientInterface;
 
 // Include the generated code
 mod org_example_ping;
@@ -26,10 +28,23 @@ impl VarlinkInterface for PingService {
     }
 }
 
-async fn run_server(addr: &str) -> Result<()> {
-    println!("Server: Listening on {}", addr);
+/// Run a server with AsyncVarlinkService for introspection support
+async fn run_server_with_introspection(addr: &str) -> Result<()> {
+    println!("Server: Listening on {} (with introspection)", addr);
+
+    // Create the ping service handler
     let ping_service = Arc::new(PingService);
-    let service = Arc::new(org_example_ping::new(ping_service));
+    let ping_handler = Arc::new(org_example_ping::new(ping_service));
+
+    // Wrap with AsyncVarlinkService for introspection support
+    let service = Arc::new(AsyncVarlinkService::new(
+        "org.example",
+        "Async Ping Example",
+        "1.0",
+        "https://github.com/varlink/rust",
+        vec![ping_handler],
+    ));
+
     listen_async(
         service,
         format!("tcp:{}", addr),
@@ -43,7 +58,6 @@ async fn run_server(addr: &str) -> Result<()> {
 async fn run_client(addr: &str, ping_message: &str) -> Result<()> {
     println!("Client: Connecting to {}", addr);
 
-    // NEW API: Use the generated VarlinkClient with AsyncConnection
     let connection = varlink::AsyncConnection::with_address(format!("tcp:{}", addr))
         .await
         .map_err(|e| anyhow::anyhow!("Connection error: {:?}", e))?;
@@ -52,7 +66,6 @@ async fn run_client(addr: &str, ping_message: &str) -> Result<()> {
 
     println!("Client: Sending Ping request: '{}'", ping_message);
 
-    // NEW API: call().await instead of call_async().await
     let reply = client
         .ping(ping_message.to_string())
         .call()
@@ -64,21 +77,69 @@ async fn run_client(addr: &str, ping_message: &str) -> Result<()> {
     Ok(())
 }
 
+/// Demonstrate introspection by calling GetInfo and GetInterfaceDescription
+async fn run_introspection_client(addr: &str) -> Result<()> {
+    println!("Client: Connecting to {} for introspection", addr);
+
+    let connection = varlink::AsyncConnection::with_address(format!("tcp:{}", addr))
+        .await
+        .map_err(|e| anyhow::anyhow!("Connection error: {:?}", e))?;
+
+    let client = varlink_stdinterfaces::org_varlink_service_async::VarlinkClient::new(connection);
+
+    // Call GetInfo to discover service metadata
+    println!("Client: Calling org.varlink.service.GetInfo...");
+    let info = client
+        .get_info()
+        .call()
+        .await
+        .map_err(|e| anyhow::anyhow!("GetInfo error: {:?}", e))?;
+
+    println!("  Vendor: {}", info.vendor);
+    println!("  Product: {}", info.product);
+    println!("  Version: {}", info.version);
+    println!("  URL: {}", info.url);
+    println!("  Interfaces: {:?}", info.interfaces);
+
+    // Call GetInterfaceDescription for org.example.ping
+    println!(
+        "\nClient: Calling org.varlink.service.GetInterfaceDescription for 'org.example.ping'..."
+    );
+    let connection = varlink::AsyncConnection::with_address(format!("tcp:{}", addr))
+        .await
+        .map_err(|e| anyhow::anyhow!("Connection error: {:?}", e))?;
+    let client = varlink_stdinterfaces::org_varlink_service_async::VarlinkClient::new(connection);
+
+    let desc = client
+        .get_interface_description("org.example.ping".to_string())
+        .call()
+        .await
+        .map_err(|e| anyhow::anyhow!("GetInterfaceDescription error: {:?}", e))?;
+
+    println!("  Description:\n{}", desc.description);
+
+    Ok(())
+}
+
 #[tokio::main]
 async fn main() -> Result<()> {
     let addr = "127.0.0.1:9999";
 
-    // Spawn the server in the background
+    // Spawn the server with introspection support
     let server_handle = tokio::spawn(async move {
-        if let Err(e) = run_server(addr).await {
+        if let Err(e) = run_server_with_introspection(addr).await {
             eprintln!("Server error: {}", e);
         }
     });
 
     // Give the server time to start
     tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;
 
-    // Run the client
+    // Demonstrate introspection
+    println!("\n=== Running Introspection Example ===\n");
+    run_introspection_client(addr).await?;
+
+    // Run the regular client
     println!("\n=== Running Client Example ===\n");
     run_client(addr, "Hello, Async Varlink!").await?;
 
@@ -111,10 +172,20 @@ mod tests {
         let stop = Arc::new(AtomicBool::new(false));
         let stop_clone = Arc::clone(&stop);
 
-        // Spawn server with graceful shutdown support
+        // Spawn server with graceful shutdown support and introspection
         let server_handle = tokio::spawn(async move {
             let ping_service = Arc::new(PingService);
-            let service = Arc::new(org_example_ping::new(ping_service));
+            let ping_handler = Arc::new(org_example_ping::new(ping_service));
+
+            // Use AsyncVarlinkService for introspection support
+            let service = Arc::new(AsyncVarlinkService::new(
+                "org.example",
+                "Async Ping Test",
+                "1.0",
+                "https://github.com/varlink/rust",
+                vec![ping_handler],
+            ));
+
             let config = ListenAsyncConfig {
                 idle_timeout: Duration::ZERO,
                 stop_listening: Some(stop_clone),
@@ -127,7 +198,15 @@ mod tests {
         // Give server time to start
         tokio::time::sleep(Duration::from_millis(100)).await;
 
-        // Test client
+        // Test introspection
+        let introspection_result = run_introspection_client(addr).await;
+        assert!(
+            introspection_result.is_ok(),
+            "Introspection failed: {:?}",
+            introspection_result.err()
+        );
+
+        // Test ping client
         let result = run_client(addr, "test").await;
         assert!(result.is_ok());
 

examples/async_ping/src/main.rs

@@ -268,3 +268,11 @@ impl varlink::AsyncConnectionHandler for VarlinkInterfaceHandler {
         Ok(None)
     }
 }
+impl varlink::AsyncInterface for VarlinkInterfaceHandler {
+    fn get_name(&self) -> &'static str {
+        "org.example.ping"
+    }
+    fn get_description(&self) -> &'static str {
+        "# Example async service\ninterface org.example.ping\n\n# Returns the same string\nmethod Ping(ping: string) -> (pong: string)\n\nerror PingError(parameter: int)\n"
+    }
+}