Crate quic_rpc

A streaming rpc system for transports that support multiple bidirectional streams, such as QUIC and HTTP2.

A lightweight memory transport is provided for cases where you want have multiple cleanly separated substreams in the same process.

For supported transports, see the transport module.

Motivation

See the README

Example

use derive_more::{From, TryInto};
use quic_rpc::{message::RpcMsg, RpcClient, RpcServer, Service};
use serde::{Deserialize, Serialize};

// Define your messages
#[derive(Debug, Serialize, Deserialize)]
struct Ping;

#[derive(Debug, Serialize, Deserialize)]
struct Pong;

// Define your RPC service and its request/response types
#[derive(Debug, Clone)]
struct PingService;

#[derive(Debug, Serialize, Deserialize, From, TryInto)]
enum PingRequest {
    Ping(Ping),
}

#[derive(Debug, Serialize, Deserialize, From, TryInto)]
enum PingResponse {
    Pong(Pong),
}

impl Service for PingService {
    type Req = PingRequest;
    type Res = PingResponse;
}

// Define interaction patterns for each request type
impl RpcMsg<PingService> for Ping {
    type Response = Pong;
}

// create a transport channel, here a memory channel for testing
let (server, client) = quic_rpc::transport::flume::channel(1);

// client side
// create the rpc client given the channel and the service type
let mut client = RpcClient::<PingService, _>::new(client);

// call the service
let res = client.rpc(Ping).await?;

// server side
// create the rpc server given the channel and the service type
let mut server = RpcServer::<PingService, _>::new(server);

let handler = Handler;
loop {
    // accept connections
    let (msg, chan) = server.accept().await?.read_first().await?;
    // dispatch the message to the appropriate handler
    match msg {
        PingRequest::Ping(ping) => chan.rpc(ping, handler, Handler::ping).await?,
    }
}

// the handler. For a more complex example, this would contain any state
// needed to handle the request.
#[derive(Debug, Clone, Copy)]
struct Handler;

impl Handler {
    // the handle fn for a Ping request.

    // The return type is the response type for the service.
    // Note that this must take self by value, not by reference.
    async fn ping(self, _req: Ping) -> Pong {
        Pong
    }
}

Features

• hyper-transport — HTTP transport using the hyper crate
• quinn-transport — QUIC transport using the iroh-quinn crate
• flume-transport (enabled by default) — In memory transport using the flume crate
• iroh-transport — p2p QUIC transport using the iroh crate
• macros — Macros for creating request handlers
• test-utils — Utilities for testing
• default — Default, includes the memory transport

Re-exports

pub use client::RpcClient;

pub use server::RpcServer;

Modules

client

Client side api

message

Service definition

pattern

Predefined interaction patterns.

server

Server side api

transport

Built in transports for quic-rpc

Macros

declare_bidi_streamingmacros

Declare a message to be a server streaming message for a service.

declare_client_streamingmacros

Declare a message to be a server streaming message for a service.

declare_rpcmacros

Declare a message to be a rpc message for a service.

declare_server_streamingmacros

Declare a message to be a server streaming message for a service.

rpc_servicemacros

Derive a set of RPC types and message implementation from a declaration.

Traits

Connector

A connector to a specific service

Listener

A listener for a specific service

RpcError

Requirements for an internal error

RpcMessage

Requirements for a RPC message

Service

A service

Functions

flume_channelflume-transport

Create a pair of RpcServer and RpcClient for the given Service type using a flume channel

quinn_channeltest-utils

Create a pair of RpcServer and RpcClient for the given Service type using a quinn channel