Document the new wire protocol

[JensRantil]

According to #33 544f1a700ffaf7a6592ac4676f9b14c065f9adaa introduced a new wire protocol. Eventually this new protocol will need to be documented.

I propose this issue could be a good place to collect references to commits that changed the API. This is what I've found:

• 544f1a700ffaf7a6592ac4676f9b14c065f9adaa
• 5442f46c270685e72f39d09ba453d800ee5eadef

Obviously, you may close this issue if you think it's a "non-issue".

[hintjens]

The 0.2 protocol definitely needs to be updated to match the code and/or vice versa. Martin Hurton made the changes to the Majordomo code but I've not had opportunity to update the specs. Here are his notes on what changed:

Goals: Not sure we can still use the adjective reliable. MDP does not support "request-reply processing" anymore. MDP/0.3 replaces PARTIAL and FINAL with REPORT message. MDP/0.3 no longer allows "the broker to recover from dead or disconnected workers by resending requests to other workers". Once the broker has forwarded the command, there is no way to know whether it has been processed.

Overall topology:

• "Clients and workers do not see each other, and both can come and go arbitrarily" no longer is true. The reason is the broker does not handle disconnected workers.
• "Workers will handle at most one request a time, and will issue exactly one reply for each successful request." This is no longer true. As we the broker cannot detect busy worker, it may happen that broker receives another request before finishing the previous one.
• "The Majordomo broker handles a set of shared request queues, one per service. Each queue has multiple writers (clients) and multiple readers (workers)" - not true anymore, the broker just forwards message as soon as it arrives

MDP/Client

• "MDP/Client is a strictly synchronous dialog initiated by the client (where 'C' represents the client, and 'B' represents the broker)" - protocol is asynchronous now

MDP/Worker

• "MDP/Worker is a mix of a synchronous request-reply dialog, initiated by the service worker, and an asynchronous heartbeat dialog that operates independently in both directions" - MDP/WOrker is fully asynchronous now

Reliability

• Worker applications which crash, run too slowly, or freeze - the broker can detect those conditions but cannot resend command to other worker