Expand description
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 value | Status name | Description |
|---|---|---|
0x1 | DATA | From clients, indicates an RPC request. From servers, indicates one of many values emitted by an RPC call. |
0x2 | END | Indicates the successful completion of an RPC call. Only sent by servers. |
0x3 | ERROR | Indicates 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:
| Field | Type | Purpose |
|---|---|---|
m | object | describes the RPC method being invoked |
m.name | string | name of the RPC method being invoked |
m.uts | number (optional) | timestamp of message creation, in microseconds since the Unix epoch |
d | object or array | varies 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.