Protocol for the DoDWAN Network API

DoDWAN offers a network API accessible through the dodwand DoDWAN daemon.

The DoDWAN daemon implements a server to which application clients can connect. A so called NAPI connection is a transport session established between the client and dodwand, during which NAPI Protocol Data Units (NAPI PDUs) are exchanged. The transport mechanism is not implemented by the dodwan-napi plugin itself but by a descendent plugin (e.g., dodwan-napi-tcp).

A PDU is a serialized map. The serialization method implemented by an instance of the NAPI plugin can be chosen among several methods (presently: JSON or BSON).

A PDU issued by a client is a command PDU (e.g., publish). It is expected that the server answers (promptly) to a command with a response PDU. A token is included in the command and is copied in the corresponding response by the server to ensure command-response matching.

A PDU issued by the DoDWAN server is a response to a command or a notification. A notification is not directly linked to a unique command, even if it is a consequence of a command. There are two types of notifications: the notifications related to the changes of neighborhood (peers appearing and disapearing), and notifications related to the arrival of DoDWAN messages, resulting from subscriptions.

PDUs are maps, composed of a series of key/value pairs. The order of these pairs is not relevant. For a given command, response or notification, a number of pairs are compulsory, and some are optional. Note that the pair with key name is always present in a PDU. Each value in a pair has a given type among the following seven types:

String (string)
32 bit Integer (int32)
64 bit Integer (int64)
Boolean (boolean)
Binary Data (binary)
Map of strings (smap)
Array of strings (sarray)

The null value is not authorized.

Connections and sessions

A client opens a NAPI connection to the server using the underlying transport protocol (presently websocket or TCP).

The client uses the NAPI protocol on this connection. The first NAPI PDU issued by the client should be the hello command in which the client passes its (unique) id to the server. Any other command received by the server before a hello command will be answered to with an error PDU.

The reception by the server of a hello command marks the beginning of a session. During a session, the notifications generated by DoDWAN are transmitted to the client that initiated the session, on the current underlying connection, if the session is active. A session is made active once the client has issued a start command. It is made inactive when the client has issued a stop command.

Notifications generated by DoDWAN when no connection is opened or when an opened connection is non active are lost. The client may retrieve later missed subscription notifications with the get_matching command.

A connection may be closed for several reasons (unexpectedly or not). When closed, the connection is automatically considered inactive. The client is expected to retry to open the connection within the session, and, on this connection, to first issue a hello command with the continuation option set.

A session is ended explicitely by the client when this client issues a bye command`.

On the server's side, the sessions are not persistent. This means that no sessions are considered opened by the server when the server restarts after having been stopped (or after a crash). The client can be aware that the server has restarted when the server responds to a hello command (with the continuation option set) with an error.

DoDWAN Descriptors

A DoDWAN message is composed of descriptor and a payload. A message descriptor is a list of attribute assignments, comprising each a key and a string value. The attributes are either system attributes (whose key starts with the undescore sign), or application attributes (whose key doesn't start the undescore sign).

The DoDWAN message descriptors used in the Network API commands of type smap.

When providing a descriptor (in the publish command) the user should provide only application attributes. Any number of application attributes can be provided (possibly no attribute at all).

Received decriptors may include also system attributes, set by the DoDWAN middleware. For example:

_docid the id of the message, assumed to be unique
_date the date of reception of the message (a string containing a 64-bit integer equals to the number of ms since Unix EPOCH, e.g., "1516183647000")
_dline the date of expiration of the message (a string containing a 64-bit integer equals to the number of ms since Unix EPOCH)

Example of a descriptor (in JSON)

{"_docid":"35465tr5", "_date":"1516183647000", "topic":"general", "type":"PDF"}

Commands (issued by the application client and received by the server)

Open a session

name    : hello           (string)
tkn     : <token>         (string)
client  : <client_id>     (string)
cont    : <continuation>  (boolean)

Examples (in JSON):
  {"name":"hello", "tkn":"1234", "client":"jeronimo"}
  {"name":"hello", "tkn":"1234", "client":"jeronimo", "cont":true}

After a connection has been established with the server, the first PDU the client should issue is a hello command, passing its unique client id with option 'client', in order to initiate a new session. If the hello command is used for initating a new session although the previous one has not been closed (cf. command bye), the new session overrides the old one after all current subscriptions have been deleted.

Option cont should be set to true if the client wants to continue an already initiated session, keeping all the subscriptions already set.

The server should reply to this command with an ok, or error PDU, namely when the passed client id is unknown when the session is continued.

Close a session

name    : bye          (string)
tkn     : <token>      (string)

Examples (in JSON):
  {"name":"bye", "tkn":"1234"}

The client closes a session when it no longer wants to interact with the server. The server will forget the client id, remove all the subscriptions set by this client, and close the underlying connection.

The server will not send any reply to this command, unless an internal error occurs, in which case and error response PDU will be issued.

Starts the reception of notifications

name    : start       (string)
tkn     : <token>     (string)

Example (in JSON):
  {"name":"start", "tkn":"1234"}

Indicates to the server that DoDWAN notifications should now be transmitted to the client. Note that notification generated previously by DoDWAN are not transmitted.