Overview

Loading…

Overview

Relevant source files

• Cargo.toml
• DRAFT.md
• README.md

This document provides a comprehensive introduction to Muxio, covering its purpose, architecture, design principles, and workspace organization. It serves as the entry point for understanding how Muxio enables high-performance, cross-platform RPC communication through a layered multiplexing framework.

For detailed information about the workspace structure and package dependencies, see Workspace Structure. For design philosophy and architectural principles, see Design Philosophy and Layered Architecture. For core implementation details, see Core Library (muxio)).

What is Muxio?

Muxio is a toolkit for building transport-agnostic, runtime-agnostic RPC systems in Rust. It provides a foundational binary framing protocol for stream multiplexing, combined with a minimal RPC layer that can be extended for different runtime environments.

The framework solves three fundamental problems:

1. Stream Multiplexing : Managing multiple concurrent data streams over a single connection using binary framing
2. Cross-Platform RPC : Enabling the same service definitions to work across native (Tokio) and browser (WASM) environments
3. Type-Safe Communication : Enforcing API contracts at compile-time through shared service definitions

Sources: README.md:19-23 README.md:42-53 Cargo.toml:10-11

Core Architecture

Muxio implements a layered architecture where each layer has a distinct responsibility. The core muxio crate provides synchronous, callback-driven primitives, while extension crates add async runtime support.

graph TB
    subgraph "Application Layer"
        UserApp["User Application\n(Native or WASM)"]
ServiceDef["Service Definition Crate\nRpcMethodPrebuffered impls"]
end
    
    subgraph "RPC Abstraction Layer"
        CallerInterface["RpcServiceCallerInterface\nmuxio-rpc-service-caller"]
EndpointInterface["RpcServiceEndpointInterface\nmuxio-rpc-service-endpoint"]
RpcService["muxio-rpc-service\nCore traits and types"]
end
    
    subgraph "Runtime Implementations"
        TokioClient["RpcClient\nmuxio-tokio-rpc-client"]
WasmClient["RpcWasmClient\nmuxio-wasm-rpc-client"]
TokioServer["RpcServer\nmuxio-tokio-rpc-server"]
end
    
    subgraph "Core Transport Layer (muxio)"
        Dispatcher["RpcDispatcher\nRequest/response correlation"]
Session["RpcSession\nStream multiplexing"]
Decoder["RpcStreamDecoder\nFrame assembly"]
Types["RpcHeader, RpcRequest\nRpcResponse"]
end
    
    subgraph "Network Layer"
        TokioWS["tokio-tungstenite\nWebSocket"]
WasmBridge["wasm-bindgen\nBrowser WebSocket bridge"]
end
    
 
   UserApp --> ServiceDef
 
   ServiceDef --> CallerInterface
 
   ServiceDef --> EndpointInterface
    
 
   CallerInterface --> TokioClient
 
   CallerInterface --> WasmClient
 
   EndpointInterface --> TokioServer
    
 
   CallerInterface --> RpcService
 
   EndpointInterface --> RpcService
    
 
   TokioClient --> Dispatcher
 
   WasmClient --> Dispatcher
 
   TokioServer --> Dispatcher
    
 
   Dispatcher --> Session
 
   Dispatcher --> Types
 
   Session --> Decoder
 
   Session --> Types
    
 
   TokioClient --> TokioWS
 
   TokioServer --> TokioWS
 
   WasmClient --> WasmBridge

System Layers

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

Core Components and Their Responsibilities

Sources: Cargo.toml:20-30 README.md:36-41

Key Design Principles

Binary Protocol with Low Overhead

Muxio uses a compact binary format for all communication. Every message consists of:

• Frame headers with stream_id and frame_type
• RPC headers with msg_type, request_id, and method_id
• Binary payloads (no JSON parsing overhead)

This design minimizes serialization costs and network bandwidth usage.

Sources: README.md:33-34 README.md:46-47

Non-Async Core with Callbacks

The muxio core library is synchronous and uses callbacks instead of async/await. This enables:

• WASM compatibility (single-threaded JavaScript environments)
• Integration with any async runtime (Tokio, async-std, etc.)
• Simpler FFI boundaries for non-Rust languages

Sources: README.md:35-36 DRAFT.md:49-52

Transport Agnosticism

The core only requires a byte stream interface. It does not depend on WebSocket, TCP, or any specific transport. Runtime-specific implementations like muxio-tokio-rpc-client and muxio-wasm-rpc-client handle transport details.

Sources: README.md:35-36 README.md:52-53

graph LR
    ServiceDefCrate["example-muxio-rpc-service-definition"]
subgraph "Shared Definitions"
        AddMethod["Add::METHOD_ID\nAdd::encode_request\nAdd::decode_response"]
