diff options
Diffstat (limited to 'docs/protocol.rst')
| -rw-r--r-- | docs/protocol.rst | 99 |
1 files changed, 99 insertions, 0 deletions
diff --git a/docs/protocol.rst b/docs/protocol.rst new file mode 100644 index 0000000..48dcacc --- /dev/null +++ b/docs/protocol.rst | |||
| @@ -0,0 +1,99 @@ | |||
| 1 | EventMQ Protocol Specification | ||
| 2 | ============================== | ||
| 3 | *The status of this document is alpha and subject to heavy change* | ||
| 4 | |||
| 5 | Goals | ||
| 6 | ===== | ||
| 7 | The EventMQ Protocol (eMQP) defines a reliable service-oriented request-reply and pub-sub dialog between a set of clients, a broker, and a set of workers. This goal is to | ||
| 8 | |||
| 9 | The goals are to: | ||
| 10 | |||
| 11 | * Specify a protocol to follow when implementing a component to EventMQ. | ||
| 12 | * Allow requests to be routed to workers by an abstracted service name. | ||
| 13 | * Detect disconnected peers through heartbeating. | ||
| 14 | * Allow for message tracing and debugging. | ||
| 15 | |||
| 16 | |||
| 17 | License | ||
| 18 | ======= | ||
| 19 | This Specification is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. | ||
| 20 | |||
| 21 | This Specification is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. | ||
| 22 | |||
| 23 | Language | ||
| 24 | ======== | ||
| 25 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119[[1](http://tools.ietf.org/html/rfc2119)]. | ||
| 26 | |||
| 27 | Architecture | ||
| 28 | ============ | ||
| 29 | insert pretty picture here | ||
| 30 | |||
| 31 | Topology | ||
| 32 | -------- | ||
| 33 | eMQP connects a set of client applications (e.g. web servers), a broker, and a pool of workers. Clients connect to the broker as well as the workers. | ||
| 34 | |||
| 35 | 'Clients' is defined as application issuing requests and 'workers' as applications that process these requests. (Workers consist of a `JobManager` and a pool of `Worker` resources where the job executes.) | ||
| 36 | |||
| 37 | The EventMQ broker handles a set of named queues. The broker SHOULD serve clients on a fair request and MAY deliver requests to workers on any basis, including 0MQ's built-in round robin or least-recently used. | ||
| 38 | |||
| 39 | ROUTER Addressing | ||
| 40 | ----------------- | ||
| 41 | In the case of request-reply, the broker MUST use a ROUTER socket to accept requests from both clients and workers. The broker MAY use a seperate socket implementing a subset of eMQP, or MAY use a single socket implementing all of eMQP. | ||
| 42 | |||
| 43 | From the 0MQ manual[[2](http://api.zeromq.org/master:zmq-socket)] | ||
| 44 | > When receiving messages a ROUTER socket shall prepend a message part containing the identity of the originating peer to the message before passing it to the application. When sending messages a ROUTER socket shall remove the first part of the message and use it to determine the identity of the peer the message shall be routed to. | ||
| 45 | |||
| 46 | This extra frame is not shown in the specifications below. | ||
| 47 | |||
| 48 | eMQP / Client | ||
| 49 | ------------- | ||
| 50 | A **REQUEST** command consists of 7-frame multipart message, formatted as follows. | ||
| 51 | |||
| 52 | ====== ============== =========== | ||
| 53 | FRAME Value Description | ||
| 54 | ====== ============== =========== | ||
| 55 | 0 _EMPTY_ leave empty | ||
| 56 | 1 eMQP/1.0 Protocol version | ||
| 57 | 2 READY Command | ||
| 58 | 3 _MSGID_ A unique id for the msg | ||
| 59 | 4 _QUEUE_NAME_ the name of the queue the worker belongs to | ||
| 60 | 5 _HEADERS_ dictionary of headers. can be an empty set | ||
| 61 | 6 _MSG_ The message to send | ||
| 62 | ====== ============== =========== | ||
| 63 | |||
| 64 | eMQP / Worker | ||
| 65 | ------------- | ||
| 66 | An **INFORM** command consists of a 5-frame multipart message, formatted as follows. | ||
| 67 | |||
| 68 | ====== ============== =========== | ||
| 69 | FRAME Value Description | ||
| 70 | ====== ============== =========== | ||
| 71 | 0 _EMPTY_ leave empty | ||
| 72 | 1 eMQP/1.0 Protocol version | ||
| 73 | 2 INFORM | ||
| 74 | 3 _MSGID_ A unique id for the msg | ||
| 75 | 4 _QUEUE_NAME_ the name of the queue the worker belongs to | ||
| 76 | ====== ============== =========== | ||
| 77 | |||
| 78 | A **READY** frame consists of a 4-frame multipart message, formatted as follows. | ||
| 79 | |||
| 80 | ====== ============== =========== | ||
| 81 | FRAME Value Description | ||
| 82 | ====== ============== =========== | ||
| 83 | 0 _EMPTY_ leave empty | ||
| 84 | 1 eMQP/1.0 Protocol version | ||
| 85 | 2 READY | ||
| 86 | 3 _MSGID_ A unique id for the msg | ||
| 87 | ====== ============== =========== | ||
| 88 | |||
| 89 | A **REPLY** frame consists of a 5-frame multipart message, formatted as follows. | ||
| 90 | |||
| 91 | ====== ============== =========== | ||
| 92 | FRAME Value Description | ||
| 93 | ====== ============== =========== | ||
| 94 | 0 _EMPTY_ leave empty | ||
| 95 | 1 eMQP/1.0 Protocol version | ||
| 96 | 2 REPLY | ||
| 97 | 3 _MSGID_ A unique id for the msg | ||
| 98 | 4 _MSG_ The reply to respond with | ||
| 99 | ====== ============== =========== | ||