Difference between revisions of "Zaqar/specs/Protocols/Wire Transport"
m (Vkmc moved page Zaqar/specs/zmq/api/v1 to Zaqar/specs/Protocols/Wire Transport: The procotol specifyed for ZMQ will be used for wire transport) |
(Update to wire-transport) |
||
Line 1: | Line 1: | ||
− | = | + | = 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. | |
+ | Generally, wire transport protocols don't define a high level abstraction on how the packet would look like. Hereby we design our own format, which tries to be as much compliant as possible with the HTTP structure. | ||
− | + | We will base our protocol in http://rfc.zeromq.org/spec:33 | |
== Serialization == | == Serialization == | ||
− | + | Zaqar's persistent transports will use [http://msgpack.org/ msgpack] as a serialization format. | |
== Structure == | == Structure == | ||
Line 24: | Line 25: | ||
== Headers == | == Headers == | ||
− | Even though | + | 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 | * Host | ||
Line 36: | Line 37: | ||
|- | |- | ||
| User-Agent | | User-Agent | ||
− | | The name and version of the | + | | 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 | | Date | ||
Line 51: | Line 52: | ||
|- | |- | ||
| Client-ID | | Client-ID | ||
− | | A unique ID for each client instance. In | + | | 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. |
|} | |} | ||
Line 58: | Line 59: | ||
<pre><nowiki> | <pre><nowiki> | ||
{ | { | ||
− | "href": "zmq:// | + | "href": "zmq://zaqar.example.com/v1/queues/my_awesome_queue", |
"action": "get", | "action": "get", | ||
"header": { | "header": { |
Revision as of 23:28, 4 December 2014
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.
Generally, wire transport protocols don't define a high level abstraction on how the packet would look like. Hereby we design our own format, which tries to be as much compliant as possible with the HTTP structure.
We will base our protocol in http://rfc.zeromq.org/spec:33
Serialization
Zaqar's persistent transports will use msgpack as a serialization format.
Structure
{ href: "", action: "", # HTTP verbs accepted 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; Either `application/json` or `application/messagepack`; If none was specified, the later will be used. |
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
{ "href": "zmq://zaqar.example.com/v1/queues/my_awesome_queue", "action": "get", "header": { "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": { ... } }
See msgpack Accept.