Crate prost_simple_rpc

A simple RPC library to be used together with prost for defining type-safe RPC services.

This library lets you generate traits for implementing a generic RPC mechanism using Protobuf as the schema language. You have to supply your own underlying transport mechanism, for example WebSockets, UNIX pipes, HTTP, etc.

You probably want to use this library together with prost-simple-rpc-build to generate the code for all of the traits defined in this crate.

Usage

Start by defining a schema for your service in e.g. src/schema/echo/service.proto:

syntax = "proto3";

package echo;

// The Echo service. This service returns back the same data that it is given.
service Echo {
    // Echoes back the data sent, unmodified.
    rpc Echo (EchoRequest) returns (EchoResponse);
}

// The request for an `Echo.Echo` call.
message EchoRequest {
    // The data to be echoed back.
    bytes data = 1;
}

// The response for an `Echo.Echo` call.
message EchoResponse {
    // The echoed back data from `EchoRequest.data`.
    bytes data = 1;
}

Use prost, prost-build and prost-simple-rpc-build to generate Rust code for this service, by putting this in your build.rs:

extern crate prost_build;
extern crate prost_simple_rpc_build;

fn main() {
    prost_build::Config::new()
        .service_generator(Box::new(prost_simple_rpc_build::ServiceGenerator::new()))
        .compile_protos(
            &["src/schema/echo/service.proto"],
            &["src/schema"],
        )
        .unwrap();
}

Then, include the generated code in your Rust build, for example in main.rs. There are a bunch of extra crate dependencies for the generated code:

extern crate bytes;
extern crate failure;
extern crate futures;
extern crate prost;
#[macro_use]
extern crate prost_derive;
extern crate prost_simple_rpc;
extern crate tokio;

mod schema {
    pub mod echo {
        include!(concat!(env!("OUT_DIR"), "/echo.rs"));
    }
}

fn main() {
    // ...
}

Client

Let's say you want to create a client for your service. You need to implement a Handler that handles the transport for your client calls. Let's imagine you have some form of WebSockets transport:

struct WebSocketTransport { /* ... */ }

impl prost_simple_rpc::handler::Handler for WebSocketTransport {
    // From our imaginary websocket library:
    type Error = websocket::Error;
    // This type is generated by prost-simple-rpc:
    type Descriptor = schema::echo::EchoDescriptor;
    // From our imaginary websocket library:
    type CallFuture = websocket::Future;

    /// Perform a raw call to the specified service and method.
    fn call(
        &mut self,
        method: <Self::Descriptor as descriptor::ServiceDescriptor>::Method,
        input: bytes::Bytes,
    ) -> Self::CallFuture {
        // You can use information from the descriptors to include in the request:
        self.websocket.call(Self::Descriptor::name(), method.name(), input)
    }
}

You can now use this handler with the client generated by prost-simple-rpc:

fn main() {
    let websocket = WebSocketTransport::connect("...");
    let client = schema::echo::EchoClient::new(websocket);
    let future = client.echo(schema::echo::EchoRequest { /* ... */ });
    // ... use the future to wait for a response.
}

Server

To create a server for your service, start by implementing the generated service trait for the service:

struct EchoService;

#[derive(Debug, Eq, Fail, PartialEq)]
#[fail(display = "Error!")]
struct Error;

impl schema::echo::Echo for EchoService {
    // You can supply an error type here if your service can fail.
    type Error = Error;
    // The future type used in the `echo()` method; you can of course use Box<Future<...>> here
    // but this library assumes unboxed futures by default.
    type EchoFuture = futures::future::FutureResult<schema::echo::EchoResponse, Self::Error>;

    fn echo(&self, input: schema::echo::EchoRequest) -> Self::EchoFuture {
        futures::future::ok(schema::echo::EchoResponse { data: input.data })
    }
}

You can now wrap this service with the generated server implementation to get something that can be plugged into your preferred routing system:

fn main() {
    let server = schema::echo::EchoServer::new(EchoService);

    websocket::spawn_server(move |request| {
        // You would probably normally look up the right method descriptor via some kind of routing
        // information; here's a hard-coded example:
        let method = schema::echo::EchoMethodDescriptor::Echo;

        server.call(method, request.data);
    });
}

Modules

descriptor	Traits for defining generic service descriptor definitions.
error	Error type definitions for errors that can occur during RPC interactions.
handler	Traits for defining generic RPC handlers.