DDNS Protocol Overview

The DDNS protocol is RPC based. I'll describe first the methods available by RPC. This interface description is logical, not actual implementation. The actual implementations take a single JSONObject argument and return one as their result, because that's what our RPC implementation requires. These descriptions show you what the argument and return value JSONObjects contain, though. The variable names shown are the names of the fields in the transmitted JSONObject.

Similarly, the behavioral descriptions 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

I'm using the notation "<Node, boolean>" to indicate a tuple, even though Java doesn't support that directly. A Node is a name and associated resource record, described more fully later. The returned boolean is true if the request has been completed, and false if the DDNSService 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, boolean done> 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 on this name server proceeds until:

  • The name is resolved to an A or SOA resource record. 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 resolution stops, and 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, boolean done, int lifetime> 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 simply compares for equality the argument password with the one associated with the name tree node. If they don't match, 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, measured in seconds.

• <Node node, int done> unregister(String name, String password) throws DDNSException

  unregister() works exactly like register(), except for two things. First, it marks the node as having no current address rather than updating its address. Second, if done is true, no node is returned.

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 Tuples
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 a tuple, as shown in the interface descriptions above. The tuples contain at most three things: 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 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}

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).

Additionally, the implementation running on cse461.cs returns an args: JSONObject field containing the call arguments, in case that helps with debugging. This is an extension, though, not required by the standard.