Network Layer and RPC

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

The network layer provides remote access to the SIMD R Drive storage engine over WebSocket connections using the Muxio RPC framework. This document covers the core RPC infrastructure, service definitions, and native Rust client implementation.

For WebSocket server deployment and configuration details, see WebSocket Server. For Muxio RPC protocol internals, see Muxio RPC Framework. For native Rust client usage, see Native Rust Client. For Python client integration, see Python Integration.

Architecture Overview

The network layer follows a symmetric client-server architecture built on three core crates that work together to enable remote DataStore access.

graph TB
    subgraph "Client Applications"
        RustApp["Rust Application"]
PyApp["Python Application\n(see section 4)"]
end
    
    subgraph "simd-r-drive-ws-client"
        WSClient["DataStoreWsClient"]
ClientCaller["RPC Caller\nmuxio-rpc-service-caller"]
ClientRuntime["muxio-tokio-rpc-client"]
end
    
    subgraph "Network Transport"
        WS["WebSocket\ntokio-tungstenite\nBinary Frames"]
end
    
    subgraph "simd-r-drive-ws-server"
        WSServer["Axum Server\nHTTP/WS Upgrade"]
ServerRuntime["muxio-tokio-rpc-server"]
ServerEndpoint["RPC Endpoint\nmuxio-rpc-service-endpoint"]
end
    
    subgraph "simd-r-drive-muxio-service-definition"
        ServiceDef["DataStoreService\nRPC Interface"]
Bitcode["bitcode serialization"]
end
    
    subgraph "Core Storage"
        DataStore["DataStore"]
end
    
 
   RustApp --> WSClient
 
   PyApp -.-> WSClient
 
   WSClient --> ClientCaller
 
   ClientCaller --> ClientRuntime
 
   ClientRuntime --> ServiceDef
 
   ClientRuntime --> WS
    
 
   WS --> WSServer
 
   WSServer --> ServerRuntime
 
   ServerRuntime --> ServiceDef
 
   ServerRuntime --> ServerEndpoint
 
   ServerEndpoint --> DataStore
    
 
   ServiceDef --> Bitcode

Component Architecture

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

Sources: experiments/simd-r-drive-ws-server/Cargo.toml:13-22 experiments/simd-r-drive-ws-client/Cargo.toml:14-21 experiments/simd-r-drive-muxio-service-definition/Cargo.toml:13-16

Service Definition and Contract

The simd-r-drive-muxio-service-definition crate defines the RPC interface as a shared contract between clients and servers. This crate must be used by both sides to ensure protocol compatibility.

DataStoreService Interface

The service definition declares available RPC methods that map to DataStore operations. The Muxio framework generates type-safe client and server stubs from this definition.

Typical Service Methods:

• read(key) - Retrieve payload by key
• write(key, payload) - Store payload
• delete(key) - Remove entry
• exists(key) - Check key existence
• batch_read(keys) - Bulk retrieval
• batch_write(entries) - Bulk insertion
• stream_* - Streaming operations

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

Bitcode Serialization

All RPC messages use bitcode for binary serialization, providing compact representation and fast encoding/decoding.

Advantages:

• Zero-copy deserialization where possible
• Smaller message sizes than JSON or bincode
• Strong type safety via Rust's type system
• Efficient handling of large payloads

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

Communication Protocol

Request-Response Flow

Sources: experiments/simd-r-drive-ws-client/Cargo.toml:14-21 experiments/simd-r-drive-ws-server/Cargo.toml:13-22

WebSocket Transport Layer

The network layer uses tokio-tungstenite for WebSocket communication over a Tokio async runtime.

Connection Properties:

• Binary WebSocket frames (not text)
• Persistent bidirectional connection
• Automatic ping/pong for keepalive
• Multiplexed requests via Muxio protocol

Protocol Stack:

┌─────────────────────────────────┐
│  DataStore Operations           │
├─────────────────────────────────┤
│  Muxio RPC (Service Methods)    │
├─────────────────────────────────┤
│  Bitcode Serialization           │
├─────────────────────────────────┤
│  WebSocket Binary Frames         │
├─────────────────────────────────┤
│  HTTP/1.1 Upgrade               │
├─────────────────────────────────┤
│  TCP (tokio runtime)            │
└─────────────────────────────────┘

