| | 1 | 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. |
| | 2 | |
| | 3 | 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. |
| | 4 | |
| | 5 | == Common Objects == |
| | 6 | |
| | 7 | === Network Address === |
| | 8 | |
| | 9 | 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. |
| | 10 | |
| | 11 | {{{ |
| | 12 | #!html |
| | 13 | <pre> |
| | 14 | 0 1 2 3 |
| | 15 | 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 |
| | 16 | 0 1 2 3 Octet |
| | 17 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 18 | | Address Type | Address Length | |
| | 19 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 20 | ~ ~ |
| | 21 | | Value | |
| | 22 | ~ ~ |
| | 23 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 24 | </pre> |
| | 25 | }}} |
| | 26 | |
| | 27 | * '''Type''' - 16-bit value identifying the type of network address represented.<br /> |
| | 28 | * '''Length''' - 16-bit unsigned integer value identifying the length of the network address in bytes. |
| | 29 | * '''Value''' - Variable-length binary value. Contains the raw (binary) form of the network address, dependent on the type and length. |
| | 30 | |
| | 31 | The following Type/Value pairs are currently supported by the prototype: |
| | 32 | |
| | 33 | || '''Type''' || '''Length''' || '''Value Format''' || |
| | 34 | ||0 || 6 ||4-byte IPv4 address, 2-byte UDP port || |
| | 35 | || 1 ||20 ||20-byte GUID value || |
| | 36 | |
| | 37 | == Request Messages == |
| | 38 | |
| | 39 | === Common Header === |
| | 40 | |
| | 41 | {{{ |
| | 42 | #!html |
| | 43 | <pre> |
| | 44 | 0 1 2 3 |
| | 45 | 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 |
| | 46 | 0 1 2 3 Octet |
| | 47 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 48 | | Version |Type of Message| Total Length | |
| | 49 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 50 | | Request ID | |
| | 51 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 52 | | Options Offset | Payload Offset | |
| | 53 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 54 | ~ ~ |
| | 55 | | Requestor Address | |
| | 56 | ~ ~ |
| | 57 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 58 | ~ ~ |
| | 59 | | Request Payload | |
| | 60 | ~ ~ |
| | 61 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 62 | ~ ~ |
| | 63 | | Options | |
| | 64 | ~ ~ |
| | 65 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 66 | </pre> |
| | 67 | }}} |
| | 68 | |
| | 69 | * '''Version''' - Protocol version. Currently 0 for development. |
| | 70 | * '''Type''' - The type of message that follows. |
| | 71 | * '''Total Length''' - The total length of the message, including the header fields, in bytes. |
| | 72 | * '''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). |
| | 73 | * '''Options Offset''' - Byte offset of the beginning of the options fields. An offset value of 0 indicates no options. |
| | 74 | * '''Payload Offset''' - Byte offset of the beginning of the message payloads. |
| | 75 | * '''Requestor Address''' - Network Address of the original sender (originator) of the request message. |
| | 76 | * '''Requestor Payload''' - Message-specific request payload, including options. See message types below. |
| | 77 | * '''Options''' - A set of options for the query, currently limited to the ones listed below. |
| | 78 | |
| | 79 | === Options === |
| | 80 | |
| | 81 | 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. |
| | 82 | |
| | 83 | 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. |
| | 84 | |
| | 85 | {{{ |
| | 86 | #!html |
| | 87 | <pre> |
| | 88 | 0 1 2 3 |
| | 89 | 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 |
| | 90 | 0 1 2 3 Octet |
| | 91 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ |
| | 92 | | Type | Length | Value | | Option 1 |
| | 93 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ |
| | 94 | | Type | Length | Value | | Option 2 |
| | 95 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ |
| | 96 | </pre> |
| | 97 | }}} |
| | 98 | |
| | 99 | The following !Type/Length pairs are currently supported for Request messages by the prototype: |
| | 100 | |
| | 101 | || '''Name''' || '''Type''' || '''Length''' || '''Value Format''' || |
| | 102 | ||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). || |
| | 103 | ||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. | | |
| | 104 | || 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. || |
| | 105 | |
| | 106 | === Lookup Request === |
| | 107 | |
| | 108 | 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: |
| | 109 | |
| | 110 | {{{ |
| | 111 | #!html |
| | 112 | <pre> |
| | 113 | 0 1 2 3 |
| | 114 | 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 |
| | 115 | 0 1 2 3 Octet |
| | 116 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 117 | ~ ~ |
| | 118 | | GUID | |
| | 119 | ~ ~ |
| | 120 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 121 | </pre> |
| | 122 | }}} |
| | 123 | |
| | 124 | * '''GUID''' - The GUID being queried in this message. |
| | 125 | |
| | 126 | == !Insert/Update Message == |
| | 127 | |
| | 128 | An insert or update involves reporting new network location bindings to the name resolution service. |
| | 129 | |
| | 130 | {{{ |
| | 131 | #!html |
| | 132 | <pre> |
| | 133 | 0 1 2 3 |
| | 134 | 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 |
| | 135 | 0 1 2 3 Octet |
| | 136 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 137 | ~ ~ |
| | 138 | | GUID | |
| | 139 | ~ ~ |
| | 140 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 141 | | Size (S) | |
| | 142 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ |
| | 143 | | | | | |
| | 144 | | Address Type | Address Length | | |
| | 145 | | | | | |
| | 146 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Entry#1 |
| | 147 | ~ ~ | |
| | 148 | | Network Address #1 | | |
| | 149 | ~ ~ | |
| | 150 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ |
| | 151 | ~ ~ |
| | 152 | | Entry #2 | |
| | 153 | ~ ~ |
| | 154 | |.............................................................| |
| | 155 | ~ ~ |
| | 156 | | Entry #S | |
| | 157 | ~ ~ |
| | 158 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 159 | </pre> |
| | 160 | }}} |
| | 161 | |
| | 162 | * '''GUID''' - The GUID value being !inserted/updated. |
| | 163 | * '''Size''' - The number of entries in the !insert/update message. |
| | 164 | * '''Entry''' - A Network Address as defined above. |
| | 165 | |
| | 166 | == Response Messages == |
| | 167 | |
| | 168 | === Common Header === |
| | 169 | |
| | 170 | {{{ |
| | 171 | #!html |
| | 172 | <pre> |
| | 173 | 0 1 2 3 |
| | 174 | 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 |
| | 175 | 0 1 2 3 Octet |
| | 176 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 177 | | Version |Type of Message| Total Length | |
| | 178 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 179 | | Request ID | |
| | 180 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 181 | | Options Offset | Payload Offset | |
| | 182 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 183 | ~ ~ |
| | 184 | | Origin Address | |
| | 185 | ~ ~ |
| | 186 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 187 | | Response Code | | |
| | 188 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 189 | ~ ~ |
| | 190 | | Payload | |
| | 191 | ~ ~ |
| | 192 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 193 | ~ ~ |
| | 194 | | Options | |
| | 195 | ~ ~ |
| | 196 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 197 | </pre> |
| | 198 | }}} |
| | 199 | |
| | 200 | * '''Version''' - Protocol version. Currently 0 for development. |
| | 201 | * '''Type''' - The type of message that follows. |
| | 202 | * '''Total Length''' - The total length of the message, including the header fields, in bytes. |
| | 203 | * '''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). |
| | 204 | * '''Options Offset''' - Byte offset of the beginning of the options fields. An offset value of 0 indicates no options. |
| | 205 | * '''Payload Offset''' - Byte offset of the beginning of the message payloads. |
| | 206 | * '''Origin Address''' - Network Address of the original sender (originator) of the reply message. |
| | 207 | * '''Payload''' - The type-specific payload of the reply message, including options. |
| | 208 | * '''Options''' - A set of options for the query, limited to the set described above. |
| | 209 | |
| | 210 | === Lookup Response === |
| | 211 | |
| | 212 | {{{ |
| | 213 | #!html |
| | 214 | <pre> |
| | 215 | 0 1 2 3 |
| | 216 | 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 |
| | 217 | 0 1 2 3 Octet |
| | 218 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 219 | | Size (S) | |
| | 220 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ |
| | 221 | | Address Type | Address Length | | |
| | 222 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Entry#1 |
| | 223 | ~ ~ | |
| | 224 | | Network Address #1 | | |
| | 225 | ~ ~ | |
| | 226 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---+ |
| | 227 | ~ ~ |
| | 228 | | Entry #2 | |
| | 229 | ~ ~ |
| | 230 | |.............................................................| |
| | 231 | ~ ~ |
| | 232 | | Entry #S | |
| | 233 | ~ ~ |
| | 234 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| | 235 | </pre> |
| | 236 | }}} |
| | 237 | |
| | 238 | * '''Size''' - The number of entries in the !insert/update message. |
| | 239 | * '''Entry''' - A Network Address as defined above. |
| | 240 | |
| | 241 | === !Insert/Update Response === |
| | 242 | |
| | 243 | The payload portion of !Insert/Update response messages is empty. |
