Examples & Demo Applications

Loading…

Examples & Demo Applications

Relevant source files

• LICENSE
• benches/README.md
• examples/example-muxio-rpc-service-definition/Cargo.toml
• examples/example-muxio-rpc-service-definition/src/lib.rs
• examples/example-muxio-rpc-service-definition/src/prebuffered.rs
• examples/example-muxio-ws-rpc-app/Cargo.toml

This section provides an overview of how the Muxio framework is utilized in practice through the provided example crates. The repository includes a structured approach to building RPC applications by separating the Service Definition (the “contract”) from the Application Implementation (the “logic”).

The examples demonstrate a complete end-to-end lifecycle: defining methods with bitcode serialization, registering handlers on a WebSocket server, and performing concurrent calls from a client.

High-Level Workflow

The Muxio example ecosystem is split into two primary crates to demonstrate best practices for code sharing in distributed systems. These extensions serve as both functional utilities and architectural templates for building on Muxio’s core.

System Entity Mapping

The following diagram bridges the gap between the conceptual “Service” and the specific code entities used to implement it within the Muxio framework.

Service Definition to Code Mapping

graph TD
    subgraph "Natural Language Space"
        Contract["Service Contract"]
Method["RPC Method"]
ID["Method Identifier"]
end

    subgraph "Code Entity Space"
        Trait["RpcMethodPrebuffered"]
Struct_Add["prebuffered::Add"]
Struct_Mult["prebuffered::Mult"]
Struct_Echo["prebuffered::Echo"]
Macro["rpc_method_id!"]
end

 
   Contract --> Trait
 
   Method --> Struct_Add
 
   Method --> Struct_Mult
 
   Method --> Struct_Echo
 
   ID --> Macro

    subgraph "Implementation Entities"
        Struct_Add -- "implements" --> Trait
        Struct_Mult -- "implements" --> Trait
        Struct_Echo -- "implements" --> Trait
        Macro -- "defines" --> ID_VAL["METHOD_ID"]
end

Sources: examples/example-muxio-rpc-service-definition/Cargo.toml:1-13 examples/example-muxio-rpc-service-definition/src/lib.rs:1-5 examples/example-muxio-rpc-service-definition/src/prebuffered.rs:1-9

Shared Service Definition Pattern

The example-muxio-rpc-service-definition crate serves as the single source of truth for the RPC interface. By defining methods in a shared crate, both the client and server are guaranteed to use the same serialization logic and method identifiers.

This pattern utilizes the RpcMethodPrebuffered trait examples/example-muxio-rpc-service-definition/src/lib.rs4 to define how data is moved across the wire. The example implementation includes:

• Add : Performs summation of Vec<f64> examples/example-muxio-rpc-service-definition/src/prebuffered.rs:1-2
• Mult : Performs multiplication of Vec<f64> examples/example-muxio-rpc-service-definition/src/prebuffered.rs:7-8
• Echo : A round-trip test returning the input Vec<u8> examples/example-muxio-rpc-service-definition/src/prebuffered.rs:4-5

For details on how to structure your own shared contracts and use the compile-time hashing macro, see Shared Service Definition Pattern.

Sources: examples/example-muxio-rpc-service-definition/Cargo.toml:2-12 examples/example-muxio-rpc-service-definition/src/lib.rs:1-5 examples/example-muxio-rpc-service-definition/src/prebuffered.rs:1-9

Full WebSocket RPC Application

The example-muxio-ws-rpc-app is a complete, runnable demonstration of the Muxio stack using the tokio runtime examples/example-muxio-ws-rpc-app/Cargo.toml17 It connects the service definitions to a live network transport.

Application Architecture & Code Entities

sequenceDiagram
    participant C as "RpcClient (muxio-tokio-rpc-client)"
    participant S as "RpcServer (muxio-tokio-rpc-server)"
    participant E as "RpcServiceEndpoint (muxio-rpc-service-endpoint)"

    Note over S, E: endpoint.register_prebuffered()
    C->>S: RpcCallPrebuffered::call(Add)
    S->>E: Dispatch by Add::METHOD_ID
    E-->>S: Add::encode_response()
    S-->>C: Response (Stream ID correlation)

This demo application showcases:

• Server Setup : Initializing RpcServer and registering method handlers using endpoint.register_prebuffered.
• Concurrency : Using tokio::join! to execute multiple RPC calls simultaneously over a single multiplexed connection.
• State Management : Monitoring connection lifecycle events via set_state_change_handler.
• Benchmarking : High-performance roundtrip tests defined in benches/roundtrip.rs examples/example-muxio-ws-rpc-app/Cargo.toml:25-28

For a step-by-step walkthrough of the server and client implementation, see example-muxio-ws-rpc-app: Full WebSocket RPC Application.

Sources: examples/example-muxio-ws-rpc-app/Cargo.toml:10-28 benches/README.md:1-2