Max Client-Server Protocol Specification (Draft)

(This document is meant to be updated in sync with the implementation.)

Max uses a client/server architecture so the world keeps running when clients disconnect.
A server may be run on the same machine as the client.

The protocol is built on top of ZeroMQ 4.

There are two connections between each client and the server: A PUB-SUB for world updates and a DEALER-ROUTER
for the client to send requests and receive responses.  Both connections are currently TCP, because during prototyping,
the dependency on libpgm and getting multicast working was problematic and unnecessary.

Command channel: Dealer-Router 

The client connects and sends a "getWorldState" message.
- The server responds with the state of the world.
  Haskell serialized value of type [SceneObject], defined in lib/Max.hs

The client and server enter a loop where client sends a request
and the server responds. If the request is to modify the world,
the response will simply be a success or failure response, with any
changes to the world being sent to all clients on the PUB-SUB channel.

The first ZMQ message part of any request is the command name (String)
marshalled using "pack" from the bytestring package (Data.ByteString.Char8 module) 
and then by "encode" from the cereal package (Data.Serialize module),
and depending on the command name, there may be other ZMQ message parts, as arguments.

"tryToggle" message: takes one parameter (message part): an Integer (bignum)
Request Scene index of the switch to toggle.
Server returns True if succeeded and False if not.

"tryAddObject" message: takes one parameter: the SceneObject to add, which already contains
a WorldObject and a Position.
Server returns True if succeeded and False if not.

World Update channel: Pub-Sub

The world is persistent.  The client may reconnect. If the client disconnects, the server will treat it as a new client
and start it at the origin.  It is assumed the client will connect to the world updates channel before it makes changes to the
world on the command channel, and therefore already synchronized.

"toggled" message: one parameter, the Integer (bignum) of which object has been toggled.

"addedObject" message: one parameter, the SceneObject to add