DDNS Protocol Overview
Version 1.0.2

The DDNS protocol is RPC based. I'll describe first the methods available by RPC, using a notation that is a mixture of Java and JSON. (Remember that the actual implementations take a single JSONObject argument and return one as their result, because that's what our RPC implementation requires.)

The behavioral descriptions of the methods are logical. You can implement the methods exactly as described, but any implementation producing results that are functionally equivalent for clients expecting the described behavior are also correct.

RPC Method Interfaces

All methods are in the name server. The name resolver doesn't export any methods by RPC. The application name (for the RPC call) is "ddns". The method names are those shown below.

The return values of the methods include fields {node: Node, done: boolean}. A Node is a name and associated resource record, described more fully later. The done boolean is true if the request has been completed, and false if the DDNS service is returning a node that is not the one named by the call argument.

If some error occurs during processing, a DDNSException is returned, instead of the function's normal result. Those exceptions are described later.

• {node: Node, done: boolean} resolve(String name) throws DDNSException

  The argument is a name to be resolved. The returned boolean is true if the returned node is the one with that name, and false if it is some other node.

  Resolution stops when:

  • An A or SOA resource record with a matching name is encountered. If the resource record contains a valid address, the name/resource record and true are returned. Otherwise, a DDNSNoAddressException is returned.

  • A CNAME record is encountered. In this case the CNAME node and false are returned.

  • An NS record is encountered. If the NS record doesn't contain a valid address, a DDNSNoAddressException is returned. Otherwise, the node and false are returned.

• {node: Node, done: boolean, lifetime: int} register(String name, String ip, int port, String password) throws DDNSException

  register() works exactly like resolve(), except for two small things. First, if the name resolves to an A or SOA or NS record, the address stored in that record is updated, so long as a password validation check succeeds. The check is simply that the argument password with the one associated with the name tree node are equal. If the check fails, a DDNSAuthorizationException is returned. Otherwise, the updated node is returned. (done is always set to false when an NS record is being returned.)

  Second, the remote service returns the lifetime of the registration: how much time can pass before the registration times out and the node is marked as having no address again. The lifetime is an int, and is measured in seconds.

• {node: Node, done: boolean} unregister(String name, String password) throws DDNSException

  unregister() works exactly like register(), except for three things:

  1. It marks the node as having no current address, rather than updating its address.
  2. If done is true, no node is returned.
  3. If an NS record with a name matching the argument name is being returned, the value of the returned node is the NS record before unregistration takes place.

RPC Encoding

All strings, including JSONObject field names, are case sensitive. What's shown below is basically the JSON encoding, although slightly cleaned up for readability.

Invocations
For all invocations, the arguments are the JSONObject encoding of the interface arguments shown above. The JSONObject field names are the parameters names above, and the types of the fields are the types above.

For instance, register("jz.cse461.", "192.168.0.77", 34562, "jzpassword") would have its arguments encoded as:

{port:34562, name:"jz.cse461.","password":"jzpassword","ip":"192.168.0.77"}

Returned Values
Returned values contain a field, resulttype, indicating what is being returned. resulttype can have one of these values: "resolveresult", "registerresult", "unregisterresult", and "ddnsexception".

Additionally, returned values contain additional fields, as shown in the interface descriptions above. There are at most three such fields: the representation of a node, the done boolean, and an integer lifetime. Here's a fairly inclusive example:

{node:[node representation described next], lifetime:600, resulttype:"registerresult", "done":true}

Returned Node Encoding
A node is a DDNS full name and a resource record. Its encoding depends on the type of the resource record.

• A record
  {name: String, type: "A", ip: String, port: int}

• NS record
  {name: String, type: "NS", ip: String, port: int}

• SOA record
  {name: String, type: "SOA", ip: String, port: int}

• CNAME record
  {name: String, type: "CNAME", alias: String}

A, NS, and SOA nodes are sent only if they have currently registered addresses. If not, a DDNSNoAddressException is returned instead.

Returned Exception Encoding

Exceptions are passed back as normal RPC payloads. Each type of exception is identified by an integer id. The full exception message (as in Exception.getMessage()) is always returned, but its value is not standardized. Some exception types return additional, specific information that can be used to create a sensible, customized message.

• DDNSNoSuchNameException
{resulttype: "ddnsexception", exceptionnum: 1, message: String, name: String}
  Thrown when the name doesn't exist in the namespace.

• DDNSNoAddressException
{resulttype: "ddnsexception", exceptionnum: 2, message: String, name: String}
  The name resolved to a node, but there is no address currently associated with that name.

• DDNSAuthorizationException
{resulttype: "ddnsexception", exceptionnum: 3, message: String, name: String}
  Thrown when an operation requiring a password is requested, but the correct password has not been supplied.

• DDNSRuntimeException
{resulttype: "ddnsexception", exceptionnum: 4, message: String}
  This is a catch-all exception class, used to report anything that goes wrong not falling into one of the five other exception types. The message is intended to be useful to the caller in determining what went wrong.

• DDNSTTLExpiredException
{resulttype: "ddnsexception", exceptionnum: 5, message: String, name: String}
  Some resolution step limit used to deal with possible naming loops went to zero before the name was resolved. The name may or may not exist, but in any case couldn't be resolved.

• DDNSZoneException
{resulttype: "ddnsexception", exceptionnum: 6, message: String, name: String, zone: String}
  The name server was asked to resolve a name not in its zone (the subtree of the namespace rooted at the server's SOA name).