muxio-rpc-service: Shared Service Definitions

Loading…

muxio-rpc-service: Shared Service Definitions

Relevant source files

• extensions/muxio-rpc-service/Cargo.toml
• extensions/muxio-rpc-service/README.md
• extensions/muxio-rpc-service/src/constants.rs
• extensions/muxio-rpc-service/src/macros.rs
• extensions/muxio-rpc-service/src/prebuffered/prebuffered_traits.rs
• extensions/muxio-rpc-service/src/result_status.rs

The muxio-rpc-service crate provides the foundational traits, constants, and macros required to define RPC service contracts within the Muxio framework extensions/muxio-rpc-service/Cargo.toml:2-3 It serves as the shared dependency between service providers (endpoints) and service consumers (callers), ensuring that both sides of a connection agree on method identifiers and serialization formats.

Core Service Abstractions

The crate centers around the “prebuffered” RPC model, where requests and responses are fully realized in memory before being processed or transmitted. This model simplifies service implementation by abstracting away the underlying stream-based transport.

RpcMethodPrebuffered Trait

The RpcMethodPrebuffered trait is the primary mechanism for defining a typed RPC method. It associates a unique u64 identifier with specific input and output types, along with their respective codec logic extensions/muxio-rpc-service/src/prebuffered/prebuffered_traits.rs:3-35

Sources: extensions/muxio-rpc-service/src/prebuffered/prebuffered_traits.rs:3-35

Compile-Time Method Identification

To avoid manual management of magic numbers for method IDs, muxio-rpc-service provides a deterministic hashing mechanism.

rpc_method_id! Macro

The rpc_method_id! macro uses the xxh3 (64-bit) algorithm to generate method identifiers from string literals at compile time extensions/muxio-rpc-service/src/macros.rs:35-40

• Deterministic: Produces the same hash across all platforms, including WASM and native extensions/muxio-rpc-service/src/macros.rs14
• Zero Runtime Cost: The hash is computed during compilation via method_id_hash and embedded as a constant extensions/muxio-rpc-service/src/macros.rs:3-5 extensions/muxio-rpc-service/src/macros.rs:37-38
• Collision Resistant: Uses xxhash-rust (specifically const_xxh3_64) to provide stable identifiers for RPC routing extensions/muxio-rpc-service/src/macros.rs1 extensions/muxio-rpc-service/src/macros.rs:17-21

Sources: extensions/muxio-rpc-service/src/macros.rs:1-40

Response Status Mapping

The crate defines the status of an RPC execution through the RpcResultStatus enum, which is used to communicate the outcome of a request across the wire.

RpcResultStatus Enum

This enum is represented as a u8 for efficient transport and categorizes the result of an RPC call extensions/muxio-rpc-service/src/result_status.rs:3-10:

• Success (0): The method executed successfully extensions/muxio-rpc-service/src/result_status.rs6
• Fail (1): Application-level failure (e.g., validation error) extensions/muxio-rpc-service/src/result_status.rs7
• SystemError (2): Internal framework or server error extensions/muxio-rpc-service/src/result_status.rs8
• MethodNotFound (3): The requested METHOD_ID is not registered on the endpoint extensions/muxio-rpc-service/src/result_status.rs9

Sources: extensions/muxio-rpc-service/src/result_status.rs:1-11

Constants and Configuration

Default values for transport and buffering are defined here to ensure consistency across implementations.

• DEFAULT_SERVICE_MAX_CHUNK_SIZE: Set to 64KB (65,536 bytes), defining the standard upper bound for RPC payload chunks extensions/muxio-rpc-service/src/constants.rs19
• DEFAULT_RPC_STREAM_CHANNEL_BUFFER_SIZE: Set to 8 items. This controls the MPSC channel depth for streaming RPC calls, balancing memory usage against network jitter absorption extensions/muxio-rpc-service/src/constants.rs32

Sources: extensions/muxio-rpc-service/src/constants.rs:1-33

Architecture & Data Flow Diagrams

RPC Service Definition Logic

This diagram illustrates how the RpcMethodPrebuffered trait bridges high-level types to the binary transport using the rpc_method_id! macro.

Sources: extensions/muxio-rpc-service/src/prebuffered/prebuffered_traits.rs:3-35 extensions/muxio-rpc-service/src/macros.rs:35-40

graph TD
    subgraph "Service Definition Space"
        A["RpcMethodPrebuffered Trait"]
B["METHOD_ID"]
M["rpc_method_id! Macro"]
end

    subgraph "Data Entities"
        I["Input Type"]
O["Output Type"]
end

    subgraph "Codec Logic"
        E1["encode_request(Input) -> Vec<u8>"]
D1["decode_request(&[u8]) -> Input"]
E2["encode_response(Output) -> Vec<u8>"]
D2["decode_response(&[u8]) -> Output"]
end

    M -- "Compile-time Hash" --> B
 
   A --> B
 
   A --> I
 
   A --> O
 
   I --> E1
 
   E1 -.-> D1
 
   O --> E2
 
   E2 -.-> D2

graph LR
    subgraph "Endpoint Execution"
        EXEC["Handler Execution"]
SUCCESS["Success (0)"]
APP_ERR["Fail (1)"]
SYS_ERR["SystemError (2)"]
NOT_FOUND["MethodNotFound (3)"]
end

    subgraph "Wire Representation"
        STATUS["RpcResultStatus (u8)"]
end

    subgraph "Caller Resolution"
        RES["Result<Output, Error>"]
end

 
   EXEC --> SUCCESS
 
   EXEC --> APP_ERR
 
   EXEC --> SYS_ERR
 
   EXEC --> NOT_FOUND

 
   SUCCESS --> STATUS
 
   APP_ERR --> STATUS
 
   SYS_ERR --> STATUS
 
   NOT_FOUND --> STATUS

 
   STATUS --> RES

Result Status Propagation

This diagram maps how RpcResultStatus categorizes the outcome of a service execution for the caller.

Sources: extensions/muxio-rpc-service/src/result_status.rs:3-10

Module Structure

The crate is organized into several modules to separate concerns:

• prebuffered: Contains the core RpcMethodPrebuffered trait definition extensions/muxio-rpc-service/src/prebuffered/prebuffered_traits.rs:3-35
• constants: Global defaults for chunk sizes and buffer depths extensions/muxio-rpc-service/src/constants.rs:1-33
• macros: Contains the method_id_hash function and the rpc_method_id! macro extensions/muxio-rpc-service/src/macros.rs:1-40
• result_status: Defines the RpcResultStatus enum for cross-wire error reporting extensions/muxio-rpc-service/src/result_status.rs:1-11

Sources: extensions/muxio-rpc-service/src/constants.rs:1-33 extensions/muxio-rpc-service/src/macros.rs:1-40 extensions/muxio-rpc-service/src/result_status.rs:1-11 extensions/muxio-rpc-service/src/prebuffered/prebuffered_traits.rs:3-35