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

Loading…

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

Relevant source files

• extensions/muxio-rpc-service-caller/Cargo.toml
• extensions/muxio-rpc-service-caller/README.md
• extensions/muxio-rpc-service-caller/src/caller_interface.rs
• extensions/muxio-rpc-service-caller/src/dynamic_channel.rs
• extensions/muxio-rpc-service-caller/src/transport_state.rs
• extensions/muxio-rpc-service-caller/src/write_channel.rs
• extensions/muxio-rpc-service-endpoint/README.md
• extensions/muxio-tokio-rpc-server/src/rpc_server.rs

The muxio-rpc-service-caller crate provides a high-level, runtime-agnostic interface for building Muxio RPC clients extensions/muxio-rpc-service-caller/Cargo.toml:2-3 It abstracts the complexities of stream lifecycle management, request correlation, and payload chunking into a simplified calling API.

RpcServiceCallerInterface

The core of the client-side logic is the RpcServiceCallerInterface trait. It defines the minimum set of capabilities a transport (like Tokio or WASM) must provide to support RPC calls extensions/muxio-rpc-service-caller/src/caller_interface.rs:25-31

Key Methods

RPC Call Data Flow

The following diagram illustrates how a call moves from the high-level interface through the dispatcher to the transport.

Client-Side Call Flow

sequenceDiagram
    participant User as "User Code"
    participant Caller as "RpcServiceCallerInterface"
    participant Disp as "RpcDispatcher"
    participant Trans as "Transport (Emit)"

    User->>Caller: call_rpc_streaming(RpcRequest)
    Caller->>Disp: register_session()
    Disp-->>Caller: RpcSession (StreamID)
    Caller->>Trans: emit(HeaderFrame)
    Caller-->>User: (RpcStreamEncoder, DynamicReceiver)
    
    Note over User, Trans: Data Streaming Phase
    
    User->>Caller: encoder.write_payload(chunk)
    Caller->>Trans: emit(PayloadFrame)
    
    Trans-->>Caller: recv_fn(RpcStreamEvent)
    Caller->>User: DynamicReceiver.next()

Sources: extensions/muxio-rpc-service-caller/src/caller_interface.rs:33-187 extensions/muxio-rpc-service-caller/src/caller_interface.rs:189-224

Dynamic Channels

To handle asynchronous responses, the caller uses DynamicChannel, which provides a unified interface over both bounded and unbounded futures::channel::mpsc channels extensions/muxio-rpc-service-caller/src/dynamic_channel.rs:11-16

• DynamicSender : Wraps Sender or UnboundedSender. It includes a send_and_ignore method that handles channel errors gracefully (e.g., if the caller dropped the receiver) extensions/muxio-rpc-service-caller/src/dynamic_channel.rs:21-45
• DynamicReceiver : Implements the Stream trait, allowing users to consume response chunks via while let Some(...) = stream.next().await extensions/muxio-rpc-service-caller/src/dynamic_channel.rs:48-75

Sources: extensions/muxio-rpc-service-caller/src/dynamic_channel.rs:1-76

RpcCallPrebuffered Blanket Implementation

The RpcCallPrebuffered trait provides a “smart” transport strategy for RPC methods defined using the RpcMethodPrebuffered pattern extensions/muxio-rpc-service-caller/src/prebuffered/traits.rs:11-21

Smart Transport Strategy

Because a single Muxio frame header is limited (typically ~64KB), the implementation automatically decides how to send arguments:

1. Small Arguments : If the encoded input is smaller than DEFAULT_SERVICE_MAX_CHUNK_SIZE, it is sent inside the rpc_param_bytes field of the initial header frame extensions/muxio-rpc-service-caller/src/prebuffered/traits.rs:63-65
2. Large Arguments : If the input is large, it is placed in rpc_prebuffered_payload_bytes. The RpcDispatcher then automatically chunks and streams this data as subsequent payload frames extensions/muxio-rpc-service-caller/src/prebuffered/traits.rs:59-61

Entity Mapping: Prebuffered Call

Sources: extensions/muxio-rpc-service-caller/src/prebuffered/traits.rs:30-74 extensions/muxio-rpc-service-caller/src/caller_interface.rs:189-200

Write Loop and Backpressure

The write_channel module provides spawn_write_loop, which manages the outbound message queue for a connection extensions/muxio-rpc-service-caller/src/write_channel.rs:34-41

• Unbounded Channel : Uses an mpsc::unbounded_channel to prevent blocking the synchronous write_bytes call in the framing layer extensions/muxio-rpc-service-caller/src/write_channel.rs:9-16
• Stall Prevention : By using an unbounded channel at the connection level, the system ensures that a slow stream does not immediately block all other streams sharing the same physical transport extensions/muxio-rpc-service-caller/src/write_channel.rs:11-16

Sources: extensions/muxio-rpc-service-caller/src/write_channel.rs:1-54

Transport State and Error Handling

RpcTransportState

The client tracks the connection status using the RpcTransportState enum:

• Connected: Transport is active and ready for calls extensions/muxio-rpc-service-caller/src/transport_state.rs3
• Disconnected: Transport is closed; new calls will be rejected immediately extensions/muxio-rpc-service-caller/src/transport_state.rs4
• Connecting: Transport is establishing a connection extensions/muxio-rpc-service-caller/src/transport_state.rs5

Error Handling

Errors are encapsulated in the RpcServiceError type.

• Immediate Rejection : If is_connected() is false, call_rpc_streaming returns io::ErrorKind::ConnectionAborted extensions/muxio-rpc-service-caller/src/caller_interface.rs:44-53
• Remote Errors : If the server returns an error status (e.g., Fail, System), the caller collects the error payload from the stream and returns it as an RpcServiceError::Rpc extensions/muxio-rpc-service-caller/src/caller_interface.rs:152-164
• Decoding Errors : Failures during the deserialization of the response are returned as RpcServiceError::Transport wrapping an io::Error extensions/muxio-rpc-service-caller/src/prebuffered/traits.rs90

Entity Mapping: Error Propagation

Sources: extensions/muxio-rpc-service-caller/src/transport_state.rs:1-7 extensions/muxio-rpc-service-caller/src/caller_interface.rs:44-53 extensions/muxio-rpc-service-caller/src/caller_interface.rs:118-170 extensions/muxio-rpc-service-caller/src/prebuffered/traits.rs90