GNRS Network Protocol
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 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.
The GNRS stores GUID/Value bindings of different types. The client can send a lookup request for a particular type, Or he can request for the all the mappings of a particular GUID.
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 Bit 0 1 2 3 Octet +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Address Type | Address Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | Value | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Type - 16-bit value identifying the type of network address represented.<br />
- 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 Bit 0 1 2 3 Octet +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Version |Type of Message| Total Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Request ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Options Offset | Payload Offset | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | Requestor Address | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | Request Payload | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | Global 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.
- Global Options - A set of global options for the query.
Options
There are two types of options - Global and Local. Global options which are appended to the message as whole (e.g. Recursive Option). Local options are associated with each binding that is stored in the GNRS (e.g. Expiration Option). Both types are encoded in the same format.
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 Bit 0 1 2 3 Octet +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ | 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 binding(s) for a GUID. It includes the query GUID and optional parameter 'type'. If a type is specified, only that particular binding is fetched. Multiple types can be included in a single lookup request. If no type is specified, all the bindings for that GUID are returned. 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 Bit 0 1 2 3 Octet +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | GUID | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Number of Types | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type #1 | Type #2 | ............................................................... | Type #n-1 | Type #n | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- GUID - The GUID being queried in this message.
- No of Types - The number of types being fetched. Value of 0 fetches all the stored bindings for the GUID.
- Type#n - Type of binding
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 Bit 0 1 2 3 Octet +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~ ~ | GUID | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Number of Bindings | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ | Type | Number of values | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | Length of options | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | ~ ~ | | Values | |Entry #1 ~ ~ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | ~ ~ | | Local options | | ~ ~ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ ~ ~ | Entry #2 | ~ ~ |.............................................................| ~ ~ | Entry #n | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- GUID - The GUID value being !inserted/updated.
- Number of Bindings - Number of bindings being inserted/updated.
- Entry - Binding of a type
- Type - Type of the binding being inserted/updated
- Number of values - Number of values of the type.
- Length of options - Length of local options.
- Values - The values of the type. Parsing will be according to the type (e.g. Network Address).
- Local Options - The options associated with the values.
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 Bit 0 1 2 3 Octet +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 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, limited to the set described above.
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 Bit 0 1 2 3 Octet +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Number of Bindings | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ | Type | No of Values | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | Length of options | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | ~ ~ | | Values | |Entry #1 ~ ~ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | ~ ~ | | Local options | | ~ ~ | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ ~ ~ | Entry #2 | ~ ~ |.............................................................| ~ ~ | Entry #n | ~ ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- GUID - The GUID value being !inserted/updated.
- Number of Bindings - Number of bindings in the response
- Entry - Binding of a type
- Type - Type of the binding
- Number of values - Number of values of the type
- Length of options - Length of local options.
- Values - The values of the type. Parsing will be according to the type (e.g. Network Address).
- Local Options - The options associated with the values
Insert/Update Response
The payload portion of Insert/Update response messages is empty.
