Protocol

Table of Contents

• Overview
  • Current status
  • Requirements
• Specification
  • Message format
  • Commands
    • Registrant protocol
    • Resolver protocol
  • STATUS codes

Overview

Current status

The WDNS protocol is currently in development, so this page is subject to heavy revision.

Note: Once the protocol matures more, this (Current status) section will be removed.

Requirements

The protocol should:

• place into formal specification:
  • communication between registrar and registrant
  • communication between registrar and resolver
• be general enough to apply to third party software using the protocol
• be easy to understand 😊

Note: This section (Requirements) should not be removed at any time.

Specification

Message format

All messages are UTF-8-encoded JSON messages, which adhere to the following format:

12345
{
	"type": string,
	"content": [string]
}

The 12345 preceding the JSON content is a numeric value detailing how many bytes the JSON content consumes, and is not delimited from the { character by any padding, so the message start would look like 12345{.

Commands

In the following command descriptions, the fields with arrows pertain to which program is sending and which program is receiving messages containing the command, as follows (Registrants and resolvers both fall under the category of Client):

• Client --> Registrar
  • The message is sent from a client to a registrar.
• Client <-- Registrar
  • The message is sent from a registrar to a client.
• Client <-> Registrar
  • The message is sent bi-directionally, either from the client or registrar, to the complementary program.

Some commands have parameters in order to allow programs to send descriptive messages to one another. For instance, there may be a command FOO which has one mandatory parameter, id, and one optional parameter, something. This command will be listed as FOO <id> [something], where the angle brackets enclosing <id> denote that the parameter is mandatory, and the square brackets enclosing [something] denote that the parameter is optional, or may be omitted.

TODO: Change the specification of these commands to adhere to the message format specification.

Registrant protocol

• CLAIM <domain>
  • Client --> Registrar
  • Attempts to claim the domain specified by <domain>. If it is available, <domain> is entered into the registrar's registry, associated with the client.
• DISCONNECT
  • Client --> Registrar
  • Requests that the registrar close the connection. This lets the registrar know that the disconnection was intentional and should always be sent before disconnecting.
• IDENT registrant
  • Client --> Registrar
  • Identifies the client to the registrar as a registrant. This command must be issued immediately following connection.
• PING
  • Client <-- Registrar
  • Tests the presence of a connection. After receiving this message from a registrar, the client should respond with a PONG message.
• PONG
  • Client --> Registrar
  • Responds to a PING request in order to let the registrar know that the connection is still valid.
• RELEASE <domain>
  • Client --> Registrar
  • If the domain specified by <domain> is claimed by the registrar sending this message, releases (deletes) that claim. Otherwise, the registrar will send a STATUS message in response.
• STATUS <code>
  • Client <-> Registrar
  • Sends a status code in response to a request. <code> must be some uppercase hexadecimal value, such as 17FA3D4. There are no restrictions on the length of <code>.

Resolver protocol

• FIELD <field> [content]
  • Client <-- Registrar
  • Supplies the contents of a field within the registry entry previously queried by the resolver with a QUERY command.
• IDENT resolver
  • Client --> Registrar
  • Identifies the client to the registrar as a resolver. This command must be issued immediately following connection.
• QUERY <domain> [field [field [...]]]
  • Client --> Registrar
  • Queries the registrar to search within its registry for the domain <domain>. If the domain cannot be found, a STATUS response will be sent by the registrar. Otherwise, if any [field] parameters are supplied, the registrar searches within the registry entry for the field [field] for each supplied parameter. The registrar responds with a FIELD message. If no [field] parameter is supplied, Address is implied.
• STATUS <code>
  • Client <-> Registrar
  • Sends a status code in response to a request. <code> must be some uppercase hexadecimal value, such as 17FA3D4. There are no restrictions on the length of <code>.

STATUS codes

All status codes consist of an arbitrary quantity of hexadecimal characters.

TODO: Restructure these codes' definition format to work better with the 'status' module in the codebase.

• Success messages (XXXX)
  • Registrar -> Registrant
    • 1000
  • Registrar -> Resolver
    • 2000
  • Registrant -> Registrar
    • 3000
  • Resolver -> Registrar
    • 4000
  • Registrar -> Unidentified client
    • 5000
  • Unidentified client -> Registrar
    • 6000
• Error messages (XXXXX)
  • Registrar -> Registrant
    • 1XXXX
  • Registrar -> Resolver
    • 2XXXX
  • Registrant -> Registrar
    • 3XXXX
  • Resolver -> Registrar
    • 4XXXX
  • Registrar -> Unidentified client
    • 5XXXX
  • Unidentified client -> Registrar
    • 6XXXX
  • IDENT errors (X000X)
    • Undefined error
      • X0000
    • Not accepting new registrants
      • 10001
    • Registrar closed to resolvers
      • 20001
    • Client not permitted to identify as a registrant (black- or white-listed)
      • 10002
    • Client not permitted to identify as a resolver (black- or white-listed)
      • 20002
    • Client type supplied is invalid
      • 50003
  • Miscellaneous errors (XFXXX)
    • Undefined error
      • XF000
    • Message not recognized
      • XF001