Wiki
Clone wikignrs / GNRS Wire Protocol
Version 1.0
IMPORTANT NOTE This protocol (and therefore this document) is currently under frequent revision. Please be aware that changes in the code may not immediately be reflected in this document.
The name resolution service supports 3 types of requests from a client: insert, update and, a lookup or query request, where the operations may be thought equivalent to the basic functions on a map data structure storing key/value pairings.
The difference between the insert and update requests is that the former equals a 'set' operation wherein any previous value mapped to the key is replaced by the new network location bindings. In an update operation, the semantics may be further qualified via an options field to either 'replace' or 'merge', for example, the existing with the presented bindings.
Common Objects
Network Address
The Network Address is a network-routable identifier acting as a communication endpoint (source, destination) within GNRS. A network address is represented in GNRS as the triple (Type, Length, Value). GUIDs may be bound to multiple Network Address values that actually identify the same network endpoint in different formats.
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Address Type | Address Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | Value | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Type - 16-bit value identifying the type of network address represented.
- Length - 16-bit unsigned integer value identifying the length of the network address in bytes.
- Value - Variable-length binary value. Contains the raw (binary) form of the network address, dependent on the type and length.
The following Type/Value pairs are currently supported by the prototype:
| Type | Length | Value Format |
|---|---|---|
| 0 | 6 | 4-byte IPv4 address, 2-byte UDP port |
| 1 | 20 | 20-byte GUID value |
Request Messages
Common Header
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Version |Type of Message| Total Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Request ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Options Offset | Payload Offset | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | Requestor Address | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | Request Payload | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | Options | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Version - Protocol version. Currently 0 for development.
- Type - The type of message that follows.
- Total Length - The total length of the message, including the header fields, in bytes.
- Request ID - Identifier for this request from the requestor. The pair (Request ID, Requestor Address) should be unique within a reasonable period of time (hours or days).
- Options Offset - Byte offset of the beginning of the options fields. An offset value of 0 indicates no options.
- Payload Offset - Byte offset of the beginning of the message payloads.
- Requestor Address - Network Address of the original sender (originator) of the request message.
- Requestor Payload - Message-specific request payload, including options. See message types below.
- Options - A set of options for the query, currently limited to Recursion Requested.
Options
Options are encoded as a (Type, Length, Value) 3-tuple. Unsupported options can be ignored by the receiving host, but should be preserved when stored or forwarded so that other hosts have the opportunity to interpret them. The block of options are located either before or after the "payload" of the message.
The highest bit of the "Type" field is a reserved flag to indicate the final option for the message. The range of values for an option Type is 0x00-0x7F, and if the highest bit is set (i.e., (TYPE & 0x80) == 0x80), then no additional options will follow.
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ | Type | Length | Value | | Option 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ | Type | Length | Value | | Option 2 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+
The following Type/Length pairs are currently supported for Request messages by the prototype:
| Name | Type | Length | Value Format |
|---|---|---|---|
| Recursion Requested | 0 | 2 | 2-byte value, indicates whether the request should be forwarded to remote servers or not. Client should send 0x01 (true), servers should send 0x00 (false). |
| Expiration | 1 | 8*i | 8-byte expiration timestamp, in milliseconds since the Unix epoch, for each of the i bindings. The binding should be ejected at this time. |
| Time To Live | 2 | 8*i | 8-byte Time-To-Live value, specified in milliseconds, for each of the i bindings. How long the binding can remain cached. A relative timestamp, specified from when the request was sent. |
Lookup Request
The lookup request is used to retrieve the network binding(s) for a GUID. It includes only the query GUID value and a set of option flags (currently undefined). Its' format is as follows:
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | GUID | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- GUID - The GUID being queried in this message.
Insert/Update Message
An insert or update involves reporting new network location bindings to the name resolution service.
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | GUID | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Size (S) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ | | | | | Address Type | Address Length | | | | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Entry#1 ~ ~ | | Network Address #1 | | ~ ~ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ ~ ~ | Entry #2 | ~ ~ |...............................................................| ~ ~ | Entry #S | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- GUID - The GUID value being inserted/updated.
- Options - The options for the insert/update message (currently undefined).
- Size - The number of entries in the insert/update message.
- Entry - A Network Address as defined above.
Response Messages
Common Header
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Version |Type of Message| Total Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Request ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Options Offset | Payload Offset | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | Origin Address | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Response Code | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | Payload | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | Options | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Version - Protocol version. Currently 0 for development.
- Type - The type of message that follows.
- Total Length - The total length of the message, including the header fields, in bytes.
- Request ID - Identifier for this request from the requestor. The pair (Request ID, Requestor Address) should be unique within a reasonable period of time (hours or days).
- Options Offset - Byte offset of the beginning of the options fields. An offset value of 0 indicates no options.
- Payload Offset - Byte offset of the beginning of the message payloads.
- Origin Address - Network Address of the original sender (originator) of the reply message.
- Payload - The type-specific payload of the reply message, including options.
- Options - A set of options for the query, currently TTL or Expiration values.
Lookup Response
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Size (S) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ | | | | | Address Type | Address Length | | | | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Entry#1 ~ ~ | | Network Address #1 | | ~ ~ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ ~ ~ | Entry #2 | ~ ~ |...............................................................| ~ ~ | Entry #S | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Size - The number of entries in the insert/update message.
- Entry - A Network Address as defined above.
Insert/Update Response
The payload portion of Insert/Update response messages is empty.
Previous Wire Protocol (version 0)
This format was used in the initial prototype implementation of GNRS. It has since been replaced with the protocol above (version 1.0) and is now considered obsolete.
Insert Message
The Insert message is used to add a new GUID -> Network Address binding.
<Request ID><TYPE><Sender NA><Sender Port>
<GUID><Destination Flag><No. Bindings>
{ <Network Address><TTL><Weight> }+
- Request ID - 32-bit unsigned integer representing the unique request ID
- TYPE - 8-bit unsigned integer indicating the type of message sent. Value is 0.
- Sender NA - 30-byte (240-bit) network address of the originating sender.
- Sender Port - 32-bit unsigned integer representing the sender's UDP port for receiving the acknowledgment.
- GUID - 20-byte (160-bit) GUID value to insert.
- Destination Flag - 8-bit unsigned integer indicating whether the destination of the GUID binding has been computed. 1 indicates it has been computed, 0 indicates it has not.
- No. Bindings - 16-bit unsigned integer indicating how many bindings are contained in the message.
- Network Address - 30-byte (240-bit) network address of the binding.
- TTL - 32-bit unsigned integer indicating the lifetime of the binding, in milliseconds.
- Weight - 16-bit unsigned integer indicating the weight of this binding.
Insert ACK Message
The Insert ACK message is used to respond to Insert messages, indicating a successful insertion into the global GNRS.
<Request ID><TYPE><Sender NA><Sender Port> <Response Code>
- Request ID - 32-bit unsigned integer representing the unique request ID
- TYPE - 8-bit unsigned integer indicating the type of message sent. Value is 2.
- Sender NA - 30-byte (240-bit) network address of the originating sender.
- Sender Port - 32-bit unsigned integer representing the sender's UDP port for receiving the acknowledgment.
- Response Code - 8-bit unsigned integer indicating success (0) or failure (1).
Lookup Message
The Lookup message is used to query the GNRS about the current binding(s) for a specific GUID value.
<Request ID><TYPE><Sender NA><Sender Port> <GUID><Destination Flag>
- Request ID - 32-bit unsigned integer representing the unique request ID
- TYPE - 8-bit unsigned integer indicating the type of message sent. Value is 1.
- Sender NA - 30-byte (240-bit) network address of the originating sender.
- Sender Port - 32-bit unsigned integer representing the sender's UDP port for receiving the acknowledgment.
- GUID - 20-byte (160-bit) GUID value to insert.
- Destination Flag - 8-bit unsigned integer indicating whether the destination of the GUID binding has been computed. 1 indicates it has been computed, 0 indicates it has not.
Lookup Response Message
The Lookup Response message is sent by a server in reply to a Lookup Message. Lookup Response messages contain zero or more bindings for a GUID value.
<Request ID><TYPE><Sender NA><Sender Port>
<Response Code><No. Bindings>
{ <Network Address><TTL><Weight> }*
- Request ID - 32-bit unsigned integer representing the unique request ID
- TYPE - 8-bit unsigned integer indicating the type of message sent. Value is 3.
- Sender NA - 30-byte (240-bit) network address of the originating sender.
- Sender Port - 32-bit unsigned integer representing the sender's UDP port for receiving the acknowledgment.
- Response Code - 8-bit unsigned integer indicating success (0) or error (1).
- No. Bindings - 16-bit unsigned integer indicating how many bindings are contained in the message.
- Network Address - 30-byte (240-bit) network address of the binding.
- TTL - 32-bit unsigned integer indicating the lifetime of the binding, in milliseconds.
- Weight - 16-bit unsigned integer indicating the weight of this binding.
Updated