Crate essrpc

Electron’s Super Simple RPC (ESSRPC) is a lightweight RPC library which aims to enable RPC calls as transparently as possible through calls to ordinary trait methods.

The magic is performed by the essrpc attribute macro which may be applied to any trait whose functions each meet the following conditions:

• Returns a Result whose error type implements From<RPCError>.
• Uses only parameter and returns types which implement Serialize
• Is not unsafe

The essrpc macro generates for a trait an RPC client and a server. For a trait named Foo, the macro will generate FooRPCClient which implements both RPCClient and Foo as well as FooRPCServer which implements RPCServer.

Examples

A trait can apply the essrpc attribute like this.

#[essrpc]
pub trait Foo {
   fn bar(&self, a: String, b: i32) -> Result<String, SomeError>;
}

For example purposes, assume we’re using a unix socket to communicate between a parent and child process. Anything else implementing Read+Write would work just as well.

let (s1, s2) = UnixStream::pair().unwrap();

We can spin up a server like this

let mut s = FooRPCServer::new(FooImpl::new(), BincodeTransport::new(s2));
s.serve()

Then, if we have some type FooImpl which implements Foo, we can do RPC like this.

let client = FooRPCClient::new(BincodeTransport::new(s1));
match client.bar("the answer".to_string(), 42) {
    Ok(result) => assert_eq!("the answer is 42", result),
    Err(e) => panic!("error: {:?}", e)
}

Asynchronous Clients

By default, the #[essrpc] attribute generates a synchronous client. Asynchronous clients can be generated via #[essrpc(async)], or #[essrpc(sync, async)] if both synchronous and asynchronous clients are needed. For asynchronous, the macro generates a new trait, suffixed with Async for which every method returns a boxed Future instead of a Result, with the same success and error types, and a type implementing AsyncRPCClient. For example,

#[essrpc(async)]
pub trait Foo {
   fn bar(&self, a: String, b: i32) -> Result<String, SomeError>;
}

Would generate a FooAsync trait with a bar method returning Box<Future<Item=String, Error=SomeError>> and a FooAsyncRPCClient struct implementing both FooAsync and AsyncRPCClient.

Modules

internal

transports

Transport implementations and helpers.

Structs

GenericSerializableError

Generic serializable error with a description and optional cause. Used in conjunction with RPCError.

MethodId

Identifies a method by both a name and an index. The Indices are automatically generated in the order methods are listed on the trait. Used when implementing ClientTransport

RPCError

RPC error. All functions in RPC traits must return an error type which implements From<RPCError>.

Enums

PartialMethodId

Identifies a method by either a name or an index. Used when implementing ServerTransport.

RPCErrorKind

Types of RPCError

Traits

AsyncClientTransport

Trait for RPC transport (client) to be used with asynchronous clients

AsyncRPCClient

Trait implemented by all RPC clients generated by the essrpc macro when the async parameter is used. For a trait named Foo, the macro will generate FooAsyncRPCClient which implements both AsyncRPCClient and FooAsync.

ClientTransport

Trait for RPC transport (client). ESSRPC attempts to make as few assumptions about the transport as possible. A transport may work across a network, via any IPC mechanism, or purely in memory within a single process. Often, you will implement both ClientTransport and ServerTransport on the same type, but it is permitted for the implementations to be on separate types. Obviously, they must be compatible.

RPCClient

Trait implemented by all RPC clients generated by the essrpc macro. For a trait named Foo, the macro will generate FooRPCClient which implements both RPCClient and Foo.

RPCServer

Trait implemented by all RPC servers generated by the essrpc macro. For a trait named Foo, the macro will generate FooRPCServer which implements RPCServer. An RPCServer generated for a trait ‘Foo’ will have a new method

ServerTransport

Trait for RPC transport (server). ESSRPC attempts to make as few assumptions about the transport as possible. A transport may work across a network, via any IPC mechanism, or purely in memory within a single process.

Type Definitions

BoxFuture

Type returned by async transport methods. A pinned dynamic-dispatch future.

Attribute Macros

essrpc

The main macro which does the magic. When applied to a trait Foo generates a FooRPCClient type implementing RPCClient (and Foo). as well as FooRPCServer implementing RPCServer.