Transport Implementations

Loading…

Transport Implementations

Relevant source files

• extensions/muxio-tokio-rpc-client/Cargo.toml
• extensions/muxio-tokio-rpc-ipc-client/Cargo.toml
• extensions/muxio-tokio-rpc-server/Cargo.toml
• extensions/muxio-wasm-rpc-client/Cargo.toml

The Transport Implementation layer consists of concrete crates that bridge the high-level RPC service abstractions to physical network I/O. While the core muxio crate and the muxio-rpc-service-* extensions handle framing and dispatching logic, these transport crates manage the lifecycle of actual connections, such as WebSocket streams over TCP, Unix Domain Sockets, or browser-based sockets.

Architecture Overview

Muxio provides several transport implementations designed for different runtime environments and communication patterns:

1. muxio-tokio-rpc-server : A native Rust server built on the Tokio runtime and tokio-tungstenite [extensions/muxio-tokio-rpc-server/Cargo.toml:1-22].
2. muxio-tokio-rpc-client : A native Rust client for desktop or server-to-server communication using tokio-tungstenite [extensions/muxio-tokio-rpc-client/Cargo.toml:1-22].
3. muxio-wasm-rpc-client : A specialized client for web browsers, utilizing wasm-bindgen to interface with JavaScript-managed sockets [extensions/muxio-wasm-rpc-client/Cargo.toml:1-22].
4. IPC Transports : Specialized crates for local inter-process communication using interprocess for Unix domain sockets and Windows named pipes [extensions/muxio-tokio-rpc-ipc-client/Cargo.toml:1-22].

graph TD
    subgraph "Application Code"
        [ServiceDefinition]
    end

    subgraph "Transport Layer (Code Entities)"
        Server["RpcServer (muxio-tokio-rpc-server)"]
NativeClient["RpcClient (muxio-tokio-rpc-client)"]
WasmClient["RpcWasmClient (muxio-wasm-rpc-client)"]
IpcClient["RpcIpcClient (muxio-tokio-rpc-ipc-client)"]
end

    subgraph "Core & Service Layer"
        Endpoint["RpcServiceEndpoint"]
Dispatcher["RpcDispatcher"]
end

 
   Server --> Endpoint
 
   NativeClient --> Dispatcher
 
   WasmClient --> Dispatcher
 
   IpcClient --> Dispatcher

    [ServiceDefinition] -. "implements" .-> Endpoint
    [ServiceDefinition] -. "calls via" .-> NativeClient
    [ServiceDefinition] -. "calls via" .-> WasmClient
    [ServiceDefinition] -. "calls via" .-> IpcClient

The following diagram illustrates how these transports connect the RpcDispatcher to the network:

Transport Entity Map

Sources: [extensions/muxio-tokio-rpc-server/Cargo.toml:1-22], [extensions/muxio-tokio-rpc-client/Cargo.toml:1-22], [extensions/muxio-wasm-rpc-client/Cargo.toml:1-22], [extensions/muxio-tokio-rpc-ipc-client/Cargo.toml:1-22].

muxio-tokio-rpc-server: WebSocket RPC Server

The muxio-tokio-rpc-server crate provides the RpcServer struct, which manages incoming WebSocket connections. It is responsible for hosting an RpcServiceEndpoint and spawning asynchronous tasks to handle each connected client [extensions/muxio-tokio-rpc-server/Cargo.toml:11-22].

• Bidirectional Calling : Unlike traditional REST servers, the RpcServer can initiate calls back to connected clients using the ConnectionContextHandle.
• Heartbeat Mechanism : Implements HEARTBEAT_INTERVAL and CLIENT_TIMEOUT logic to prune dead connections.
• Task Architecture : Each connection spawns a sender_task and a receiver_task to ensure full-duplex communication without head-of-line blocking at the application level.

For details on server configuration and connection management, see muxio-tokio-rpc-server: WebSocket RPC Server.

