This documentation is part of the "Projects with Books" initiative at zenOSmosis.

The source code for this project is available on GitHub.

Getting Started & Workspace Layout

Loading…

Getting Started & Workspace Layout

Relevant source files

This page provides a technical overview of the rust-muxio repository structure, its dependency management strategy, and the processes for building, testing, and deploying the framework. Muxio is organized as a Cargo workspace to facilitate modular development of its core multiplexing engine and its various transport and service extensions.

Cargo Workspace Structure

The project utilizes a Cargo workspace to manage multiple interconnected crates. This allows for a “layered transport kit” approach where users can opt into specific transport implementations (like Tokio, IPC, or WASM) without pulling in unnecessary dependencies.

Member Crates

The workspace is divided into the core library, extensions, and example applications.

Category	Crate Path	Description
Core	`.`	The root `muxio` crate which re-exports `muxio-core` and optional extensions.
Core	`core/`	The foundational `muxio-core` containing binary framing and RPC dispatch logic.
Extensions	`extensions/muxio-rpc-service`	Shared traits and macros for defining RPC methods.
Extensions	`extensions/muxio-rpc-service-caller`	Client-side abstractions for making RPC calls.
Extensions	`extensions/muxio-rpc-service-endpoint`	Server-side registry and execution pipeline for RPC handlers.
Extensions	`extensions/muxio-tokio-mpsc-adapter`	MPSC channel wrapper for streaming RPCs.
Extensions	`extensions/muxio-tokio-rpc-client`	Async client implementation using `tokio` and `tokio-tungstenite`.
Extensions	`extensions/muxio-tokio-rpc-server`	WebSocket server implementation using `axum`.
Extensions	`extensions/muxio-tokio-rpc-ipc-client`	Unix Domain Socket / Windows Named Pipe client.
Extensions	`extensions/muxio-tokio-rpc-ipc-server`	Unix Domain Socket / Windows Named Pipe server.
Extensions	`extensions/muxio-wasm-rpc-client`	Browser-compatible client for WASM environments.
Testing	`extensions/muxio-ext-test`	Internal harness for cross-crate integration testing.
Examples	`examples/example-muxio-rpc-service-definition`	Demo of a shared service contract.
Examples	`examples/example-muxio-ws-rpc-app`	End-to-end WebSocket RPC demo application.

Sources: Cargo.toml:16-32 Cargo.toml:51-65

Shared Dependency Management

Muxio leverages workspace-level dependency inheritance to ensure version consistency across all member crates. Common attributes such as version, edition, and repository are defined once in the root Cargo.toml.

Workspace Package Metadata: Defines the global version (e.g., 0.12.0-alpha) and edition (2024). Cargo.toml:34-40
Dependency Inheritance: Centralized versions for critical libraries like tokio (1.52.3), axum (0.8.9), bitcode, and futures are managed in the [workspace.dependencies] table. Cargo.toml:42-75
Crate Usage: Individual crates reference these using workspace = true. The root muxio crate re-exports extensions based on feature flags like rpc-service-caller or tokio-rpc-server. Cargo.toml:77-109

Workspace Layout Diagram

The following diagram maps the logical layers of the framework to the physical crate entities within the workspace.

Workspace Entity Map

graph TD
    subgraph "Application_Space"
        APP["example-muxio-ws-rpc-app"]
DEF["example-muxio-rpc-service-definition"]
end

    subgraph "Transport_Extensions"
        TOK_S["muxio-tokio-rpc-server"]
TOK_C["muxio-tokio-rpc-client"]
WASM_C["muxio-wasm-rpc-client"]
IPC_S["muxio-tokio-rpc-ipc-server"]
IPC_C["muxio-tokio-rpc-ipc-client"]
MPSC["muxio-tokio-mpsc-adapter"]
end

    subgraph "Service_Abstraction"
        EP["muxio-rpc-service-endpoint"]
CALL["muxio-rpc-service-caller"]
SVC["muxio-rpc-service"]
end

    subgraph "Core_Engine"
        ROOT["muxio_(root)"]
CORE["muxio-core"]
end

 
   APP --> DEF
 
   APP --> TOK_S
 
   APP --> TOK_C
 
   TOK_S --> EP
 
   TOK_C --> CALL
 
   WASM_C --> CALL
 
   IPC_S --> EP
 
   IPC_C --> CALL
 
   MPSC --> EP
 
   MPSC --> CALL
 
   EP --> SVC
 
   CALL --> SVC
 
   SVC --> CORE
 
   ROOT --> CORE
 
   DEF --> SVC

Sources: Cargo.toml:16-32 Cargo.toml:51-65 Cargo.toml:98-109

CI/CD Pipeline & Quality Control

The project employs a robust CI/CD suite via GitHub Actions to maintain code quality across different operating systems and feature configurations.

Rust Tests Pipeline

