Design Goals & Architecture Principles

Loading…

Design Goals & Architecture Principles

Relevant source files

• DRAFT.md
• README.md
• assets/Muxio-logo.svg
• extensions/README.md

The Muxio framework is built on a layered architecture designed to provide high-performance, multiplexed communication while remaining agnostic of specific network transports or async runtimes. This page details the core design philosophy and the architectural patterns that enable its cross-platform capabilities.

Core Design Philosophy

Muxio is engineered to solve the challenges of building modern distributed systems by prioritizing efficiency, type safety, and portability.

• Binary-First Protocol : Unlike text-based protocols (e.g., JSON-RPC), Muxio operates exclusively on raw bytes. This minimizes CPU overhead for parsing and reduces payload size README.md:46-47 It makes zero assumptions about serialization, supporting formats like CBOR, FlatBuffers, or raw bitcode DRAFT.md11
• Framed Transport : All data is transmitted in discrete, ordered binary chunks (frames), allowing for reliable reassembly of interleaved streams README.md32 DRAFT.md13
• Bidirectional Symmetry : The protocol is inherently symmetric; both the “client” and “server” can initiate requests, send streams, and handle responses using the same underlying logic DRAFT.md15 DRAFT.md25
• WASM Compatibility : By avoiding heavy dependencies on OS-specific networking or multi-threaded primitives in the core, Muxio is fully compatible with WebAssembly environments README.md:46-47 DRAFT.md17
• Runtime-Agnostic Model : The core library uses a non-async, callback-driven design. This allows it to be integrated into tokio, standard library threads, or single-threaded event loops (like browser JS) without imposing a specific execution model DRAFT.md:43-48
• Minimal Overhead : The binary framing protocol uses a compact 17-byte header (Stream ID, Sequence ID, Frame Kind, Timestamp), making it significantly more efficient than HTTP/2 or gRPC for high-frequency small messages README.md:44-45 README.md:58-59

Sources:

• README.md:32-33
• README.md:44-47
• README.md:58-59
• DRAFT.md:11-25
• DRAFT.md:43-48

Layered Architecture Principles

Muxio follows a “Layered Transport Kit” concept DRAFT.md3 Each layer has a specific responsibility and communicates with adjacent layers through standardized interfaces, primarily read_bytes and write_bytes DRAFT.md5

1. Frame Layer (The Foundation)

The bottom-most layer handles raw binary framing. It is responsible for taking a stream of bytes and identifying Frame boundaries, handling stream_id allocation, and managing FrameKind (Data, Heartbeat, Fin, Cancel, etc.) README.md:44-45

2. RPC Layer (The Dispatcher)

The RPC layer sits atop the Frame layer. It manages the lifecycle of individual “Sessions.” It correlates requests to responses using unique IDs and handles the multiplexing of multiple concurrent RPC streams over the single framed transport README.md:32-35

3. Service Extension Layer

This layer provides high-level abstractions like the RpcServiceCallerInterface and RpcServiceEndpointInterface. It allows developers to define strongly-typed API contracts using traits like RpcMethodPrebuffered and the rpc_method_id! macro for compile-time hashing README.md:40-42 README.md:60-61

4. Transport Implementation Layer

The outermost layer connects the Muxio logic to physical I/O. Examples include RpcServer (WebSockets over Tokio), RpcClient (Native Async), and RpcWasmClient (JavaScript-to-Rust byte bridge) README.md:52-54

Architecture Entity Mapping

The following diagram illustrates how natural language concepts map to specific code entities across the layers.

Muxio Architecture & Code Entity Map

graph TD
    subgraph "ApplicationSpace"
        Contract["Service Contract"]
Impl["Method Implementation"]
end

    subgraph "ServiceExtensionLayer"
 
       Contract -->|implements| RpcMethodPrebuffered["RpcMethodPrebuffered (trait)"]
Endpoint["RpcServiceEndpoint"] -->|registers| RpcMethodPrebuffered
 
       Caller["RpcServiceCallerInterface (trait)"] -->|invokes| RpcMethodPrebuffered
    end

    subgraph "CoreRpcLayer"
 
       RpcMethodPrebuffered -->|uses| RpcDispatcher["RpcDispatcher (struct)"]
RpcDispatcher -->|manages| RpcSession["RpcSession (struct)"]
RpcSession -->|tracks| StreamID["Stream ID (u32)"]
end

    subgraph "CoreFrameLayer"
 
       RpcDispatcher -->|encodes to| Frame["Frame (struct)"]
Frame -->|categorized by| FrameKind["FrameKind (enum)"]
Frame -->|processed by| FrameCodec["FrameCodec (struct)"]
end

    subgraph "TransportLayer"
 
       FrameCodec -->|IO_via| RpcServer["RpcServer (Tokio)"]
FrameCodec -->|IO_via| RpcWasmClient["RpcWasmClient (WASM)"]
FrameCodec -->|IO_via| RpcClient["RpcClient (Native)"]
end

Sources:

• README.md:32-45
• README.md:52-54
• README.md:60-61
• DRAFT.md:3-5

Data Flow: The Callback-Driven Model

Muxio’s core is “passive.” It does not spawn its own threads or async tasks. Instead, it relies on the transport layer to push bytes into it and provides callbacks for when it needs to send bytes back out DRAFT.md:43-48

1. Ingress : The transport (e.g., a WebSocket or IPC socket) receives raw bytes and calls the read_bytes function on the RpcDispatcher or RpcServiceEndpoint DRAFT.md5
2. Processing : The core decodes the bytes into a Frame. If it’s an RPC message, the RpcDispatcher correlates it to a session README.md:32-33
3. Dispatch : If the frame represents a new request, the RpcServiceEndpoint looks up the registered handler using the method_id README.md:40-42
4. Egress : When the handler produces a result, it is passed back down. The core calls a provided emit callback (often a closure capturing a network sink or a sender task) to send the response bytes back to the transport DRAFT.md:47-48

Bidirectional Data Flow and Interaction

Sources:

• README.md:32-42
• DRAFT.md5
• DRAFT.md:43-48

Design Summary Table

Sources:

• README.md:32-45
• README.md:58-65
• DRAFT.md3
• DRAFT.md:11-25