Transport Implementations

Relevant source files

• Cargo.lock
• Cargo.toml
• README.md

Purpose and Scope

This page provides an overview of the concrete transport implementations that connect the abstract RPC framework to actual network protocols. These implementations serve as the bridge between application code and the underlying communication layer, enabling RPC calls to be transmitted over real network connections.

For details on the RPC abstraction layer these transports implement, see RPC Framework. For guidance on creating custom transports, see Custom Transport Implementation.

Overview

The rust-muxio system provides three production-ready transport implementations, each targeting different deployment environments while sharing the same core RPC abstractions. All three implementations use WebSocket as the underlying protocol and implement the RpcServiceCallerInterface trait for client-side operations.

All transport implementations are located in the extensions/ directory, following the workspace structure defined in Cargo.toml:19-31

Sources: Cargo.toml:19-31 README.md:38-39 Cargo.lock:897-954

Transport Layer Architecture

The following diagram illustrates how transport implementations integrate with the RPC abstraction layer and the muxio core:

Sources: Cargo.toml:39-47 Cargo.lock:897-954 README.md:38-51

graph TB
    subgraph "Application Layer"
        APP["Application Code\nService Methods"]
end
    
    subgraph "RPC Abstraction Layer"
        CALLER["RpcServiceCallerInterface\nClient-side trait"]
ENDPOINT["RpcServiceEndpointInterface\nServer-side trait"]
SERVICE["RpcMethodPrebuffered\nService definitions"]
end
    
    subgraph "Transport Implementations"
        TOKIO_SERVER["muxio-tokio-rpc-server\nRpcServer struct"]
TOKIO_CLIENT["muxio-tokio-rpc-client\nRpcClient struct"]
WASM_CLIENT["muxio-wasm-rpc-client\nRpcWasmClient struct"]
end
    
    subgraph "Core Layer"
        DISPATCHER["RpcDispatcher\nRequest correlation"]
FRAMING["Binary Framing Protocol\nStream multiplexing"]
end
    
    subgraph "Network Layer"
        WS_SERVER["tokio_tungstenite\nWebSocket server"]
WS_CLIENT_NATIVE["tokio_tungstenite\nWebSocket client"]
WS_CLIENT_WASM["Browser WebSocket API\nvia wasm_bindgen"]
end
    
 
   APP --> SERVICE
 
   SERVICE --> CALLER
 
   SERVICE --> ENDPOINT
    
 
   CALLER --> TOKIO_CLIENT
 
   CALLER --> WASM_CLIENT
    
 
   ENDPOINT --> TOKIO_SERVER
    
 
   TOKIO_SERVER --> DISPATCHER
 
   TOKIO_CLIENT --> DISPATCHER
 
   WASM_CLIENT --> DISPATCHER
    
 
   DISPATCHER --> FRAMING
    
 
   TOKIO_SERVER --> WS_SERVER
 
   TOKIO_CLIENT --> WS_CLIENT_NATIVE
 
   WASM_CLIENT --> WS_CLIENT_WASM
    
 
   FRAMING --> WS_SERVER
 
   FRAMING --> WS_CLIENT_NATIVE
 
   FRAMING --> WS_CLIENT_WASM

Tokio-Based Transports

RpcServer

The RpcServer struct provides the server-side transport implementation for Tokio environments. It combines Axum's WebSocket handling with the RPC endpoint interface to accept incoming connections and dispatch RPC calls to registered handlers.

Key characteristics:

• Built on axum framework with WebSocket support
• Uses tokio-tungstenite for WebSocket protocol implementation
• Provides serve_with_listener() method for integration with existing TCP listeners
• Implements RpcServiceEndpointInterface for handler registration

Sources: Cargo.lock:917-933 Cargo.toml46 README.md38

RpcClient

The RpcClient struct provides the client-side transport implementation for Tokio environments. It establishes WebSocket connections to servers and implements the caller interface for making RPC requests.

Key characteristics:

• Direct WebSocket connection using tokio-tungstenite
• Implements RpcServiceCallerInterface for type-safe RPC calls
• Provides state change callbacks via set_state_change_handler()
• Supports both prebuffered and streaming RPC methods

Sources: Cargo.lock:898-916 Cargo.toml47 README.md:136-151

WASM Transport

RpcWasmClient

The RpcWasmClient struct enables RPC communication from WebAssembly environments by bridging Rust code with JavaScript's WebSocket API through wasm-bindgen.

Key characteristics:

• Compiles to WebAssembly target wasm32-unknown-unknown
• Uses wasm-bindgen to interface with browser WebSocket API
• Implements the same RpcServiceCallerInterface as native clients
• No direct dependency on Tokio runtime

Sources: Cargo.lock:934-954 Cargo.toml28 README.md39 README.md51

WebSocket Protocol Selection

All transport implementations use WebSocket as the underlying protocol for several reasons:

WebSocket messages carry the binary-serialized RPC frames defined by the muxio core protocol. The transport layer is responsible for:

