Workspace Structure

Loading…

Workspace Structure

Relevant source files

• Cargo.lock
• Cargo.toml

Purpose and Scope

This document details the Cargo workspace organization of the rust-muxio repository. It catalogs all workspace member crates, their locations in the directory tree, their roles within the overall system architecture, and their dependency relationships. For information about the design philosophy and layered architecture principles, see Design Philosophy and Layered Architecture.

Workspace Overview

The rust-muxio repository is organized as a Cargo workspace containing 11 member crates. The workspace is configured with resolver version 2 and defines shared metadata (version, authors, license, repository) inherited by all member crates.

Sources:

graph TB
    subgraph "Root Directory"
        ROOT["muxio (Root Crate)"]
end
    
    subgraph "extensions/"
        EXT_TEST["muxio-ext-test"]
RPC_SERVICE["muxio-rpc-service"]
RPC_CALLER["muxio-rpc-service-caller"]
RPC_ENDPOINT["muxio-rpc-service-endpoint"]
TOKIO_SERVER["muxio-tokio-rpc-server"]
TOKIO_CLIENT["muxio-tokio-rpc-client"]
WASM_CLIENT["muxio-wasm-rpc-client"]
end
    
    subgraph "examples/"
        EXAMPLE_APP["example-muxio-ws-rpc-app"]
EXAMPLE_DEF["example-muxio-rpc-service-definition"]
end
    
 
   ROOT -->|extends| RPC_SERVICE
 
   RPC_SERVICE -->|extends| RPC_CALLER
 
   RPC_SERVICE -->|extends| RPC_ENDPOINT
 
   RPC_CALLER -->|implements| TOKIO_CLIENT
 
   RPC_CALLER -->|implements| WASM_CLIENT
 
   RPC_ENDPOINT -->|implements| TOKIO_SERVER
 
   EXAMPLE_DEF -->|uses| RPC_SERVICE
 
   EXAMPLE_APP -->|demonstrates| EXAMPLE_DEF

• Cargo.toml:19-31
• Cargo.toml:1-17

Workspace Member Listing

The workspace members are declared in the root Cargo.toml and organized into three categories:

Sources:

• Cargo.toml:19-31
• Cargo.lock:426-954

Core Library: muxio

The root crate muxio (located at repository root .) provides the foundational binary framing protocol and stream multiplexing primitives. This crate is runtime-agnostic and has minimal dependencies.

Key Components:

• RpcDispatcher - Request correlation and response routing
• RpcSession - Stream multiplexing and per-stream decoders
• RpcStreamEncoder / RpcStreamDecoder - Frame encoding/decoding
• RpcRequest / RpcResponse / RpcHeader - Core message types

Direct Dependencies:

• bitcode - Binary serialization
• chrono - Timestamp generation
• once_cell - Lazy static initialization
• tracing - Structured logging

Dev Dependencies:

• rand - Random data generation for tests
• tokio - Async runtime for tests

Sources:

• Cargo.toml:9-17
• Cargo.toml:34-38
• Cargo.toml:67-70
• Cargo.lock:830-839

RPC Framework Extensions

muxio-rpc-service

Located at extensions/muxio-rpc-service, this crate provides trait definitions for RPC services and compile-time method ID generation.

Key Exports:

• RpcMethodPrebuffered trait - Defines prebuffered RPC method signatures
• DynamicChannelReceiver / DynamicChannelSender - Channel abstractions for streaming
• Method ID constants via xxhash-rust

Dependencies:

• muxio - Core framing and session management
• bitcode - Parameter/response serialization
• xxhash-rust - Compile-time method ID generation
• num_enum - Message type discrimination
• async-trait - Async trait support
• futures - Channel and stream utilities

Sources:

• Cargo.toml41
• Cargo.toml43
• Cargo.lock:858-867

muxio-rpc-service-caller

Located at extensions/muxio-rpc-service-caller, this crate defines the RpcServiceCallerInterface trait for platform-agnostic client-side RPC invocation.

Key Exports:

• RpcServiceCallerInterface trait - Abstract client interface
• Helper functions for invoking prebuffered and streaming methods

Dependencies:

• muxio - Core session and dispatcher
• muxio-rpc-service - Service definitions
• async-trait - Trait async support
• futures - Future combinators
• tracing - Instrumentation

Sources:

• Cargo.toml44
• Cargo.lock:870-880

muxio-rpc-service-endpoint

Located at extensions/muxio-rpc-service-endpoint, this crate defines the RpcServiceEndpointInterface trait for platform-agnostic server-side handler registration and request processing.

Key Exports:

• RpcServiceEndpointInterface trait - Abstract server interface
• Handler registration and dispatch utilities

Dependencies:

• muxio - Core dispatcher and session
• muxio-rpc-service - Service trait definitions
• muxio-rpc-service-caller - For bidirectional RPC (server-to-client calls)
• bitcode - Request/response deserialization
• async-trait - Trait async support
• futures - Channel management

Sources:

• Cargo.toml45
• Cargo.lock:883-895

Platform-Specific Extensions

muxio-tokio-rpc-server

Located at extensions/muxio-tokio-rpc-server, this crate provides a Tokio-based WebSocket RPC server implementation using Axum and tokio-tungstenite.

