RPC Service Extension Layer

Loading…

RPC Service Extension Layer

Relevant source files

• extensions/muxio-rpc-service-caller/Cargo.toml
• extensions/muxio-rpc-service-endpoint/Cargo.toml
• extensions/muxio-rpc-service/Cargo.toml

The RPC Service Extension Layer provides high-level abstractions for defining, calling, and handling RPC services. While the core muxio crate handles the mechanics of binary framing and stream multiplexing, this layer introduces structured service definitions, client-side calling interfaces, and server-side handler registries.

These extensions are split into three primary crates to ensure a clear separation of concerns between shared definitions, client logic, and server logic.

Layered Architecture Overview

The following diagram illustrates how the RPC Service Extension crates sit between the low-level muxio core and the final transport implementations (like WebSocket or IPC).

Service Extension Topology

graph TD
    subgraph "Application Space"
        [ServiceDefinition] --> |implements| [RpcMethodPrebuffered]
    end

    subgraph "RPC Service Extension Layer"
        [muxio-rpc-service-caller] -.-> [muxio-rpc-service]
        [muxio-rpc-service-endpoint] -.-> [muxio-rpc-service]
    end

    subgraph "Muxio Core"
        [muxio-rpc-service-caller] --> [RpcDispatcher]
        [muxio-rpc-service-endpoint] --> [RpcRespondableSession]
    end

    [muxio-rpc-service-caller] --- [muxio-tokio-rpc-client]
    [muxio-rpc-service-endpoint] --- [muxio-tokio-rpc-server]

Sources:

• extensions/muxio-rpc-service/Cargo.toml:1-3
• extensions/muxio-rpc-service-caller/Cargo.toml:1-3
• extensions/muxio-rpc-service-endpoint/Cargo.toml:1-3

muxio-rpc-service: Shared Service Definitions

The muxio-rpc-service crate defines the “language” that both clients and servers speak. It focuses on compile-time safety and efficient serialization using bitcode extensions/muxio-rpc-service/Cargo.toml12

• Trait-Based Definitions : Uses the RpcMethodPrebuffered trait to define RPC methods, associating them with specific request and response types.
• Compile-Time Hashing : Provides the rpc_method_id! macro, which uses xxhash-rust extensions/muxio-rpc-service/Cargo.toml14 at compile-time to generate unique u64 identifiers for methods based on their names.
• Standardized Results : Defines RpcResultStatus and RpcServiceError to ensure consistent error propagation across the network.
• Configuration : Sets the DEFAULT_SERVICE_MAX_CHUNK_SIZE for prebuffered message fragmentation.

For details, see muxio-rpc-service: Shared Service Definitions.

Sources:

• extensions/muxio-rpc-service/Cargo.toml:1-15

muxio-rpc-service-caller: Client-Side Calling Interface

The muxio-rpc-service-caller crate provides the interface used by clients to initiate RPC requests. It abstracts the underlying RpcDispatcher into a more ergonomic API using async-trait extensions/muxio-rpc-service-caller/Cargo.toml12

• Caller Interface : The RpcServiceCallerInterface trait defines how a client interacts with the transport, including get_dispatcher, get_emit_fn, and checking is_connected status.
• Typed Calling : Provides call_rpc_buffered and call_rpc_streaming methods that automatically handle serialization and deserialization based on the RpcMethodPrebuffered definition.
• State Management : Tracks the RpcTransportState (e.g., Connected, Disconnected) and allows applications to react to lifecycle events via set_state_change_handler.
• Dynamic Channels : Utilizes DynamicChannel (Bounded or Unbounded) to manage asynchronous data flow for streaming calls, backed by tokio::sync extensions/muxio-rpc-service-caller/Cargo.toml16

For details, see muxio-rpc-service-caller: Client-Side Calling Interface.

Sources:

• extensions/muxio-rpc-service-caller/Cargo.toml:1-17

muxio-rpc-service-endpoint: Server-Side Handler Registry

The muxio-rpc-service-endpoint crate manages the server-side logic for receiving requests and routing them to the appropriate handlers.

• Handler Registration : The RpcServiceEndpoint struct allows developers to register handlers for specific method IDs using register_prebuffered.
• Execution Pipeline : Implements a three-stage read_bytes pipeline for incoming data:
  1. Decode : Incoming bytes are decoded into the request type using bitcode extensions/muxio-rpc-service-endpoint/Cargo.toml17
  2. Execute : The registered RpcPrebufferedHandler is executed (optionally concurrently).
  3. Emit : The result is serialized and sent back to the client via the response emission logic.
• Concurrency : Includes support for tokio to handle concurrent request processing via the tokio_support feature flag extensions/muxio-rpc-service-endpoint/Cargo.toml13 managing handlers through a HandlersLock.

For details, see muxio-rpc-service-endpoint: Server-Side Handler Registry.

Sources:

• extensions/muxio-rpc-service-endpoint/Cargo.toml:1-24

Entity Mapping: Extension to Core

The following table maps the high-level Extension Layer concepts to the low-level Core entities they wrap or utilize.

Sources:

• extensions/muxio-rpc-service/Cargo.toml:12-14
• extensions/muxio-rpc-service-caller/Cargo.toml:14-16
• extensions/muxio-rpc-service-endpoint/Cargo.toml:20-23