Wire Protocol

This document specifies the makeup of a dripline message and how it is expressed as an AMQP message.

Foundation

Dripline messages are built on the AMQP 0.9.1 messaging protocol as implemented in RabbitMQ

Structure

A dripline message comprises header information that describes the message and the payload that is the message contents.

Header

A subset of the header fields are specified as AMQP message properties.

Field	Type	Message Type	Values
content-encoding	string	All	application/json
correlation-id	string	All	UUID for request/reply correlation
reply-to	string	Requests	Routing key for replies
message-id	string	All	UUID or UUID/[chunk number]/[total chunks]

The remaining fields are specified as headers in the AMQP message properties.

Field	Type	Message Type	Values
message_type	integer	All	Reply (2), Request (3), Alert (4)
message_operation	integer	Requests	Set (0), Get (1), Command (9)
specifier	string		Provides additional information about how the consumer should process the message
timestamp	string	All	Following the RFC3339 format (example: 2017-12-31T15:00:00.000Z) with sub-second precision
lockout_key	string	Requests	16 hexidecimal digits (see Lockout)
sender_info.exe	string	All	Full path of the executable used to send the message
sender_info.hostname	string	All	Name of the host computer that sends the message
sender_info.username	string	All	User responsible for sending the message
sender_info.service_name	string	All	Name of the service that sent the message
sender_info.versions	[below]	All	Package version information for the components of the sender
return_code	integer	Replies	Machine-interpretable status; see Return Codes
return_message	string	Replies	Human-readable explanation of the return code

The sender_info.versions field consists of the package version information for the components of the sending software. It is a dictionary of dictionaries. For each package it contains the following pieces of information:

Field	Type	Values
version	string	Software version for this component of the sender
package	string	Software package name for this component of the sender
commit	string	Git commit for this component of the sender

Payload

The payload is the content of the message, and it comprises the AMQP message body. It is optional in all types of dripline messages.

The payload should be formatted in JSON. The encoding (application/json) should be specified in the content_encoding field of the AMQP message.

Split Messages

A dripline message can be split across multiple AMQP messages to accommodate large payloads. The AMQP messages that comprise a single dripline message are called “chunks.” The headers for all chunks comprising a single dripline message are identical, with the exception of message-id. The payload, encoded as a JSON string, is split into substrings based on a maximum size, and each substring is assigned as the payload for a single chunk in order of position in the original string.

The message-id header field is used to properly reconstruct the full message. The structure of the message-id for a split message is UUID/[chunk number]/[total chunks]. The UUID is a single unique identifier for the dripline message, and is duplicated in each chunk. The chunk number describes the position of the chunk in the full message. The total chunks` is the number of chunks into which the message was divided.

For unsplit messages the message-id field may either be UUID or UUID/0/1.

Message Types

There are three types of dripline messages:

Request

messages sent from one node to another in a dripline mesh to perform a specific action.

Reply

messages sent in reply to a request.

Alert

messages broadcast from a node without regard to whether other nodes are listening.

Message Operations

Request messages have three possible operations:

Set

set a value

Get

get a value

Command

perform a command

The exact meaning of an operation will depend on the application. Generally get and set will get and set a value, respectively, and a command will request some application-specific command.

Return Codes

The following table lists return codes. It is worth stressing that all codes fall into one of the following categories:

• <0: not defined

• 0: success

• 1-99: warnings (request fulfilled but with some caveat)

• 100-999: dripline error

• >=1000: application errors

Errors are subdivided into categories, with each multiple of 100 representing a category and values falling within that category. Dripline errors are covered by codes in the 100-999 range. Additional errors may be specified for a particular application of dripline. These errors are covered by codes 1000 and above.

Code	Description
0	Success
1	Generic Warning; No Action Taken
2	Deprecated Feature Warning
3	Dry Run Warning
4	Offline Warning
5	Sub-Service Warning
6-99	Unassigned, Non-Error Warnings
100	Generic AMQP Related Error
101	AMQP Connection Error
102	Invalid AMQP Routing Key
103-199	Unallocated AMQP Errors
200	Generic Resource Error
201	Resource Connection Error
202	No Response
203	Sub-Service Error
204-299	Unallocated Resource Errors
300	Generic Service Error
301	Invalid Message Encoding
302	Decoding Failed
303	Invalid Payload
304	Invalid Value
305	Timeout
306	Invalid Command
307	Access Denied
308	Invalid Lockout Key
309	[removed]
310	Invalid Specifier
310-399	Unallocated Service errors
400	Generic Client Error
401	Invalid Request
402	Error Handling Reply
403	Unable to Send
404	Client Timeout
405-499	Unallocated Client Error
500-998	Unallocated
999	Unhandled dripline or application error
1000+	Application-specified errors

AMQP Message Properties

This section lists how the different properties of an AMQP message are used in the dripline wire protocol. It duplicates the information above, but referenced in a different way.

AMQP Field	Type	Dripline Use
content-type	string	Unused
content-encoding	string	application/json
headers	table	Other header fields
delivery-mode	string	Unused
priority	uint8	Unused
correlation-id	string	UUID for message correlation
reply-to	string	Routing key for reply
expiration	string	Unused
message-id	string	Message UUID or UUID/[chunk number]/[total chunks]
timestamp	uint64	Unused (string timestamp field in headers)
type	string	Unused
user-id	string	Unused
app-id	string	Unused
cluster-id	string	Unused
Body	string	Payload