Key Exports:

• RpcServer struct - Main server implementation
• Axum WebSocket handler integration
• Connection lifecycle management

Dependencies:

• muxio - Core session primitives
• muxio-rpc-service - Service definitions
• muxio-rpc-service-caller - For bidirectional communication
• muxio-rpc-service-endpoint - Server endpoint interface
• axum - HTTP/WebSocket framework
• tokio - Async runtime
• tokio-tungstenite - WebSocket transport
• bytes - Byte buffer utilities
• futures-util - Stream combinators
• async-trait - Async trait implementations

Sources:

• Cargo.toml46
• Cargo.lock:918-932

muxio-tokio-rpc-client

Located at extensions/muxio-tokio-rpc-client, this crate provides a Tokio-based WebSocket RPC client with Arc-based lifecycle management and background task coordination.

Key Exports:

• RpcClient struct - Main client implementation
• Connection state tracking with RpcClientConnectionState
• Arc-based shared ownership model

Dependencies:

• muxio - Core dispatcher and session
• muxio-rpc-service - Service definitions
• muxio-rpc-service-caller - Client interface implementation
• muxio-rpc-service-endpoint - For bidirectional communication
• axum - (Used for shared types)
• tokio - Async runtime
• tokio-tungstenite - WebSocket transport
• bytes - Byte buffer utilities
• futures / futures-util - Async combinators
• async-trait - Trait async support

Sources:

• Cargo.toml47
• Cargo.lock:898-915

muxio-wasm-rpc-client

Located at extensions/muxio-wasm-rpc-client, this crate provides a WASM-compatible RPC client for browser environments using wasm-bindgen and JavaScript interop.

Key Exports:

• RpcWasmClient struct - WASM client implementation
• MUXIO_STATIC_RPC_CLIENT_REF - Thread-local static client reference
• JavaScript bridge functions (static_muxio_write_bytes, etc.)

Dependencies:

• muxio - Core framing and session
• muxio-rpc-service - Service definitions
• muxio-rpc-service-caller - Client interface
• muxio-rpc-service-endpoint - For bidirectional communication
• wasm-bindgen - JavaScript FFI
• js-sys - JavaScript API bindings
• wasm-bindgen-futures - Async/await in WASM
• futures / futures-util - Future utilities
• async-trait - Trait support

Sources:

• Cargo.toml28
• Cargo.lock:935-953

Testing Infrastructure

muxio-ext-test

Located at extensions/muxio-ext-test, this integration test crate validates end-to-end functionality across client and server implementations.

Test Coverage:

• Native client to native server communication
• Service definition validation
• Error handling and edge cases

Dependencies:

• muxio-rpc-service - Service trait testing
• muxio-rpc-service-caller - Client interface testing
• muxio-rpc-service-endpoint - Server endpoint testing
• muxio-tokio-rpc-client - Client implementation testing
• muxio-tokio-rpc-server - Server implementation testing
• example-muxio-rpc-service-definition - Test service definitions
• tokio - Async test runtime
• tracing / tracing-subscriber - Test instrumentation
• bytemuck - Binary data utilities

Sources:

• Cargo.toml22
• Cargo.lock:842-855

Example Applications

example-muxio-rpc-service-definition

Located at examples/example-muxio-rpc-service-definition, this crate defines shared RPC service contracts used across example applications.

Service Definitions:

• Basic arithmetic operations (Add, Multiply)
• Echo service
• Demonstrates RpcMethodPrebuffered trait implementation

Dependencies:

• muxio-rpc-service - Service trait definitions
• bitcode - Serialization for parameters and responses

Sources:

• Cargo.toml30
• Cargo.toml42
• Cargo.lock:426-431

example-muxio-ws-rpc-app

Located at examples/example-muxio-ws-rpc-app, this demonstration application shows complete client-server setup with WebSocket transport.

Demonstrates:

• Server instantiation with RpcServer
• Client connection with RpcClient
• Service handler registration
• RPC method invocation
• Benchmarking with criterion

Dependencies:

• example-muxio-rpc-service-definition - Shared service contracts
• muxio - Core primitives
• muxio-rpc-service-caller - Client calling
• muxio-tokio-rpc-client - Client implementation
• muxio-tokio-rpc-server - Server implementation
• tokio - Async runtime
• async-trait - Handler trait implementation
• criterion - Performance benchmarking
• futures - Async utilities
• tracing / tracing-subscriber - Application logging
• doc-comment - Documentation tests

Sources:

• Cargo.toml29
• Cargo.lock:434-449

Workspace Dependency Graph

Sources:

• Cargo.toml:40-47
• Cargo.lock:830-953

Directory Structure to Code Entity Mapping

Sources:

• Cargo.toml:19-31

Shared Workspace Configuration

All workspace member crates inherit common metadata from the workspace-level configuration:

Workspace-wide Third-Party Dependencies:

The workspace defines shared third-party dependency versions to ensure consistency:

Sources:

• Cargo.toml:1-8
• Cargo.toml32
• Cargo.toml:39-64

Crate Size and Complexity Metrics

Based on Cargo.lock dependency counts:

Sources:

• Cargo.lock:830-953