MultMethod["Mult::METHOD_ID\nMult::encode_request\nMult::decode_response"]
EchoMethod["Echo::METHOD_ID\nEcho::encode_request\nEcho::decode_response"]
end
    
    subgraph "Server Side"
        ServerEndpoint["endpoint.register_prebuffered"]
ServerHandler["Handler closure"]
DecodeReq["Add::decode_request"]
EncodeResp["Add::encode_response"]
end
    
    subgraph "Client Side"
        ClientCall["Add::call"]
EncodeReq["Add::encode_request"]
DecodeResp["Add::decode_response"]
end
    
 
   ServiceDefCrate --> AddMethod
 
   ServiceDefCrate --> MultMethod
 
   ServiceDefCrate --> EchoMethod
    
 
   AddMethod --> ServerEndpoint
 
   ServerEndpoint --> ServerHandler
 
   ServerHandler --> DecodeReq
 
   ServerHandler --> EncodeResp
    
 
   AddMethod --> ClientCall
 
   ClientCall --> EncodeReq
 
   ClientCall --> DecodeResp

Cross-Platform Type Safety

Service definitions are shared between client and server through a common crate. Both implement the same RpcMethodPrebuffered trait, ensuring compile-time verification that request and response types match.

Sources: README.md:50-51 README.md:70-119

graph TB
    subgraph "Root Package"
        MuxioCore["muxio\nCore framing & multiplexing\nNon-async, callback-driven"]
end
    
    subgraph "RPC Service Layer (extensions/)"
        RpcService["muxio-rpc-service\nCore RPC traits"]
RpcCaller["muxio-rpc-service-caller\nRpcServiceCallerInterface"]
RpcEndpoint["muxio-rpc-service-endpoint\nRpcServiceEndpointInterface"]
end
    
    subgraph "Runtime Implementations (extensions/)"
        TokioServer["muxio-tokio-rpc-server\nTokio + Axum server"]
TokioClient["muxio-tokio-rpc-client\nTokio WebSocket client"]
WasmClient["muxio-wasm-rpc-client\nwasm-bindgen client"]
end
    
    subgraph "Testing (extensions/)"
        ExtTest["muxio-ext-test\nIntegration tests"]
end
    
    subgraph "Examples (examples/)"
        ServiceDef["example-muxio-rpc-service-definition\nShared RPC methods"]
ExampleApp["example-muxio-ws-rpc-app\nComplete demo"]
end
    
 
   MuxioCore --> RpcService
 
   RpcService --> RpcCaller
 
   RpcService --> RpcEndpoint
    
 
   RpcCaller --> TokioClient
 
   RpcCaller --> WasmClient
 
   RpcEndpoint --> TokioServer
    
 
   MuxioCore --> TokioClient
 
   MuxioCore --> TokioServer
 
   MuxioCore --> WasmClient
    
 
   RpcService --> ServiceDef
 
   ServiceDef --> ExampleApp
 
   TokioServer --> ExampleApp
 
   TokioClient --> ExampleApp
    
 
   TokioServer --> ExtTest
 
   TokioClient --> ExtTest
 
   ServiceDef --> ExtTest

Workspace Organization

The repository is structured as a Cargo workspace with clear separation between core functionality, RPC abstractions, runtime implementations, and examples.

Workspace Structure

Package Dependency Table:

Sources: Cargo.toml:19-31 Cargo.toml:40-47

Quick Start: Key APIs

Defining an RPC Method

RPC methods are defined by implementing the RpcMethodPrebuffered trait with a unique METHOD_ID:

Sources: README.md:71-74 README.md:50-51

Server Registration

Handlers are registered on the RpcServiceEndpointInterface:

Sources: README.md:98-119

Client Invocation

Clients call methods through the RpcServiceCallerInterface:

Sources: README.md:146-152 README.md:48-49

Use Cases

Low-Latency Financial Data Streaming

The binary protocol and multiplexing enable efficient transmission of market data ticks over a single WebSocket connection, with separate streams per symbol.

Cross-Platform Applications

Write service logic once, then deploy to:

• Native desktop applications (via RpcClient)
• Web browsers (via RpcWasmClient)
• Mobile apps through FFI bindings

Real-Time Collaboration Tools

Multiple users can interact with the same server session, with each user action multiplexed over independent streams without head-of-line blocking.

Foreign Function Interfaces (FFI)

The byte-oriented core makes Muxio suitable as a bridge between Rust and other languages (C, C++, Python, Swift) through simple byte array passing.

Sources: README.md:44-53 DRAFT.md:9-26

Technology Stack

Sources: Cargo.toml:49-64

Version and Licensing

• Current Version : 0.10.0-alpha (pre-release)
• License : Apache-2.0
• Repository : https://github.com/jzombie/rust-muxio

All workspace members share the same version number and are published together.

Sources: Cargo.toml:1-7 README.md:164-166

Dismiss

Refresh this wiki

Enter email to refresh