The rust-tests.yml workflow ensures cross-platform compatibility by running the test suite on ubuntu-latest, macos-latest, and windows-latest. [ .github/workflows/rust-tests.yml25-26](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .github/workflows/rust-tests.yml#L25-L26)

Key steps include:

Cargo All-Features: Validates that the codebase compiles and passes tests under every possible combination of feature flags using --all-features. [ .github/workflows/rust-tests.yml78](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .github/workflows/rust-tests.yml#L78-L78)
Workspace Testing: Runs cargo test --workspace --all-features --lib --bins --tests --examples to include integration tests and examples. [ .github/workflows/rust-tests.yml78](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .github/workflows/rust-tests.yml#L78-L78)
Coverage: Uses cargo-llvm-cov to generate coverage reports. [ .github/workflows/rust-tests.yml104-123](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .github/workflows/rust-tests.yml#L104-L123)

Rust Lint & Security Pipeline

The rust-lint.yml workflow enforces strict coding standards and security audits. [ .github/workflows/rust-lint.yml1-6](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .github/workflows/rust-lint.yml#L1-L6)

Formatting: Checks compliance with cargo fmt --all -- --check. [ .github/workflows/rust-lint.yml130-131](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .github/workflows/rust-lint.yml#L130-L131)
Clippy: Runs with -D warnings to treat all lints as build failures. [ .github/workflows/rust-lint.yml134-135](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .github/workflows/rust-lint.yml#L134-L135)
Unused Dependencies: Uses cargo-udeps to find unused crates in the workspace. [ .github/workflows/rust-lint.yml61-62](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .github/workflows/rust-lint.yml#L61-L62)
Security Audits:
- cargo deny: Validates licenses (allowing MIT, Apache-2.0, etc.) and checks for advisory vulnerabilities. [ .github/workflows/rust-lint.yml142-143](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .github/workflows/rust-lint.yml#L142-L143) [ .cargo/deny.toml1-9](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .cargo/deny.toml#L1-L9)
- cargo audit: Scans Cargo.lock for crates with known security vulnerabilities. [ .github/workflows/rust-lint.yml146-147](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .github/workflows/rust-lint.yml#L146-L147)

Documentation Deployment

A weekly cron job and manual trigger facilitate the deployment of the documentation to GitHub Pages using a custom DeepWiki generator. [ .github/workflows/build-docs.yml4-7](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .github/workflows/build-docs.yml#L4-L7) [ .github/workflows/build-docs.yml59-64](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .github/workflows/build-docs.yml#L59-L64)

Building and Running the Example

To explore the framework, the example-muxio-ws-rpc-app provides a complete implementation of a WebSocket-based RPC server and client.

sequenceDiagram
    participant App as "example-muxio-ws-rpc-app"
    participant Server as "muxio_tokio_rpc_server::RpcServer"
    participant Endpoint as "muxio_rpc_service_endpoint::RpcServiceEndpoint"
    participant Client as "muxio_tokio_rpc_client::RpcClient"
    participant Dispatcher as "muxio_core::rpc::RpcDispatcher"

    Note over App: Register Handlers
    App->>Endpoint: register_prebuffered(MethodID, Handler)
    App->>Server: new(Endpoint).serve(addr)
    
    Note over App: Connect Client
    App->>Client: new(url).connect()
    
    Note over App: Execute RPC
    App->>Client: call_rpc_buffered(Request)
    Client->>Dispatcher: call(RequestBytes)
    Dispatcher-->>Server: [Binary Frame over WS]
    Server->>Endpoint: read_bytes(Frame)
    Endpoint->>App: [Execute Handler Logic]
    App-->>Endpoint: Response
    Endpoint-->>Dispatcher: [Binary Frame over WS]
    Dispatcher-->>App: Future Resolves with Response

Data Flow: Example Application

This diagram illustrates the interaction between the example application and the underlying workspace crates, highlighting key types and methods used during an RPC lifecycle.

Example Execution Flow

Sources: Cargo.toml:17-32 Cargo.toml:51-65

Testing Infrastructure: muxio-ext-test

The extensions/muxio-ext-test crate serves as a specialized testing harness to avoid circular dependencies between transport crates and service crates.

Test Suites: Contains generic test suites like streaming_handler_tests and mpsc_adapter_tests that are exercised across different transports (WS, IPC, WASM). [ .opencode/plans/1782849738403-silent-moon.md130-141](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .opencode/plans/1782849738403-silent-moon.md?plain=1#L130-L141)
MPSC Adapter: Provides ChannelEndpointExt and ChannelCallerExt for simplified streaming using tokio::mpsc channels. [ .opencode/plans/1782849738403-silent-moon.md30-61](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .opencode/plans/1782849738403-silent-moon.md?plain=1#L30-L61)

Commands

From the root of the workspace:

Build everything: cargo build --workspace --all-features
Run tests: cargo test --workspace --all-features
Run the example app: cargo run -p example-muxio-ws-rpc-app

Sources: Cargo.toml:16-32 [ .github/workflows/rust-tests.yml78](https://github.com/jzombie/rust-muxio/blob/a2d43b2a/ .github/workflows/rust-tests.yml#L78-L78)

Keyboard shortcuts

rust-muxio Documentation