Network Layer: WebSocket RPC (Experiments)

Loading…

Network Layer: WebSocket RPC (Experiments)

Relevant source files

• Cargo.lock
• experiments/bindings/python-ws-client/Cargo.toml
• 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

The network layer in simd-r-drive is an experimental, high-performance RPC system designed to expose the core storage engine over WebSockets. It leverages the muxio framework to provide multiplexed I/O, allowing multiple concurrent requests and responses over a single TCP connection without head-of-line blocking at the application level.

System Architecture

The architecture consists of a server that wraps a DataStore instance and a client that implements the standard simd-r-drive traits, making the network boundary transparent to the application logic. Communication is governed by a shared service definition that uses bitcode for efficient serialization.

Network Entity Mapping

This diagram bridges the natural language concepts of the network layer to the specific code entities and crates that implement them.

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

graph TD
    subgraph "Client_Space"["Client Space"]
        "WsClient"["WsClient [experiments/simd-r-drive-ws-client]"]
        "AsyncTraits"["AsyncDataStoreReader / AsyncDataStoreWriter [simd-r-drive]"]
        "PyWsClient"["simd_r_drive_ws_client [experiments/bindings/python-ws-client]"]
end

    subgraph "Service_Definition_Shared"["Service Definition (Shared)"]
        "ServiceDef"["simd-r-drive-muxio-service-definition [experiments/simd-r-drive-muxio-service-definition]"]
        "Bitcode"["bitcode [serialization]"]
end

    subgraph "Server_Space"["Server Space"]
        "WsServer"["simd-r-drive-ws-server [experiments/simd-r-drive-ws-server]"]
        "MuxioServer"["muxio-tokio-rpc-server"]
        "DataStore"["DataStore [simd-r-drive]"]
end

    "WsClient" -- "implements" --> "AsyncTraits"
    "WsClient" -- "uses" --> "ServiceDef"
    "PyWsClient" -- "wraps" --> "WsClient"
    "WsServer" -- "registers" --> "ServiceDef"
    "WsServer" -- "wraps" --> "DataStore"
    "WsClient" -- "WebSocket_muxio" --> "MuxioServer"

WebSocket Server

The simd-r-drive-ws-server crate provides a standalone binary that hosts a DataStore over a WebSocket endpoint. It uses tokio for the asynchronous runtime and integrates with muxio-tokio-rpc-server to handle incoming RPC calls.

The server registers several RPC endpoints corresponding to the DataStore API:

• Write Operations: write, batch_write, delete.
• Read Operations: read, batch_read, exists.
• Metadata Operations: len, is_empty, file_size.

For details on server implementation, transport configuration, and CLI arguments, see WebSocket Server.

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

WebSocket Client and Service Definition

The client-side implementation is split between a shared service definition and a concrete client wrapper.

Service Definition

The simd-r-drive-muxio-service-definition crate defines the “contract” between the client and server. It uses the bitcode crate for high-speed serialization of keys and payloads, ensuring minimal overhead during network transit. It defines the structure of requests and responses that both the client and server must adhere to.

WsClient

The WsClient struct in simd-r-drive-ws-client implements the AsyncDataStoreReader and AsyncDataStoreWriter traits. This allows it to be used as a drop-in replacement for a local DataStore in asynchronous contexts, abstracting the network calls into standard trait methods.

For details on the multiplexed transport and serialization format, see WebSocket Client and Service Definition.

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

Request Flow Overview

The following diagram illustrates the flow of an RPC request from the client to the underlying storage engine on the server.

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:14-15

sequenceDiagram
    participant C as "WsClient (simd-r-drive-ws-client)"
    participant M as "muxio-tokio-rpc-client"
    participant S as "simd-r-drive-ws-server"
    participant DS as "DataStore (simd-r-drive)"

    C->>C: Encode Request (bitcode)
    C->>M: send_request(METHOD_ID, payload)
    M->>S: WebSocket Frame (Multiplexed Stream)
    S->>S: Route to Method Handler
    S->>DS: Perform Storage Operation
    DS-->>S: Result (EntryHandle / Success)
    S->>S: Encode Response (bitcode)
    S-->>M: WebSocket Frame
    M-->>C: Response Bytes
    C->>C: Decode Response

Sub-pages

• WebSocket Server : Deep dive into how simd-r-drive-ws-server wraps DataStore in Arc<RwLock> and registers RPC endpoints (write, batch_write, read, batch_read, delete, len, is_empty, file_size, exists) via muxio-tokio-rpc-server. Covers the axum/tokio-tungstenite transport and CLI args.
• WebSocket Client and Service Definition : Details on how simd-r-drive-ws-client implements AsyncDataStoreReader/AsyncDataStoreWriter via WsClient, using muxio-tokio-rpc-client for multiplexed WebSocket transport. Covers the prebuffered service definition (bitcode serialization, METHOD_ID constants).