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

The source code for this project is available on GitHub.

Prebuffered RPC Calls

Loading…

Prebuffered RPC Calls

Relevant source files

Purpose and Scope

This document describes the prebuffered RPC call pattern in muxio, where the entire request payload is encoded and buffered before transmission, and the entire response payload is accumulated before being decoded and returned to the caller. This is in contrast to streaming RPC calls, which process data incrementally using channels (see Streaming RPC Calls).

Prebuffered calls are the simplest and most common RPC pattern, suitable for request/response operations where the entire input and output fit comfortably in memory. For service definition details, see Service Definitions. For caller interface abstractions, see Service Caller Interface.

Sources: extensions/muxio-rpc-service-caller/src/prebuffered/traits.rs:10-21

Overview

A prebuffered RPC call is a synchronous-style remote procedure invocation where:

The caller encodes the entire request payload using bitcode serialization
The request is transmitted as a complete unit to the server
The server processes the request and generates a complete response
The response is transmitted back as a complete unit
The caller decodes the response and returns the result

The key characteristic is that both request and response are treated as atomic, indivisible units from the application’s perspective, even though the underlying transport may chunk them into multiple frames for transmission.

Sources: extensions/muxio-rpc-service-caller/src/prebuffered/traits.rs:30-48

The RpcCallPrebuffered Trait

The RpcCallPrebuffered trait defines the interface for making prebuffered RPC calls. It is automatically implemented for any type that implements RpcMethodPrebuffered from the muxio-rpc-service crate.

Trait Definition

The trait is generic over any client type C that implements RpcServiceCallerInterface, making it runtime-agnostic and usable with both native Tokio clients and WASM clients.

Automatic Implementation

The blanket implementation at extensions/muxio-rpc-service-caller/src/prebuffered/traits.rs:24-98 automatically provides the call method for any service that defines request/response types via the RpcMethodPrebuffered trait.

Sources: extensions/muxio-rpc-service-caller/src/prebuffered/traits.rs:10-28

Request/Response Flow

The following diagram illustrates the complete flow of a prebuffered RPC call from the caller’s perspective:

sequenceDiagram
    participant App as "Application Code"
    participant Trait as "RpcCallPrebuffered::call"
    participant Encode as "encode_request"
    participant Strategy as "Transport Strategy"
    participant Client as "RpcServiceCallerInterface"
    participant Buffered as "call_rpc_buffered"
    participant Decode as "decode_response"
    
    App->>Trait: Echo::call(client, input)
    Trait->>Encode: Self::encode_request(input)
    Encode-->>Trait: Vec<u8>
    
    Trait->>Strategy: Check encoded_args.len()
    
    alt "len < DEFAULT_SERVICE_MAX_CHUNK_SIZE"
        Strategy->>Strategy: Use rpc_param_bytes
        note over Strategy: Small payload: inline in header
    else "len >= DEFAULT_SERVICE_MAX_CHUNK_SIZE"
        Strategy->>Strategy: Use rpc_prebuffered_payload_bytes
        note over Strategy: Large payload: stream as chunks
    end
    
    Strategy->>Trait: RpcRequest struct
    Trait->>Client: call_rpc_buffered(request, decode_fn)
    
    Client->>Client: Transmit request frames
    Client->>Client: Await response frames
    Client->>Client: Accumulate response bytes
    
    Client-->>Trait: (encoder, Result<Vec<u8>, Error>)
    
    alt "Response is Ok(bytes)"
        Trait->>Decode: decode_response(bytes)
        Decode-->>Trait: Self::Output
        Trait-->>App: Ok(output)
    else "Response is Err"
        Trait-->>App: Err(RpcServiceError)
    end