[−][src]Crate fast_rpc

Fast: A simple RPC protcol used by Joyent products

Fast is a simple RPC protocol used in Joyent'sTriton and Manta systems, particularly in the Moray and Boray components.

Protocol overview

The Fast protocol is intended for use with TCP. Typically, a Fast server listens for TCP connections on a well-known port, and Fast clients connect to the server to make RPC requests. Clients can make multiple connections to the server, but each connection represents a logically separate client. Communication between client and server consist of discrete messages sent over the TCP connection.

Fast protocol messages have the following structure:

  • VERSION 1-byte integer. The only supported value is "1".

  • TYPE 1-byte integer. The only supported value is TYPE_JSON (0x1), indicating that the data payload is an encoded JSON object.

  • STATUS 1-byte integer. The only supported values are:

    • STATUS_DATA 0x1 indicates a "data" message

    • STATUS_END 0x2 indicates an "end" message

    • STATUS_ERROR 0x3 indicates an "error" message

  • MSGID0...MSGID3 4-byte big-endian unsigned integer, a unique identifier for this message.

  • CRC0...CRC3 4-byte big-endian unsigned integer representing the CRC16 value of the data payload

  • DLEN0...DLEN4 4-byte big-endian unsigned integer representing the number of bytes of data payload that follow

  • DATA0...DATAN Data payload. This is a JSON-encoded object (for TYPE = TYPE_JSON). The encoding length in bytes is given by the DLEN0...DLEN4 bytes.

Status

There are three allowed values for status:

Status valueStatus nameDescription
0x1DATAFrom clients, indicates an RPC request. From servers, indicates one of many values emitted by an RPC call.
0x2ENDIndicates the successful completion of an RPC call. Only sent by servers.
0x3ERRORIndicates the failed completion of an RPC call. Only sent by servers.

Message IDs

Each Fast message has a message id, which is scoped to the Fast connection. These are allocated sequentially from a circular 31-bit space.

Data payload

For all messages, the data field contains properties:

FieldTypePurpose
mobjectdescribes the RPC method being invoked
m.namestringname of the RPC method being invoked
m.utsnumber (optional)timestamp of message creation, in microseconds since the Unix epoch
dobject or arrayvaries by message status

Messaging Scenarios

Essentially, there are only four messaging scenarios with Fast:

Client initiates an RPC request. The client allocates a new message identifier and sends a DATA message with data.m.name set to the name of the RPC method it wants to invoke. Arguments are specified by the array data.d. Clients may issue concurrent requests over a single TCP connection, provided they do not re-use a message identifier for separate requests.

Server sends data from an RPC call. RPC calls may emit an arbitrary number of values back to the client. To emit these values, the server sends DATA messages with data.d set to an array of non-null values to be emitted. All DATA messages for the same RPC request have the same message identifier that the client included in its original DATA message that initiated the RPC call.

Server completes an RPC call successfully. When an RPC call completes successfully, the server sends an END event having the same message identifier as the one in the client's original DATA message that initiated the RPC call. This message can contain data as well, in which case it should be processed the same way as for a DATA message.

Server reports a failed RPC call. Any time before an END message is generated for an RPC call, the server may send an ERROR message having the same message identifier as the one in the client's original DATA message that initiated the RPC call.

By convention, the m fields (m.name and m.uts) are populated for all server messages, even though m.name is redundant.

The RPC request begins when the client sends the initial DATA message. The RPC request is finished when the server sends either an ERROR or END message for that request. In summary, the client only ever sends one message for each request. The server may send any number of DATA messages and exactly one END or ERROR message.

Modules

client

This module provides the interface for creating Fast clients.

protocol

This module contains the types and functions used to encode and decode Fast messages. The contents of this module are not needed for normal client or server consumers of this crate, but they are exposed for the special case of someone needing to implement custom client or server code.

server

This module provides the interface for creating Fast servers.