Overview

Loading…

Overview

Relevant source files

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

Purpose and Scope

This document provides a high-level introduction to the rust-muxio repository, explaining its purpose as a toolkit for building high-performance, multiplexed RPC systems. It covers the foundational architecture, the layered design philosophy, and how the different components of the system work together to enable efficient, cross-platform communication.

For detailed information about specific subsystems, see:

• Workspace organization: Workspace Structure
• Core design principles: Design Philosophy
• Low-level implementation: Core Library (muxio))
• RPC framework usage: RPC Framework
• Platform-specific implementations: Platform Implementations

Sources : README.md:1-18 Cargo.toml:9-17

What is Muxio?

Muxio is a layered transport toolkit for building multiplexed, binary RPC systems in Rust. It separates concerns across three distinct architectural layers:

The system is designed around two key principles:

1. Runtime Agnosticism : The core library (muxio) uses a callback-driven, non-async model that works in any Rust environment—Tokio, WASM, single-threaded, or multi-threaded contexts.

2. Layered Abstraction : Each layer provides a clean interface to the layer above, enabling developers to build custom transports or replace individual components without affecting the entire stack.

Sources : README.md:19-41 Cargo.toml:19-31

System Architecture

The following diagram illustrates the complete system architecture, showing how components in the workspace relate to each other:

Sources : Cargo.toml:19-31 README.md:23-41 Cargo.lock:830-954

graph TB
    subgraph Core["Core Foundation (muxio crate)"]
RpcDispatcher["RpcDispatcher\nRequest Correlation\nResponse Routing"]
RpcSession["RpcSession\nStream Multiplexing\nFrame Mux/Demux"]
FrameProtocol["Binary Framing\nRpcHeader + Payload Chunks"]
RpcDispatcher --> RpcSession
 
       RpcSession --> FrameProtocol
    end
    
    subgraph RPCFramework["RPC Framework Layer"]
RpcService["muxio-rpc-service\nRpcMethodPrebuffered Trait\nxxhash Method IDs"]
RpcCaller["muxio-rpc-service-caller\nRpcServiceCallerInterface\nGeneric Client Logic"]
RpcEndpoint["muxio-rpc-service-endpoint\nRpcServiceEndpointInterface\nHandler Registration"]
RpcCaller --> RpcService
 
       RpcEndpoint --> RpcService
    end
    
    subgraph NativeExt["Native Platform Extensions"]
TokioServer["muxio-tokio-rpc-server\nRpcServer + Axum\nWebSocket Transport"]
TokioClient["muxio-tokio-rpc-client\nRpcClient\ntokio-tungstenite"]
TokioServer --> RpcEndpoint
 
       TokioServer --> RpcCaller
 
       TokioClient --> RpcCaller
 
       TokioClient --> RpcEndpoint
    end
    
    subgraph WASMExt["WASM Platform Extensions"]
WasmClient["muxio-wasm-rpc-client\nRpcWasmClient\nwasm-bindgen Bridge"]
WasmClient --> RpcCaller
 
       WasmClient --> RpcEndpoint
    end
    
    subgraph AppLayer["Application Layer"]
ServiceDef["example-muxio-rpc-service-definition\nShared Service Contracts"]
ExampleApp["example-muxio-ws-rpc-app\nDemo Application"]
ServiceDef --> RpcService
 
       ExampleApp --> ServiceDef
 
       ExampleApp --> TokioServer
 
       ExampleApp --> TokioClient
    end
    
 
   RpcCaller --> RpcDispatcher
 
   RpcEndpoint --> RpcDispatcher
    
 
   TokioClient <-->|Binary Frames| TokioServer
 
   WasmClient <-->|Binary Frames| TokioServer

Core Components and Their Roles

muxio Core (muxio)

The foundational crate provides three critical components:

• RpcSession : Manages stream multiplexing over a single connection. Allocates stream IDs, maintains per-stream decoders, and handles frame interleaving. Located at src/rpc/rpc_internals/rpc_session.rs:16-21

• RpcDispatcher : Correlates RPC requests with responses using unique request IDs. Tracks pending requests in a HashMap and routes responses to the appropriate callback. Located at src/rpc/rpc_dispatcher.rs:19-30

• Binary Framing Protocol : A schemaless, low-overhead protocol that chunks payloads into frames with minimal headers. Each frame contains a stream ID, flags, and a payload chunk. Defined at src/rpc/rpc_internals/rpc_session.rs:16-21

RPC Framework Layer

• muxio-rpc-service : Defines the RpcMethodPrebuffered trait for creating shared service contracts. Uses xxhash-rust to generate compile-time method IDs from method names. Located at extensions/muxio-rpc-service/

• muxio-rpc-service-caller : Provides the RpcServiceCallerInterface trait, which abstracts client-side RPC invocation. Any client implementation (Tokio, WASM, custom) must implement this interface. Located at extensions/muxio-rpc-service-caller/

• muxio-rpc-service-endpoint : Provides the RpcServiceEndpointInterface trait for server-side handler registration and request dispatch. Located at extensions/muxio-rpc-service-endpoint/

Platform Extensions

• muxio-tokio-rpc-server : Implements RpcServer using Axum for HTTP/WebSocket serving and tokio-tungstenite for WebSocket framing. Located at extensions/muxio-tokio-rpc-server/