Sources: Cargo.lock:305-339 (axum), Cargo.lock:1302-1317 (muxio-tokio-rpc-client), Cargo.lock:1320-1335 (muxio-tokio-rpc-server)

Muxio RPC Framework

The Muxio framework provides the core RPC abstraction layer, handling request routing, response matching, and connection multiplexing.

graph LR
    subgraph "Client Side"
        SC["muxio-rpc-service-caller\nMethod Invocation"]
TC["muxio-tokio-rpc-client\nTransport Handler"]
end
    
    subgraph "Shared"
        MRS["muxio-rpc-service\nCore Abstractions"]
SD["Service Definition"]
end
    
    subgraph "Server Side"
        TS["muxio-tokio-rpc-server\nTransport Handler"]
SE["muxio-rpc-service-endpoint\nMethod Routing"]
end
    
 
   SC --> MRS
 
   SC --> TC
 
   TC --> SD
    
 
   TS --> MRS
 
   TS --> SE
 
   SE --> SD
    
 
   MRS --> SD

Framework Components

Sources: Cargo.lock:1250-1271 (muxio), Cargo.lock:1261-1271 (muxio-rpc-service), Cargo.lock:1274-1284 (muxio-rpc-service-caller), Cargo.lock:1287-1299 (muxio-rpc-service-endpoint)

Sources: Cargo.lock:1250-1335

Request Multiplexing

The Muxio protocol assigns unique request IDs to enable multiple concurrent RPC calls over a single WebSocket connection.

Multiplexing Benefits:

• Single persistent connection reduces overhead
• Concurrent requests improve throughput
• Out-of-order responses supported
• Connection pooling not required

Sources: Cargo.lock:1250-1258

Client-Server Integration

Server-Side Implementation

The server crate (simd-r-drive-ws-server) integrates Axum for HTTP/WebSocket handling with the Muxio RPC server runtime.

Server Architecture:

1. Axum HTTP server accepts connections
2. WebSocket upgrade on /ws endpoint
3. muxio-tokio-rpc-server handles RPC protocol
4. muxio-rpc-service-endpoint routes to DataStore methods
5. Responses serialized with bitcode and returned

Sources: experiments/simd-r-drive-ws-server/Cargo.toml:13-22

Client-Side Implementation

The client crate (simd-r-drive-ws-client) provides DataStoreWsClient for remote DataStore access.

Client Architecture:

1. Connect to WebSocket endpoint
2. muxio-tokio-rpc-client manages connection
3. muxio-rpc-service-caller provides method invocation API
4. Requests serialized with bitcode
5. Async methods return Future<Result<T>>

Sources: experiments/simd-r-drive-ws-client/Cargo.toml:13-21

Dependency Graph

Sources: experiments/simd-r-drive-ws-server/Cargo.toml:13-22 experiments/simd-r-drive-ws-client/Cargo.toml:13-21 experiments/simd-r-drive-muxio-service-definition/Cargo.toml:13-16

Performance Characteristics

Serialization Overhead

Bitcode provides efficient binary serialization with minimal overhead:

• Small message payloads for keys and metadata
• Zero-copy where possible for large payloads
• Faster than JSON or traditional formats

Sources: Cargo.lock:392-413

Network Considerations

The WebSocket-based architecture has specific performance characteristics:

Trade-offs:

• Remote access enables distributed deployments
• Network latency higher than direct DataStore access
• Serialization/deserialization adds CPU overhead
• Suitable for applications with network-tolerant latency requirements

Sources: Cargo.lock:305-339 (axum), Cargo.lock:1302-1335 (muxio tokio rpc)

Async Runtime Integration

All network components run on the Tokio async runtime, providing non-blocking I/O and efficient concurrency.

Tokio Integration:

• WebSocket connections handled asynchronously
• Multiple clients served concurrently
• Non-blocking DataStore operations
• Future-based API throughout

Sources: experiments/simd-r-drive-ws-server/Cargo.toml18 experiments/simd-r-drive-ws-client/Cargo.toml19