This project is no longer maintained

The gRPC ecosystem has advanced since we've written this project, and we've moved to using gRPC instead.

Loqui

Loqui is a transport that implements a very simple framing protocol over a raw socket. The framing protocol is similar to http2, except that we've chosen deliberately to not implement a bunch of stuff, like flow control. Instead, the RPC implements very simple request and response semantics. For our purposes, requests and responses are both adequately small so we can just send the entire payload in one frame, instead of having streams (like http2 does).

The RPC protocol does not care how you encode your data - treating all data passed through it as opaque binaries. However, the protocol does support encoding negotiation, and compression where the client sends the server a list of encodings it can speak and compression algos it can use, and the server picks the encoding and compression it wants to use. Compression can be toggled on a per frame basis with frame flags.

The protocol

The protocol is 9 opcodes, with a binary frame format.

Each frame starts with the opcode as an unsigned 8 bit integer (uint8). The opcodes are:

Following the opcode is the frame header - and then if applicable - the payload. All integers are encoded in Big Endian format.

Hello

The hello opcode is sent by the client to the server upon connecting. It advertises the client's Loqui version and a payload containing a a list of connection settings. Settings are in order and split by |and a specific setting can have a list of values split by ,. In our current version the 2 settings are supported encodings and supported compressions.

HelloAck

The helloAck opcode is sent by the server upon receiving hello from the client. It contains the interval in which the server will ping (and that it expects the client to ping the server) - and the supported encodings within the payload data, contains the encoding and compression separated by |.

Ping/Pong

Ping and pong are sent back between the client and server. Either end can initiate a ping - and both ends are expected to reply to a ping with a pong, with the seq that the remote end pinged with.

Request/Response

The client can send requests to the server. The server is expected to reply with a RESPONSE payload with the sequence set to request sequence.

Push

The client and server can send pushes to their remote connection. These are good for one off messages to the service that do not need to be acknowledged.

Go Away

The server is getting ready to shut down the connection. It sends this opcode to tell the client end to finish sending requests and to disconnect. The payload data can be empty, or a string with an error message. Or whatever else you want it to be.

Error

The server had an internal error processing a given request for a specific seq.