-
Notifications
You must be signed in to change notification settings - Fork 2
Conga Protocol Description
Current Version: V0.5
The Conga messages themselves will be passed around the conga network separately from the management interface and messages, which overwhelmingly will be routed over HTTP. The conga messages themselves cannot use HTTP, as they are passed in a peer-to-peer fashion rather than using a client-server model. This makes HTTP a poor application-layer protocol to use. For this reason, we will define our own ad-hoc, simple protocol for use with Conga messages. This document defines that protocol.
This is a living document. As we encounter other necessary use-cases, this document will be updated to reflect those changes. Please check back on a regular basis!
Conga messages are transmitted over a single TCP connection between the conga participant and the managing server. The server itself does not participate in the conga, but acts as a transparent proxy, forwarding messages from one participant to another. This star network design allows us to avoid painful and fragile NAT-busting code in order to establish a truly peer-to-peer model.
Each client will register its intent to join a conga with the managing server over the HTTP interface. When registration is successful the server will respond with a JSON object that includes a port to connect to for the conga interface. This port will be well outside the well-defined range: between 20000 and 655535.
The client will then establish a TCP connection to that port. This connection will need to be kept-alive. There is currently no scope for keep-alives at the application layer.
The Conga protocol is text-based. Because of its limited utility, we can avoid most of the markers that are used in other text-based protocols like HTTP. Each message is made up of UTF-8 encoded text. The message has three parts. First, a verb line, that takes the form of an all-caps word from the verb list (see below), followed by \r\n. The next component are headers, which are multiple lines of the form:
Key: Value\r\n
All characters aside from the Unicode Colon (U+003A) ':', the Unicode Line Feed (U+000A) '\n' and the Unicode Carriage Return (U+000D) '\r' are valid for the Key. The Value may include colons, but otherwise is bound by the same limitations.
The list of headers is separated from the body of the message by a blank line (still terminated by \r\n). The body may then be arbitrary text running to the remaining length of the message.
The following verbs are defined, and were added in V0.3.
- HELLO. This verb is used for the first message, to introduce a client to the server. This message should have no body. It should contain a Content-Length header (set to zero) and a User-ID header, set to the User-ID assigned to the client by the web app. If this ID is unknown or belongs to a previously registered user, the request will be ignored and the connection closed.
- MSG. This verb defines any message that is expecting to be sent around the conga. It may contain any body. It must contain a Content-Length header.
- BYE. A client should send this message before disconnecting and closing the connection, to allow the server to tidy up. It should contain no body. It must contain a Content-Length header.
The following headers were added in V0.2:
-
Content-Length. This should have, as a value, the length of the body of the message. This header is mandatory. 0 is an acceptable value. For example,Content-Length: 25.
The following headers were added in V0.4:
-
User-ID. This should have as a value the user ID returned by the conga join endpoint of the REST webserver. For example,User-ID: 6855.
The following headers were added in V0.5:
-
Message-ID. This header is assigned by the server. Whenever a MSG is sent from the server to a client, it will have one of these headers attached: when the client echoes it back to the server for sending to the next participant, the same value MUST be present on the MSG. If a new message is being sent from the client, this header MUST NOT be present: the server will assign its own value.
It's likely we'll define more headers, mostly stolen from HTTP. My current thoughts are Content-Type and Authorization (though Authorization will do something quite different than it does in HTTP).