Jump to: navigation, search

Difference between revisions of "Zaqar/specs/Protocols/Wire Transport"

m (Structure)
m (Example)
 
Line 61: Line 61:
 
     {
 
     {
 
         "action": "post_message",
 
         "action": "post_message",
         "header": {
+
         "headers": {
 
             "User-Agent": "python/2.7 killer-rabbit/1.2",
 
             "User-Agent": "python/2.7 killer-rabbit/1.2",
 
             "Date": "Wed, 2    8 Nov 2012 21:14:19 GMT",
 
             "Date": "Wed, 2    8 Nov 2012 21:14:19 GMT",

Latest revision as of 19:56, 19 January 2015

Wire Transport Protocol

Zaqar currently has a well defined protocol that works well for HTTP. As a project, we're looking forward to welcome more transports that will work for different use-cases but we don't have a way to support them. This document aims to define such protocol to establish the basis for the support of the mentioned transports.

Message format

Generally, wire transport protocols don't define a high level abstraction on how the message would look like. Hereby we design our own format, which tries to be as much compliant as possible with the HTTP structure.

Serialization

Zaqar's persistent transports will use JSON as a serialization format. The utilization of a more efficient serialization format (e.g. Protobufs) is under discussion.

Structure

    {
        "action": "",
        "headers": {},
        "body": {
            ...
        }
    }

Headers

Even though Zaqar's endpoints try to be as much similar as possible, there are some slightly differences between them. Note that wire transports doesn't implement some of the HTTP headers since they're meaningless for it, like:

  • Host
  • Content-Length
  • Accept-Encoding
  • Content-Type


Header Description
User-Agent The name and version of the Zaqar client, as well as a UUID for that client. Zaqar uses the UUID to distinguish publishers from subscribers, i.e., to avoid echoing an agent's own messages back to it.
Date The current date and time, using the standard RFC 1123 HTTP date format
Accept Media type desired. `application/json`.
X-Auth-Token Keystone auth token
X-Project-ID An ID for a project to which the value of X-Auth-Token grants access. Queues will be created under this project.
Client-ID A unique ID for each client instance. In Zaqar, this is used to avoid echoing a sender's messages back to the same instance, and may be logged by the server for future use. Should be generated once and persisted between restarts of the client.

Example

    {
        "action": "post_message",
        "headers": {
            "User-Agent": "python/2.7 killer-rabbit/1.2",
            "Date": "Wed, 2    8 Nov 2012 21:14:19 GMT",
            "Accept": "application/x-msgpack",
            "Client-ID": 30387f00-39a0-11e2-be4d-a8d15f34bae2,
            "X-Project-ID": 518b51ea133c4facadae42c328d6b77b,
            "X-Auth-Token": "7d2f63fd-4dcc-4752-8e9b-1d08f989cc00"
        },
        "body": {
            ...
        }
    }

Connection

The wire transport protocol also have to define the way for peers to identify each other at TCP connection time. Given that we are willing to give support for different implementations, we decided that this has to be depicted by the wire transport implementation itself. For example, in the case of websockets, the connection mechanism works as specified in the RFC6455.

Security

The security model used for data transmission is also a concern of the wire transport protocol. As stated in the previous section, we decided to delegate this task to the wire transport implementation in order to be able to support multiple implementations. For example, in the case of websockets, the security model used is the one specified in the RFC6455.