1. Establishing and maintaining WebSocket connections
2. Converting between WebSocket binary messages and byte slices
3. Handling connection lifecycle events (connect, disconnect, errors)
4. Providing state change notifications to application code

Sources: Cargo.lock:1446-1455 Cargo.lock:1565-1580 README.md32

stateDiagram-v2
    [*] --> Disconnected
    
    Disconnected --> Connecting : new() / connect()
    
    Connecting --> Connected : WebSocket handshake success
    Connecting --> Disconnected : Connection failure
    
    Connected --> Disconnected : Network error
    Connected --> Disconnected : Server closes connection
    Connected --> Disconnected : Client disconnect()
    
    Disconnected --> [*]
    
    note right of Connected
        RpcTransportState enum
        - Disconnected
        - Connecting
        - Connected
    end note

Transport State Management

All client transports implement a state machine to track connection status. The state transitions are exposed to application code through callback handlers.

The RpcTransportState enum defines the possible connection states. Applications can register state change handlers using the set_state_change_handler() method available on client implementations:

This callback mechanism enables applications to:

• Display connection status in UI
• Implement automatic reconnection logic
• Queue requests while connecting
• Handle connection failures gracefully

Sources: README.md:138-141 README.md75

graph TD
    subgraph "Tokio Server Stack"
        TOKIO_SRV["muxio-tokio-rpc-server"]
AXUM["axum\nv0.8.4"]
TOKIO_1["tokio\nv1.45.1"]
TUNGSTENITE_1["tokio-tungstenite\nv0.26.2"]
end
    
    subgraph "Tokio Client Stack"
        TOKIO_CLI["muxio-tokio-rpc-client"]
TOKIO_2["tokio\nv1.45.1"]
TUNGSTENITE_2["tokio-tungstenite\nv0.26.2"]
end
    
    subgraph "WASM Client Stack"
        WASM_CLI["muxio-wasm-rpc-client"]
WASM_BINDGEN["wasm-bindgen\nv0.2.100"]
JS_SYS_DEP["js-sys\nv0.3.77"]
WASM_FUTURES["wasm-bindgen-futures\nv0.4.50"]
end
    
    subgraph "Shared RPC Layer"
        RPC_SERVICE["muxio-rpc-service"]
RPC_CALLER["muxio-rpc-service-caller"]
RPC_ENDPOINT["muxio-rpc-service-endpoint"]
end
    
    subgraph "Core"
        MUXIO_CORE["muxio"]
end
    
 
   TOKIO_SRV --> AXUM
 
   TOKIO_SRV --> TOKIO_1
 
   TOKIO_SRV --> TUNGSTENITE_1
 
   TOKIO_SRV --> RPC_ENDPOINT
    
 
   TOKIO_CLI --> TOKIO_2
 
   TOKIO_CLI --> TUNGSTENITE_2
 
   TOKIO_CLI --> RPC_CALLER
    
 
   WASM_CLI --> WASM_BINDGEN
 
   WASM_CLI --> JS_SYS_DEP
 
   WASM_CLI --> WASM_FUTURES
 
   WASM_CLI --> RPC_CALLER
    
 
   RPC_ENDPOINT --> RPC_SERVICE
 
   RPC_CALLER --> RPC_SERVICE
 
   RPC_SERVICE --> MUXIO_CORE

Dependency Graph

The following diagram shows the concrete dependency relationships between transport implementations and their supporting crates:

Sources: Cargo.lock:917-933 Cargo.lock:898-916 Cargo.lock:934-954 Cargo.toml:39-64

Cross-Platform Service Definition Sharing

A key design principle is that all transport implementations can consume the same service definitions. This is achieved through the RpcMethodPrebuffered trait, which defines methods with compile-time generated method IDs and encoding/decoding logic.

Example service definition usage from README.md:144-151:

The same service definitions work identically with RpcClient (Tokio), RpcWasmClient (WASM), and any future transport implementations that implement RpcServiceCallerInterface.

Sources: README.md:47-49 README.md:69-73 README.md:144-151 Cargo.toml42

Implementation Selection Guidelines

Choose the appropriate transport implementation based on your deployment target:

Usemuxio-tokio-rpc-server when:

• Building server-side applications
• Need to handle multiple concurrent client connections
• Require integration with existing Tokio/Axum infrastructure
• Operating in native Rust environments

Usemuxio-tokio-rpc-client when:

• Building native client applications (CLI tools, desktop apps)
• Writing integration tests for server implementations
• Need Tokio's async runtime features
• Operating in native Rust environments

Usemuxio-wasm-rpc-client when:

• Building web applications that run in browsers
• Creating browser extensions
• Need to communicate with servers from JavaScript contexts
• Targeting the wasm32-unknown-unknown platform

For detailed usage examples of each transport, refer to the subsections Tokio RPC Server, Tokio RPC Client, and WASM RPC Client.

Sources: README.md:38-51 Cargo.toml:19-31

Dismiss

Refresh this wiki

Enter email to refresh