progrium / duplex

Full duplex modern RPC

Duplex RPC

Modern full-duplex RPC

• Serialization and transport agnostic
• Client and server combined into Peer object
• Calls and callbacks in either direction
• Optional streaming of results and arguments
• Extensible with middleware (soon)
• Easy to implement protocol and API
• Ready-to-go implementations
  • Go
  • Python 3
  • JavaScript (Node.js and browser)
  • TODO: Ruby?

Getting Started

• with Python
• with Go
• with JavaScript

Tour

Language and serialization agnostic

Duplex is an RPC protocol designed for dynamic (and some statically-typed) languages that focuses on advanced RPC semantics and not object or frame serialization. This lets you pick how to marshal objects, whether with JSON, msgpack, protobuf, BERT, BSON, or anything custom.

// rpc setup using json

// rpc setup using gob

API combines client and server into "peer"

While that alone is somehow already revolutionary for RPC protocols, it also combines client and server into a peer object, letting either side of the connection call or provide invocable service methods. This means you never have to worry about only having a client or only having a server library in your language. It also allows for flexible connection topologies (server calling client functions), callbacks, and plugin architectures.

# server with methods connects to client

// method gets a callback and calls back to the client

Bi-directional object streaming

Methods can also stream multiple results and accept multiple streaming arguments, letting you use Duplex for bi-directional object streaming. Among other patterns, this lets you implement real-time data synchronization, connection tunneling, and interactive consoles, all with the same mechanism as simple remote method calls.

// calls an interactive method, attaches to terminal

# call to subscribe to updates

Simple, extensible API and protocol

Duplex has a simple protocol spec not much more complex than JSON-RPC. It also has an API guide that can be used for easy and consistent implementations in various languages.

The protocol and API are also designed to eventually be extensible. Expect a middleware mechanism that lets you add tracing, authentication, policy, transactions, and more. This allows Duplex to remain simple but powerful.

Transport agnostic, frame interface

The API design has a simple framed transport interface. This means out of the box you can expect to use any transport that takes care of framing, for example WebSockets, UDP, ZeroMQ, AMQP. Wrapping streaming transports such as raw TCP or STDIO with length-prefix or newline framing lets you use them as well. By focusing on frames and making the API transport agnostic, as well as being serialization agnostic, implementations are very simple with no major dependencies.

TODO

• document spec / api
• demo
  • cross language, browser
  • topologies: client-server, server-client, gateway
  • transports: websocket, tcp, UDP
  • codecs: json, msgpack, protobuf
  • streaming: state sync, terminal
  • callbacks: async reply, events, plugins
  • gateway: behind firewall, client to client (browser)
  • patterns: identity, reflection (cli), self docs
  • implementation: code tour, api guide, protocol spec

duplex's Issues

Server doesn't reply any peer created after old peers have been closed.

Here are some logs. You can reproduce the same problem by running the tests I created in the referenced PR.

You should be able to see that the last client sends a frame but the server doesn't read the frame.

2014/11/01 20:34:20 6 Sending frame [ 0 ]: &{false 0xc2080059e0 0xc208005920  0 0 Arith.Add map[]  false []}
2014/11/01 20:34:20 6 Pumping started for channel 0
2014/11/01 20:34:20 6 Sending frame: &{false 0xc208005aa0 0xc208005920  1 0  map[]  true [130 161 65 7 161 66 8]}
2014/11/01 20:34:20 Reading frame: {false <nil> <nil>  0 0 Arith.Add map[]  false []}
2014/11/01 20:34:20 4 Pumping started for channel 0
2014/11/01 20:34:20 Reading frame: {false <nil> <nil>  1 0  map[]  true [130 161 65 7 161 66 8]}
2014/11/01 20:34:20 4 Sending frame: &{false 0xc208005d40 0xc208005bc0  1 0  map[]  true [129 161 67 15]}
2014/11/01 20:34:20 4 Pumping finished for channel 0
2014/11/01 20:34:20 EOF
2014/11/01 20:34:20 Reading frame: {false <nil> <nil>  1 0  map[]  true [129 161 67 15]}
2014/11/01 20:34:20 6 Pumping finished for channel 0
2014/11/01 20:34:20 read tcp 127.0.0.1:9876: use of closed network connection
2014/11/01 20:34:20 7 Connecting 127.0.0.1:9876
2014/11/01 20:34:20 EOF
2014/11/01 20:34:20 sending greeting to  127.0.0.1:9876 :  f724082e-b216-4aa3-bf68-46913ae5c91c
2014/11/01 20:34:20 received greeting from  127.0.0.1:57515 :  f724082e-b216-4aa3-bf68-46913ae5c91c
2014/11/01 20:34:20 sending greeting to  127.0.0.1:57515 :  3246bc2c-f770-4ad4-8a5a-cfe611a6db82
2014/11/01 20:34:20 received greeting from  127.0.0.1:9876 :  3246bc2c-f770-4ad4-8a5a-cfe611a6db82
2014/11/01 20:34:20 7 Connected
2014/11/01 20:34:20 7 First connection, routing...
2014/11/01 20:34:20 7 Sending frame [ 0 ]: &{false 0xc208005f80 0xc208005ec0  0 0 Arith.Add map[]  false []}
2014/11/01 20:34:20 7 Pumping started for channel 0
2014/11/01 20:34:20 7 Sending frame: &{false 0xc2080aa060 0xc208005ec0  1 0  map[]  true [130 161 65 7 161 66 8]}

