Network Layer and RPC

Loading…

Network Layer and RPC

Relevant source files

• experiments/bindings/python-ws-client/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 network layer and Remote Procedure Call (RPC) system that enables remote access to the DataStore over WebSocket connections. The system is built on the Muxio framework and provides a standardized interface for clients in any language to communicate with a DataStore server.

For information about the core storage engine that the network layer wraps, see Core Storage Engine. For details on language-specific client implementations, see Python Integration and Native Rust Client.

Overview

The network layer provides a WebSocket-based RPC protocol that allows remote clients to perform DataStore operations. The architecture consists of three main components:

The system uses bitcode for efficient binary serialization and tokio-tungstenite for WebSocket transport. The Muxio framework handles message framing, multiplexing, and concurrent request processing over a single WebSocket connection.

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

Architecture Overview

Diagram: Network Layer Component Architecture

The client and server both depend on simd-r-drive-muxio-service-definition to ensure they share the same RPC contract. The Muxio framework components (muxio-rpc-service-caller and muxio-rpc-service-endpoint) handle the RPC mechanics, while muxio-tokio-rpc-client and muxio-tokio-rpc-server provide the WebSocket transport layer.

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

Service Definition Layer

The simd-r-drive-muxio-service-definition crate defines the RPC contract shared between client and server. This contract specifies:

• RPC Methods : Operations that can be invoked remotely (e.g., read, write, compact)
• Request/Response Types : Data structures for method parameters and return values
• Error Types : Standardized error representations for network and storage errors

Key Components

The service definition uses the muxio-rpc-service framework to define typed RPC interfaces. All data types use bitcode for serialization, which provides:

• Compact Binary Encoding : Efficient wire format optimized for small message sizes
• Zero-Copy Deserialization : Where possible, data is accessed without copying
• Type Safety : Compile-time guarantees that client and server speak the same protocol

Diagram: Service Definition Structure

The service trait defines method signatures, while request/response structs define the data exchanged. The bitcode derive macros generate serialization code automatically.

Sources: experiments/simd-r-drive-muxio-service-definition/Cargo.toml:14-15 experiments/bindings/python-ws-client/Cargo.lock:133-143

Transport Layer

WebSocket Protocol

The network layer uses WebSocket as the transport protocol for several reasons:

The transport is implemented using tokio-tungstenite, which provides async WebSocket support integrated with the Tokio runtime.

Sources: experiments/bindings/python-ws-client/Cargo.lock:1213-1222 experiments/bindings/python-ws-client/Cargo.lock:1303-1317

Muxio Framework

The Muxio framework provides the RPC layer on top of WebSocket:

Diagram: RPC Message Flow Through Muxio

The caller assigns a unique request_id to each RPC call, enabling multiplexing : multiple concurrent requests can be in flight over the same WebSocket connection. The endpoint matches responses to requests using these IDs.

Sources: experiments/bindings/python-ws-client/Cargo.lock:659-682 experiments/bindings/python-ws-client/Cargo.lock:685-700

Connection Management

Diagram: WebSocket Connection State Machine

The client maintains connection state and can implement automatic reconnection logic. The Muxio layer handles connection interruptions gracefully, returning errors for in-flight requests when the connection drops.

Sources: experiments/bindings/python-ws-client/Cargo.lock:685-700

Concurrency Model

The network layer is fully asynchronous and built on Tokio:

Client-Side Concurrency

The muxio-rpc-service-caller manages request IDs and matches responses to the correct awaiting future, enabling concurrent operations without blocking.

Server-Side Concurrency

The server spawns a new Tokio task for each incoming RPC request, allowing concurrent processing of multiple client requests. The underlying DataStore handles concurrent reads efficiently through its shared memory-mapped file access pattern (see Concurrency and Thread Safety).

Sources: experiments/simd-r-drive-ws-client/Cargo.toml19 experiments/simd-r-drive-ws-server/Cargo.toml18 experiments/bindings/python-ws-client/Cargo.lock:1184-1199

Error Handling

The RPC layer distinguishes between different error categories:

Diagram: Error Type Hierarchy

Each error category provides different information to help diagnose issues:

• Transport Errors : Indicate network connectivity problems
• Protocol Errors : Suggest version mismatches or implementation bugs
• Application Errors : Represent normal error conditions from DataStore operations

Sources: experiments/bindings/python-ws-client/Cargo.lock:659-669

Security Considerations

The current implementation provides:

For production deployments, consider:

1. Use WSS (WebSocket Secure) : Implement TLS encryption by placing the server behind a reverse proxy (nginx, Caddy, etc.)
2. Implement Authentication : Add token-based auth in the WebSocket handshake
3. Add Authorization : Implement per-key access controls in the server handler
4. Rate Limiting : Protect against DoS by limiting request rates per client

Sources: experiments/simd-r-drive-ws-server/Cargo.toml:1-23

Performance Characteristics

Serialization Overhead

The bitcode serialization format is optimized for performance:

• Small Message Size : Typically 30-50% smaller than JSON
• Fast Encoding : Zero-copy for many types, SIMD-optimized where applicable
• Predictable Layout : Fixed-size types don’t require length prefixes

Network Latency

RPC call latency consists of:

Total Latency = Serialization + Network RTT + Deserialization + Processing

For typical operations:

• Serialization/Deserialization : <1ms for small payloads
• Network RTT : Depends on network conditions (LAN: <1ms, WAN: 10-100ms)
• Processing : Varies by operation (read: <1ms, write: ~1-5ms with flush)

Connection Multiplexing

A single WebSocket connection can handle thousands of concurrent RPC calls, limited only by:

• Available memory for buffering requests
• Server processing capacity
• Network bandwidth

Sources: experiments/simd-r-drive-muxio-service-definition/Cargo.toml14 experiments/bindings/python-ws-client/Cargo.lock:133-143

Dependency Graph

Diagram: Complete Dependency Graph for Network Layer

The layered architecture ensures clean separation of concerns:

• Application Layer : Client and server applications
• simd-r-drive Components : Project-specific RPC wrappers and service definitions
• Muxio Framework : Generic RPC infrastructure
• Transport & Runtime: Low-level WebSocket and async runtime

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

Dismiss

Refresh this wiki

Enter email to refresh