Core Library: Frame & RPC Layers

Loading…

Core Library: Frame & RPC Layers

Relevant source files

• core/README.md
• core/src/constants.rs
• core/src/frame.rs
• core/src/frame/README.md
• core/src/frame/frame_codec.rs
• core/src/lib.rs
• core/src/rpc.rs

The muxio-core library provides the foundational primitives for bidirectional, multiplexed communication over a byte stream. It is architected into two primary layers: the Frame Layer , which handles binary serialization and stream multiplexing, and the RPC Layer , which manages request-response correlation and stream lifecycles.

Layered Architecture Overview

The core library transforms a raw byte-oriented transport into a structured RPC system through a tiered approach. The frame module handles the physical layout of data on the wire, while the rpc module provides the logical abstractions for multi-channel communication.

graph TD
    subgraph "Frame Layer (core/src/frame/)"
        A["FrameCodec"] -- "decodes" --> B["Frame"]
B -- "contains" --> C["FrameKind"]
D["FrameMuxStreamDecoder"] -- "assembles" --> B
    end

    subgraph "RPC Layer (core/src/rpc/)"
        E["RpcDispatcher"] -- "manages" --> F["RpcRequest/Response"]
F -- "contains" --> G["RpcHeader"]
E -- "routes to" --> H["RpcRespondableSession"]
end

    B -- "Payload" --> F

The following diagram illustrates the relationship between these layers and their corresponding code entities:

System Entity Mapping: Frame to RPC Transition

Sources: core/src/lib.rs:1-2 core/src/frame.rs:1-13 core/src/rpc.rs:1-7

Frame Layer: Binary Framing Protocol

The Frame Layer is the lowest abstraction in muxio. It defines the binary protocol used to encapsulate data. Every message sent over the wire is wrapped in a Frame core/src/frame/frame_struct.rs:8-14 which includes a header specifying the FrameKind (e.g., Open, Data, End, or Cancel) core/src/frame/frame_kind.rs:10-23 and the payload length.

Key responsibilities of this layer include:

• Serialization : The FrameCodec handles the conversion between Frame structs and raw bytes using little-endian encoding core/src/frame/frame_codec.rs:20-48
• Multiplexing : The FrameMuxStreamDecoder allows multiple logical streams to be interleaved over a single physical connection by tracking and reassembling frame sequences core/src/frame/frame_mux_stream_decoder.rs:14-20
• Encoding : The FrameStreamEncoder provides the mechanism to split larger payloads into smaller chunks and write structured frames back into a byte stream core/src/frame/frame_stream_encoder.rs:13-21

For a deep dive into the binary format and framing mechanics, see Frame Layer: Binary Framing Protocol.

Sources: core/src/frame.rs:1-13 core/src/constants.rs:2-7 core/src/frame/README.md:19-30

RPC Layer: Dispatcher, Sessions & Stream Lifecycle

The RPC Layer sits atop the Frame Layer and introduces the concept of stateful communication. While the Frame Layer only knows about “packets,” the RPC Layer understands “requests,” “responses,” and “streams.”

The central logic is managed via the RpcDispatcher core/src/rpc.rs5 which maintains a registry of active sessions. When a response arrives, the dispatcher uses the RPC header information to correlate that response with the original request that initiated the session.

Key features include:

• Message Correlation : Tracking unique RPC IDs to match RpcRequest core/src/rpc/rpc_request_response.rs:10-18 with corresponding RpcResponse core/src/rpc/rpc_request_response.rs:20-27
• Message Types : Differentiation between requests, responses, and stream updates via RpcMessageType (internal to RPC header logic).
• Stream Abstraction : High-level interfaces for reading and writing bytes associated with a specific RPC call via RpcStreamEncoder and RpcStreamDecoder.
• Respondable Sessions : The RpcRespondableSession allows for pre-buffering and catch-all handling of incoming RPC calls.

For details on how requests are correlated and how the stream lifecycle is managed, see RPC Layer: Dispatcher, Sessions& Stream Lifecycle.

Data Flow: From Bytes to RPC Dispatch

Sources: core/src/frame/frame_codec.rs:68-127 core/src/rpc/rpc_dispatcher.rs:1-10 core/src/rpc/rpc_request_response.rs:1-30

Core Utilities and Constants

The core library also provides shared constants and utilities used by both layers:

• Frame Constants : Defines protocol-wide offsets and field sizes for Frame headers, including FRAME_HEADER_SIZE (21 bytes) core/src/constants.rs:2-7
• RPC Constants : Defines offsets for the RPC header within the frame payload, such as RPC_FRAME_METHOD_ID_OFFSET and RPC_FRAME_MSG_TYPE_OFFSET core/src/constants.rs:12-37
• Utils : Contains helper functions for timestamping and atomic ID generation core/src/utils.rs:1-6

Sources: core/src/lib.rs:4-5 core/src/constants.rs:1-38