tokio_ipc

A high-performance, multi-protocol RPC framework built on top of tokio_socket, enabling type-safe inter-process communication with support for multiple protocols over a single connection.

Features

• Multi-Protocol Support: Run multiple protocols over a single connection
• Type-Safe RPC: Compile-time checked request/response types using macros
• Bidirectional Communication: Both client and server can initiate calls
• Protocol Multiplexing: Route messages to different handlers based on protocol ID
• Zero-Copy Serialization: Efficient binary protocol using bincode
• Async/Await: Built on Tokio for high-performance async I/O

Quick Start

Define your protocols using the protocol! macro:

use tokio_ipc::protocol;

protocol! {
    pub mod my_protocol {
        // Request with response
        echo { message: String } -> { response: String };
        
        // Request without response (fire-and-forget)
        notify { event: String };
        
        // No parameters
        get_status -> { status: String };
    }
}

Implement the protocol handler:

#[derive(Clone)]
struct MyHandler;

impl my_protocol::Receive for MyHandler {
    async fn echo(&self, message: String) -> Result<my_protocol::echo::Response> {
        Ok(my_protocol::echo::Response {
            response: format!("Echo: {}", message)
        })
    }
    
    async fn notify(&self, event: String) -> Result<()> {
        println!("Event: {}", event);
        Ok(())
    }
    
    async fn get_status(&self) -> Result<my_protocol::get_status::Response> {
        Ok(my_protocol::get_status::Response {
            status: "healthy".to_string()
        })
    }
}

Examples

The examples/ directory contains comprehensive real-world examples demonstrating various use cases:

Basic Example (basic.rs)

The simplest multi-protocol example showing:

• Two protocols on a single handler (app_protocol + admin_protocol)
• Request/response RPC calls
• Auto-generated sender/receiver types
• Minimal boilerplate

Run it:

# Demo mode (integrated)
cargo run --example basic

# Separate processes
cargo run --example basic -- --server  # Terminal 1
cargo run --example basic -- --client  # Terminal 2

Bidirectional Example (bidirectional.rs)

Demonstrates full-duplex communication:

• Server calling methods on the client
• Client calling methods on the server
• Push notifications from server to client
• Bidirectional RPC patterns

Run it:

cargo run --example bidirectional

File Transfer Example (file_transfer.rs)

Real-world file transfer with progress tracking:

• Protocols: file_protocol + progress_protocol
• Chunked data transfer with configurable chunk size
• Progress updates sent from server to client
• Checksum verification on completion
• Flow control and error handling

Key Features:

• Demonstrates one-way messages (chunks) and request/response (file request)
• Shows bidirectional communication (server pushes progress updates)
• Realistic data streaming patterns

Run it:

cargo run --example file_transfer

Database Example (database.rs)

In-memory database with transaction support:

• Protocols: db_protocol + replication_protocol
• ACID transaction support (begin, commit, rollback)
• In-memory key-value store
• Write replication to clients
• Transaction isolation

Key Features:

• Demonstrates stateful protocol handlers
• Shows transaction management patterns
• Illustrates replication via bidirectional protocols

Run it:

cargo run --example database

Service Mesh Example (service_mesh.rs)

Service discovery and health monitoring:

• Protocols: service_protocol + health_protocol + discovery_protocol
• Service registration and discovery
• Health check monitoring
• Metrics collection and reporting
• Service-to-service RPC routing

Key Features:

• Demonstrates three protocols working together
• Shows service registry patterns
• Illustrates health monitoring and metrics

Run it:

# Demo mode
cargo run --example service_mesh

# Separate processes
cargo run --example service_mesh -- --registry  # Terminal 1
cargo run --example service_mesh -- --service   # Terminal 2
cargo run --example service_mesh -- --client    # Terminal 3

Multi-Protocol Patterns

Single Handler, Multiple Protocols

Implement multiple protocol traits on one handler:

#[derive(Clone)]
struct MyService {
    state: Arc<RwLock<ServiceState>>,
}

impl protocol_a::Receive for MyService { /* ... */ }
impl protocol_b::Receive for MyService { /* ... */ }
impl protocol_c::Receive for MyService { /* ... */ }

// Generate sender and receiver
tokio_ipc::protocol_sender!(MySender impl [protocol_a, protocol_b, protocol_c]);
tokio_ipc::protocol_handler!(MyReceiver impl [protocol_a, protocol_b, protocol_c] with MyService);

Protocol Registry

Compose protocols at runtime:

let registry = tokio_ipc::registry! {
    protocol_a => HandlerA::new(),
    protocol_b => HandlerB::new(),
    protocol_c => HandlerC::new(),
};

Bidirectional Protocols

Server can call client methods:

// Server handler receives client sender
impl RpcServerHandler for MyServer {
    type SendRpc = ClientSender;  // Can call client methods
    type ReceiveRpc = ServerReceiver;
    
    async fn on_rpc_connect(&self, client_sender: &Self::SendRpc) -> Self::ReceiveRpc {
        // Server can now call methods on the client
        client_sender.notify("Welcome!".to_string()).await?;
        // ...
    }
}

Protocol Design Guidelines

Separation of Concerns

Each protocol should handle one aspect of functionality:

• Data Protocol: File transfer, database operations
• Control Protocol: Service registration, configuration
• Monitoring Protocol: Health checks, metrics, logging

Message Types

• Request/Response: Use -> { fields } for operations that need acknowledgment
• One-Way: Omit return type for fire-and-forget notifications
• No Parameters: Omit request fields for simple queries

Protocol Versioning

Protocol IDs are auto-generated from name + version:

#[version(2)]
pub mod my_protocol {
    // Protocol version 2
}

Testing

All examples have comprehensive integration tests in tests/test_new_examples.rs:

# Run all example tests
cargo test --test test_new_examples

# Run specific example test
cargo test --test test_new_examples test_file_transfer_demo_mode

Tests verify:

• Demo mode execution
• Separate server/client processes
• Protocol message exchange
• Error handling
• Proper cleanup

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Application Layer                        │
│  (Your protocol implementations: Receive + Sender traits)   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                    Protocol Layer (tokio_ipc)                │
│  • Protocol multiplexing (protocol_id routing)              │
│  • RPC packet handling (request/response matching)          │
│  • Serialization (bincode)                                  │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                  Transport Layer (tokio_socket)              │
│  • Socket abstraction (TCP/UDS)                             │
│  • Packet framing (length-prefixed)                         │
│  • Connection management                                     │
└─────────────────────────────────────────────────────────────┘

Performance Considerations

• Zero-Copy: Messages are serialized directly to socket buffers
• Async I/O: Non-blocking operations using Tokio
• Connection Pooling: Reuse connections for multiple requests
• Backpressure: Flow control via async/await

License

See workspace LICENSE file.