Sources: [extensions/muxio-tokio-rpc-server/Cargo.toml:1-22].

muxio-tokio-rpc-client: Native Async RPC Client

The muxio-tokio-rpc-client crate provides the RpcClient, a native Rust implementation of the RpcServiceCallerInterface. It is designed for high-performance, asynchronous environments using the Tokio runtime [extensions/muxio-tokio-rpc-client/Cargo.toml:11-22].

• Three-Task Architecture : Internally manages three concurrent loops: a heartbeat loop, a receive loop for incoming frames/responses, and a send loop for outgoing requests.
• State Management : Tracks RpcTransportState and allows users to set state change handlers to react to disconnections.
• Graceful Shutdown : Supports both shutdown_async and shutdown_sync to ensure pending requests are handled or cancelled before the client is dropped.

For details on the native client’s task lifecycle and state transitions, see muxio-tokio-rpc-client: Native Async RPC Client.

Sources: [extensions/muxio-tokio-rpc-client/Cargo.toml:1-22].

muxio-wasm-rpc-client: Browser/WASM RPC Client

The muxio-wasm-rpc-client crate is a specialized implementation of the Muxio protocol for WebAssembly targets. Because browsers do not allow raw TCP access, this crate facilitates communication through a JavaScript bridge [extensions/muxio-wasm-rpc-client/Cargo.toml:14-22].

• JS Bridge : Uses wasm-bindgen to export functions like static_muxio_write_bytes_uint8 and static_muxio_read_bytes_uint8, allowing a JavaScript-based WebSocket to pass data into the Rust RPC engine.
• Static Client Pattern : Provides MUXIO_STATIC_RPC_CLIENT_REF and init_static_client to manage a global RPC singleton, which is a common requirement in WASM applications where ownership across the JS/Rust boundary is complex.
• Lifecycle : Manages the handle_connect and handle_disconnect events triggered by the browser’s networking stack.

For details on the WASM-to-JS integration and static client usage, see muxio-wasm-rpc-client: Browser/WASM RPC Client.

Sources: [extensions/muxio-wasm-rpc-client/Cargo.toml:1-22].

IPC Transports & MPSC Adapter

Muxio supports local communication via IPC and internal channels:

• IPC Transports : The muxio-tokio-rpc-ipc-client and muxio-tokio-rpc-ipc-server crates use interprocess to provide high-speed local communication over Unix Domain Sockets or Windows Named Pipes [extensions/muxio-tokio-rpc-ipc-client/Cargo.toml:1-22].
• MPSC Adapter : The muxio-tokio-mpsc-adapter crate allows using standard Rust MPSC channels as a transport, which is useful for internal service communication within a single process or for testing purposes.

For details on local transports and streaming adapters, see IPC Transports & MPSC Adapter.

Sources: [extensions/muxio-tokio-rpc-ipc-client/Cargo.toml:1-22].

Transport Interaction Lifecycle

The following diagram demonstrates the typical flow of data from a high-level RPC call through a transport implementation to the network.

sequenceDiagram
    participant App as "Application Code"
    participant Caller as "RpcServiceCallerInterface"
    participant Transport as "RpcClient / RpcWasmClient"
    participant Dispatcher as "RpcDispatcher"
    participant Network as "Network I/O (WebSocket/TCP)"

    App->>Caller: call_rpc_buffered(method, args)
    Caller->>Dispatcher: call(request_bytes)
    Dispatcher->>Transport: emit_fn(frame_bytes)
    Note over Transport: Transport Task (Send Loop)
    Transport->>Network: Send Binary Frame
    Network-->>Transport: Receive Binary Frame
    Transport->>Dispatcher: read_bytes(frame_bytes)
    Dispatcher-->>App: Return RpcResult

Data Flow: Caller to Transport

Sources: [extensions/muxio-tokio-rpc-client/Cargo.toml:16-19], [extensions/muxio-wasm-rpc-client/Cargo.toml:15-18].