Dmsg

dmsg

Distributed messaging system.

Terminology

• entity - A service of dmsg (typically being part of an executable running on a machine).
• entity type - The type of entity. dmsg has three entity types; dmsg.Server, dmsg.Client, dmsg.Discovery.
• entry - A data structure that describes an entity and is stored in dmsg.Discovery for entities to access.
• frame - The data unit of the dmsg system.
• frame type - The type of dmsg frame. There are four frame types; REQUEST, ACCEPT, CLOSE, FWD, ACK.
• connection - The direct line of duplex communication between a dmsg.Server and dmsg.Client.
• transport - A line of communication between two dmsg.Clients that is proxied via a dmsg.Server.
• transport ID - A uint16 value that identifies a transport.

Entities

The dmsg system is made up of three entity types:

• dmsg.Discovery is a RESTful API that allows dmsg.Clients to find remote dmg.Clients and dmsg.Servers.
• dmsg.Server proxies frames between clients.
• dmsg.Client establishes transports between itself and remote dmsg.Clients.

Entities of types dmsg.Server or dmsg.Client are represented by a secp256k1 public key.

           [D]

     S(1)        S(2)
   //   \\      //   \\
  //     \\    //     \\
 C(A)    C(B) C(C)    C(D)

Legend:

• [D] - dmsg.Discovery
• S(X) - dmsg.Server
• C(X) - dmsg.Client

Connection Handshake

A Connection refers to the line of communication between a dmsg.Client and dmsg.Server.

To set up a dmsg Connection, dmsg.Client dials a TCP connection to the dmsg.Server and then they perform a handshake via the noise protocol using the XK handshake pattern (with the dmsg.Client as the initiator).

Note that dmsg.Client always initiates the dmsg connection, and it is a given that a dmsg.Client always knows the public key that identifies the dmsg.Server that it wishes to connect with.

Frames

Frames are sent and received within a dmsg connection after the noise handshake. A frame has two sections; the header and the payload. Here are the fields of a frame:

|| FrameType | TransportID | PayloadSize || Payload ||
|| 1 byte    | 2 bytes     | 2 bytes     || ~ bytes ||

• The FrameType specifies the frame type via the one byte.
• The TransportID contains an encoded uint16 which represents a identifier for a transport. A set of IDs are unique for a given dmsg connection.
• The PayloadSize contains an encoded uint16 which represents the size (in bytes) of the payload.
• The Payload have a size that is obtainable via PayloadSize.

The following is a summary of the frame types:

FrameType	Name	Payload Contents	Payload Size
0x1	REQUEST	initiating client's public key + responding client's public key	66
0x2	ACCEPT	initiating client's public key + responding client's public key	66
0x3	CLOSE	1 byte that represents the reason for closing	1
0xa	FWD	uint16 sequence + transport payload	>2
0xb	ACK	uint16 sequence	2

Transports

Transports are represented by transport IDs and facilitate duplex communication between two dmsg.Clients which are connected to a common dmsg.Server.

Transport IDs are assigned in such a manner:

• A dmsg.Client manages the assignment of even transport IDs between itself and each connected dmsg.Server. The set of transport IDs will be unique between itself and each dmsg.Server.
• A dmsg.Server manages the assignment of odd transport IDs between itself and each connected dmsg.Client. The set of transport IDs will be unique between itself and each dmsg.Client.

For a given transport:

• Between the initiating client and the common server - the transport ID is always a even value.
• Between the responding client and the common server - the transport ID is always a odd value.

Hence, a transport in it's entirety, is represented by 2 transport IDs.