• muxio-tokio-rpc-client : Implements RpcClient with Arc-based lifecycle management and background tasks for connection handling. Located at extensions/muxio-tokio-rpc-client/

• muxio-wasm-rpc-client : Implements RpcWasmClient using wasm-bindgen to bridge Rust to JavaScript. Communicates with browser WebSocket APIs via a static byte-passing interface. Located at extensions/muxio-wasm-rpc-client/

Sources : Cargo.toml:40-47 Cargo.lock:830-954 README.md:36-41

Key Design Characteristics

graph LR
    subgraph CorePrimitives["Core Primitives (Non-Async)"]
RpcDispatcher["RpcDispatcher\nBox<dyn Fn> Callbacks"]
RpcSession["RpcSession\nCallback-Driven Events"]
end
    
    subgraph TokioRuntime["Tokio Runtime"]
TokioClient["RpcClient\nArc + TokioMutex"]
TokioServer["RpcServer\ntokio::spawn Tasks"]
end
    
    subgraph WASMRuntime["WASM Runtime"]
WasmClient["RpcWasmClient\nthread_local RefCell"]
JSBridge["JavaScript Bridge\nstatic_muxio_write_bytes"]
end
    
    subgraph CustomRuntime["Custom Runtime"]
CustomImpl["Custom Implementation\nUser-Defined Threading"]
end
    
 
   CorePrimitives --> TokioRuntime
 
   CorePrimitives --> WASMRuntime
 
   CorePrimitives --> CustomRuntime
    
 
   TokioClient --> RpcDispatcher
 
   TokioServer --> RpcDispatcher
 
   WasmClient --> RpcDispatcher
 
   CustomImpl --> RpcDispatcher

Runtime-Agnostic Core

The following diagram shows how the non-async, callback-driven core enables cross-runtime compatibility:

Key Implementation Details :

• Callback Closures : Both RpcDispatcher and RpcSession accept Box<dyn Fn(...)> callbacks rather than returning Futures, enabling use in any execution context.

• No Async Core : The muxio crate itself has no async functions in its public API. All asynchrony is introduced by the platform extensions (muxio-tokio-rpc-client, etc.).

• Flexible Synchronization : Platform extensions choose their own synchronization primitives—TokioMutex for Tokio, RefCell for WASM, or custom locking for other runtimes.

Sources : README.md:35-36 Cargo.lock:830-839

Type Safety Through Shared Definitions

Muxio enforces compile-time type safety by requiring shared service definitions between client and server:

Both client and server depend on the same service definition crate. If a client attempts to call a method with the wrong parameter types, or if the server returns a response with the wrong type, the code will not compile.

Example fromexample-muxio-rpc-service-definition:

Sources : README.md:50-51 Cargo.lock:426-431 examples/example-muxio-rpc-service-definition/

graph TB
    subgraph ServerSide["Server-Side Deployment"]
RpcServer["RpcServer\nAxum + WebSocket"]
TokioRuntime["Tokio Runtime\nMulti-threaded Executor"]
RpcServer --> TokioRuntime
    end
    
    subgraph NativeClient["Native Client Deployment"]
RpcClient["RpcClient\ntokio-tungstenite"]
TokioClientRuntime["Tokio Runtime\nAsync Tasks"]
RpcClient --> TokioClientRuntime
    end
    
    subgraph WASMClient["WASM Browser Client"]
RpcWasmClient["RpcWasmClient\nwasm-bindgen"]
JSHost["JavaScript Host\nWebSocket APIs"]
RpcWasmClient --> JSHost
    end
    
    subgraph SharedContract["Shared Service Definition"]
ServiceDef["example-muxio-rpc-service-definition\nAdd, Mult, Echo Methods"]
end
    
 
   RpcClient <-->|Binary Protocol| RpcServer
 
   RpcWasmClient <-->|Binary Protocol| RpcServer
    
    RpcClient -.depends on.-> ServiceDef
    RpcWasmClient -.depends on.-> ServiceDef
    RpcServer -.depends on.-> ServiceDef

Deployment Configurations

Muxio supports multiple deployment configurations, all using the same binary protocol:

Key Characteristics :

1. Same Service Definitions : All clients and servers depend on the same service definition crate, ensuring API consistency across platforms.

2. Binary Protocol Compatibility : Native clients, WASM clients, and servers all communicate using identical binary framing and serialization (via bitcode).

3. Platform-Specific Transports : Each platform extension provides its own WebSocket transport implementation—tokio-tungstenite for native, browser APIs for WASM.

Sources : README.md:66-161 Cargo.lock:898-954

Summary

Muxio provides a three-layer architecture for building efficient, cross-platform RPC systems:

1. Core Layer (muxio): Binary framing, stream multiplexing, request/response correlation—all using callback-driven, non-async primitives.

2. RPC Framework Layer : Service definitions with compile-time method IDs, generic caller/endpoint interfaces, and type-safe abstractions.

3. Platform Extensions : Concrete implementations for Tokio (native) and WASM (browser) environments, both implementing the same abstract interfaces.

The system prioritizes low-latency communication (via compact binary protocol), type safety (via shared service definitions), and runtime flexibility (via callback-driven core).

For implementation details, see:

• Core Library (muxio)) for framing and multiplexing internals
• RPC Framework for service definition patterns
• Platform Implementations for Tokio and WASM client/server usage

Sources : README.md:1-163 Cargo.toml:1-71 Cargo.lock:830-954