Crate grafos_rpc 

grafos-rpc – Lease-backed RPC framework for grafOS.

The hot path is a leased shared memory write + read instead of a network round trip. Client writes a request to a leased memory region; server reads from the same region and writes back a response. The underlying transport is FBMU (Fabric Bootstrap Memory Unit), so co-located services exchange calls without touching the network stack.

Quick start

use grafos_rpc::{RpcHandler, RpcClient, RpcServer};
use grafos_std::error::{FabricError, Result};

// 1. Define your service handler.
struct Adder;
impl RpcHandler for Adder {
    fn handle(&self, method_id: u32, payload: &[u8]) -> Result<Vec<u8>> {
        let args: (f64, f64) = postcard::from_bytes(payload)
            .map_err(|_| FabricError::IoError(-200))?;
        postcard::to_allocvec(&(args.0 + args.1))
            .map_err(|_| FabricError::IoError(-201))
    }
}

// 2. Acquire a lease (mock backend for native testing).
grafos_std::host::reset_mock();
grafos_std::host::mock_set_fbmu_arena_size(65536);
let lease = grafos_std::mem::MemBuilder::new().min_bytes(65536).acquire()?;

// 3. Create client and server on the same lease.
let mut client = RpcClient::new(&lease);
let server = RpcServer::new(&lease);

Architecture

The shared memory arena is divided into two regions at fixed offsets:

• Request region (offset 0): Written by the client, read by the server.
• Response region (offset 32768): Written by the server, read by the client.

Each region has a status byte that drives the protocol state machine:

Value	Constant	Meaning
0	EMPTY	Slot is idle
1	REQUEST_READY	Client has written a request
2	PROCESSING	Server is handling the request
3	RESPONSE_READY	Server has written the response
4	ERROR	Server encountered an error

Wire layout

Request region (written at offset 0):

[request_id: u64 LE (8B)] [method_id: u32 LE (4B)] [status: u8 (1B)]
[payload_len: u32 LE (4B)] [payload: [u8; payload_len]]

Response region (written at offset 32768):

[request_id: u64 LE (8B)] [status: u8 (1B)]
[payload_len: u32 LE (4B)] [payload: [u8; payload_len]]

All integers are little-endian. Payloads are serialized with postcard (compact, no_std-friendly). Maximum payload size is 30 KiB.

Re-exports

pub use mux::RpcMuxClient;

pub use mux::RpcMuxServer;

pub use transport::AutoTransport;

pub use transport::QuicTransport;

pub use transport::RpcTransport;

pub use transport::ServiceHandlerAdapter;

pub use transport::SharedMemoryTransport;

Modules

mux

Multi-slot / multi-client concurrency for lease-backed RPC.

transport

Transport abstraction for grafos-rpc.

Structs

RpcClient

Client side of the shared-memory RPC protocol.

RpcServer

Server side of the shared-memory RPC protocol.

Constants

EMPTY

Slot is idle — no pending request or response.

ERROR

Server encountered an error processing the request.

PROCESSING

Server is currently processing the request.

REQUEST_READY

Client has written a request; server should process it.

RESPONSE_READY

Server has written the response; client can read it.

Traits

RpcHandler

Trait for handling RPC method dispatches on the server side.

Attribute Macros

grafos_rpc_service

Attribute macro that generates RPC client and server from a service trait.