Muxio RPC Framework

Relevant source files

• Cargo.lock
• experiments/simd-r-drive-muxio-service-definition/Cargo.toml
• experiments/simd-r-drive-ws-client/Cargo.toml
• experiments/simd-r-drive-ws-server/Cargo.toml

Purpose and Scope

This document describes the Muxio RPC (Remote Procedure Call) framework as implemented in SIMD R Drive for remote storage access over WebSocket connections. The framework provides a type-safe, multiplexed communication protocol using bitcode serialization for efficient binary data transfer.

For information about the WebSocket server implementation, see WebSocket Server. For the native Rust client implementation, see Native Rust Client. For Python client integration, see Python WebSocket Client API.

Sources: experiments/simd-r-drive-ws-server/Cargo.toml:1-23 experiments/simd-r-drive-ws-client/Cargo.toml:1-22 experiments/simd-r-drive-muxio-service-definition/Cargo.toml:1-17

Architecture Overview

The Muxio RPC framework consists of multiple layers that work together to provide remote procedure calls over WebSocket connections:

Muxio RPC Framework Layer Architecture

graph TB
    subgraph "Client Application Layer"
        App["Application Code"]
end
    
    subgraph "Client RPC Stack"
        Caller["muxio-rpc-service-caller\nMethod Invocation"]
ClientRuntime["muxio-tokio-rpc-client\nWebSocket Client Runtime"]
end
    
    subgraph "Shared Contract"
        ServiceDef["simd-r-drive-muxio-service-definition\nService Interface Contract\nMethod Signatures"]
Bitcode["bitcode\nBinary Serialization"]
end
    
    subgraph "Server RPC Stack"
        ServerRuntime["muxio-tokio-rpc-server\nWebSocket Server Runtime"]
Endpoint["muxio-rpc-service-endpoint\nRequest Router"]
end
    
    subgraph "Server Application Layer"
        Impl["DataStore Implementation"]
end
    
    subgraph "Core Framework"
        Core["muxio-rpc-service\nBase RPC Traits & Types"]
end
    
 
   App --> Caller
 
   Caller --> ClientRuntime
 
   ClientRuntime --> ServiceDef
 
   ClientRuntime --> Bitcode
 
   ClientRuntime --> Core
    
 
   ServiceDef --> Bitcode
 
   ServiceDef --> Core
    
 
   ServerRuntime --> ServiceDef
 
   ServerRuntime --> Bitcode
 
   ServerRuntime --> Core
 
   ServerRuntime --> Endpoint
 
   Endpoint --> Impl
    
    style ServiceDef fill:#f9f9f9,stroke:#333,stroke-width:2px

The framework is organized into distinct layers:

Sources: Cargo.lock:1250-1336 experiments/simd-r-drive-ws-server/Cargo.toml:14-17 experiments/simd-r-drive-ws-client/Cargo.toml:14-21

Core Framework Components

muxio-rpc-service

The muxio-rpc-service crate provides the foundational abstractions for the RPC system:

Core RPC Framework Types

graph LR
    subgraph "muxio-rpc-service Core Types"
        RpcService["RpcService Trait\nService Interface"]
Request["Request Type\nmethod_id + payload"]
Response["Response Type\nresult or error"]
Error["RpcError\nError Handling"]
end
    
 
   RpcService -->|defines| Request
 
   RpcService -->|defines| Response
 
   Response -->|contains| Error

Key components in muxio-rpc-service:

Sources: Cargo.lock:1261-1272

Service Definition Layer

simd-r-drive-muxio-service-definition

The service definition crate serves as the shared contract between clients and servers. It defines the exact interface of the DataStore RPC service:

DataStore RPC Service Methods

graph TB
    subgraph "Service Definition Structure"
        ServiceDef["DataStoreService\nService Definition"]
Methods["Method Definitions"]
Types["Request/Response Types"]
Write["write\n(key, payload) → offset"]
Read["read\n(key) → Option<bytes>"]
Delete["delete\n(key) → bool"]
Exists["exists\n(key) → bool"]
BatchWrite["batch_write\n(entries) → Vec<offset>"]
BatchRead["batch_read\n(keys) → Vec<Option<bytes>>"]
end
    
 
   ServiceDef --> Methods
 
   ServiceDef --> Types
    
 
   Methods --> Write
 
   Methods --> Read
 
   Methods --> Delete
 
   Methods --> Exists
 
   Methods --> BatchWrite
 
   Methods --> BatchRead
    
 
   Types -->|uses| Bitcode["bitcode Serialization"]