Completion of error handling

I have looked at a few source files for your current software. I have noticed that some checks for return codes are missing.

Would you like to add more error handling for return values from functions like the following?

• pthread_create ⇒ dpx_init
• malloc ⇒ _dpx_peer_new

javascript: Should be != true

https://github.com/progrium/duplex/blob/master/javascript/src/duplex.coffee#L176
https://github.com/progrium/duplex/blob/master/javascript/src/duplex.coffee#L195

Named Peers

In order to implement various plugin patterns using Duplex, you need to be able to make calls (open channels) with specific peers, not just round robin. The solution is again borrowing from ZMQ to give peers a unique name that is shared with remote peers. Then a generalized version of Peer.Open called Peer.OpenWith would take a name of a remote peer. New methods on Peer would include:

peer.Name() # returns the uuid name of this peer, generated on construction
peer.Remote() # returns a list of uuids of remote peers
peer.OpenWith(...) # same as Open, but first argument is a remote peer name

Implementation notes:

• A UUID is generated when a Peer is instantiated.
• The unused connection greeting methods will be modified to take a Peer object, and a greeting will be introduced: simply the UUID string of the peer. This must be symmetrical. If a UUID string is not received, the connection is closed.
• OpenFrame will need a way to include its intended peer, so routeOpenFrames can skip round robin if a target peer is already known.
• Named peers now allows peers to de-dupe multiple connections with the same peer. If a connection is established with a remote peer that is already connected with / known, it will just use the new connection in place of the old one.
• Otherwise, everything else should work the same

Using named peers:

• Higher level client API will also have an OpenWith method. The common convenience method Call will have a CallTo companion.
• Applications will not know when a new peer is connected, but can at any time see connected peers. If an event is needed or extra information about a peer, a high level pattern would be to expose a Register method, allowing the other side to call Register after connecting, passing its peer.Name() and any other information necessary for the intended application.

Deferred / skipping:

• This introduces the possibility to explicitly disconnect with remote peers. Perhaps a Drop(name) method can be introduced, but not yet. This can be useful when doing peer specific "Ping" liveness requests, which would be application level, and result in a call to Drop when they fail for a particular peer.
• ZMQ allows custom names. This is rarely used, but if necessary, it can be done at the application level using a Register method. The application can then map a custom name to a peer UUID. So I don't think the API will need to support custom names.

Building On OSX

Is building this on OSX supported at all? I keep getting the following error.

error: typedef redefinition with different types ('struct uuid_st' vs
      '__darwin_uuid_t' (aka 'unsigned char [16]'))
typedef struct uuid_st uuid_t;

Golang Demo: panic: close of closed channel

Running peer.call("doMsgbox", "Client called doMsgbox() on server, server called msgbox() on client.") works fine but peer.call("echo", {foo: "bar"}) causes go server to crash.

$ cd demo && go run demo.go
WS on 8001...
HTTP on 8000...
panic: close of closed channel

goroutine 9 [running]:
panic(0x2c3be0, 0xc860208070)
    /usr/local/go/src/runtime/panic.go:481 +0x3e6
github.com/progrium/duplex/golang.(*Channel).Send(0xc8200f0060, 0x2c2e60, 0xc8201a40f0, 0x0, 0x0, 0x0)
    /Users/matt/src/github.com/progrium/duplex/golang/duplex.go:341 +0x241
main.init.1.func1(0xc8200f0060, 0x0, 0x0)
    /Users/matt/src/github.com/progrium/duplex/golang/demo/demo.go:20 +0xba
created by github.com/progrium/duplex/golang.(*Peer).route
    /Users/matt/src/github.com/progrium/duplex/golang/duplex.go:222 +0x67e
exit status 2
make: *** [demo] Error 1

javascript: Peer.call error if args == function

https://github.com/progrium/duplex/blob/master/javascript/src/duplex.coffee#L150

python: better locking in sync.py

Because of the threads used in sync.py, a lot of the dicts used will not proper locks.

Node.js binding

Your lib look awesome, waiting for a binding!

Make include guards unique

I find that include guards like "DPX_H" and "TASK_H" are too short for the safe reuse of your header files.

reserved identifier violation

I would like to point out that identifiers like "_DPX_H_" and "_TASK_H_" do not fit to the expected naming convention of the C language standard.
Would you like to adjust your selection for unique names?

how to use?

im really interested in this library.
is there any plans on elaborating further or do further development on this projecT?
and wondering if this is suitable for multiplex connection for realtime MMO backend?
thx

Documentation

What about to write some words about
1. Bidirectional capability
2. Reconnect behavior (f.e. server restart)

callback_func should unregister

Implementations currently leave a callback function registered, but to cleanup in the case of unbounded callbacks, they should be wrapped to unregister themselves when completed.

no way to close channels without closing connection

Silly thing to forget as it's been a major part of previous streaming RPC. Channel implementations currently have no close() method or just call peer.close() which closes the whole connection. This means we'll have to introduce a ctl control type message, but that was inevitable. Later it could be used for back pressure etc.