The service definition establishes a type-safe contract for all operations:

flowchart LR
    Signature["Method Signature\n'write(key,payload)'"]
Hash["XXH3 Hash"]
MethodID["method_id: u64"]
Signature -->|hash| Hash
 
   Hash --> MethodID
 
   MethodID -->|used for routing| Router["Request Router"]

Method ID Generation

Each method is identified by an XXH3 hash of its signature, enabling fast routing without string comparisons:

Method Identification Flow

Sources: experiments/simd-r-drive-muxio-service-definition/Cargo.toml:1-17 Cargo.lock:1261-1272

graph LR
    subgraph "Bitcode Serialization Pipeline"
        RustType["Rust Type\n(Request/Response)"]
Encode["bitcode::encode"]
Binary["Binary Payload\nCompact Format"]
Decode["bitcode::decode"]
RustType2["Rust Type\n(Reconstructed)"]
end
    
 
   RustType -->|serialize| Encode
 
   Encode --> Binary
 
   Binary -->|deserialize| Decode
 
   Decode --> RustType2

Bitcode Serialization

The framework uses the bitcode crate for efficient binary serialization with the following characteristics:

Serialization Features

Bitcode Encoding/Decoding Pipeline

Integration with RPC

The serialization is integrated at multiple points:

1. Request serialization : Client encodes method arguments to binary
2. Wire transfer : Binary payload sent over WebSocket
3. Response serialization : Server encodes return values to binary
4. Deserialization : Both sides decode binary to Rust types

Sources: Cargo.lock:392-414 experiments/simd-r-drive-muxio-service-definition/Cargo.toml14

Client-Side Components

muxio-rpc-service-caller

The caller component provides the client-side method invocation interface:

Client Method Invocation Flow

Key responsibilities:

• Method call marshalling
• Request ID generation
• Response awaiting and matching
• Error propagation

Sources: Cargo.lock:1274-1285 experiments/simd-r-drive-ws-client/Cargo.toml18

muxio-tokio-rpc-client

The client runtime handles WebSocket communication and multiplexing:

Client Runtime Request/Response Multiplexing

The client runtime provides:

Sources: Cargo.lock:1302-1318 experiments/simd-r-drive-ws-client/Cargo.toml16

flowchart TB
    subgraph "Server Request Processing"
        Receive["Receive Request\nWebSocket"]
Deserialize["Deserialize\nbitcode::decode"]
ExtractID["Extract method_id"]
Route["Route to Handler"]
Execute["Execute Method"]
Serialize["Serialize Response\nbitcode::encode"]
Send["Send Response\nWebSocket"]
end
    
 
   Receive --> Deserialize
 
   Deserialize --> ExtractID
 
   ExtractID --> Route
 
   Route --> Execute
 
   Execute --> Serialize
 
   Serialize --> Send

Server-Side Components

muxio-rpc-service-endpoint

The endpoint component routes incoming RPC requests to service implementations:

Server Request Processing Pipeline

Endpoint responsibilities:

Sources: Cargo.lock:1287-1300 experiments/simd-r-drive-ws-server/Cargo.toml17

muxio-tokio-rpc-server

The server runtime manages WebSocket connections and request dispatching:

Server Runtime Connection Management

Key features:

Sources: Cargo.lock:1320-1336 experiments/simd-r-drive-ws-server/Cargo.toml16

Request/Response Flow

Complete RPC Call Sequence

End-to-End RPC Call Flow

Message Format

The wire protocol uses a structured binary format:

Sources: All component sources above

Error Handling

The framework provides comprehensive error handling across the RPC boundary:

RPC Error Classification and Propagation

Error Categories

Error Recovery

The framework implements several recovery strategies:

• Connection loss : Client automatically attempts reconnection
• Request timeout : Client cancels pending request after configured duration
• Serialization failure : Error logged and generic error returned
• Invalid method ID : Server returns "method not found" error

Sources: Cargo.lock:1261-1336

Performance Characteristics

The Muxio RPC framework is optimized for high-performance remote storage access:

The use of bitcode serialization and WebSocket binary frames minimizes overhead compared to text-based protocols like JSON over HTTP. The multiplexed architecture allows clients to issue multiple concurrent requests without blocking, essential for high-performance batch operations.

Sources: Cargo.lock:392-414 Cargo.lock:1250-1336