Map Proxy

A server that acts as a proxy to allow easy communication between clients.

Running

• Install node.js
• Download latest map-proxy $ npm install -g map-proxy
• Run $ map-proxy
  • Run on an alternate port $ map-proxy --port 2345 $ map-proxy 2345

Writing clients

Map Proxy provides a TCP server. Data sent to the server is forwarded almost directly to all clients. All data is UTF-8 encoded.

All clients are assigned an RFC4122 v4 UUID, generated by uuid.

Map Proxy expects the first data sent is the name of a data notation (e.g. JSON). These are the supported data types, along with the parsers used:

• json
  • uses V8's JSON.parse() and JSON.stringify()
• yaml
  • uses js-yaml (safeLoad and safeDump)

After that, all data sent should be parseable by the respective parser, otherwise you will get an error sent back and no-one else will know. Usually, this means that you should just use a parser/serializer that just conforms to the same standard.

When Map Proxy recieves data, if it is a map, it first checks if there is a "cmd" key, and if the corresponding value is "quit". It will then tell everyone else that this client wants to quit, and the connection is closed.

Next, Map Proxy checks if "cmd" is "deny". If it is, then it also expects to be passed an "id" key, with the UUID of another client. Map Proxy will register the current client as having wanted to kick the given client. If more than half of the clients want to kick a client, said client will be kicked.

Next, "cmd": "list". This returns a list of UUID's representing all the clients.

Failing all these, Map Proxy tries to set the "from" attribute on the sent data. Note that this will have pretty much no effect unless the sent data is a map. The "from" attribute will contain the UUID of the sending client. Then, the data is re-serialized according to the preferences of each client, and sent along.

An optional "to" key can be used to specify the UUIDs of clients to restrict the forwarding to. If given a list, data will only be forwarded to those clients. If given a string, only to that client.

Example session

< yaml
> cmd: welcome
  id: 35dac294-e36e-4efb-a74c-88b864ef6387
< cmd: list peers
> cmd: RES:list peers
  peers:
    - e7b25b29-62ed-4bca-821b-8066765c32de
    - 65537abc-0b17-4e03-88cc-29945b65c6ce
    - 0f0c71b5-ee3b-4b48-971c-da6e580382d9
> cmd: peer connected
  id: 6666762c-00ac-495e-a83f-96d1437449ff
< cmd: deny
  id: 6666762c-00ac-495e-a83f-96d1437449ff
> cmd: RES:deny
  success: true
  denied: 2
< cmd: deny
  id: 6666762c-00ac-495e-a83f-96d1437449ff
> cmd: ERROR
  type: redundant
  info: already denied
  message: You have already denied the connection of 6666762c-00ac-495e-a83f-96d1437449ff
> cmd: peer left
  id: 6666762c-00ac-495e-a83f-96d1437449ff
  why: denied
  by:
    - e7b25b29-62ed-4bca-821b-8066765c32de
    - 35dac294-e36e-4efb-a74c-88b864ef6387
    - 65537abc-0b17-4e03-88cc-29945b65c6ce
> cmd: peer left
  id: 0f0c71b5-ee3b-4b48-971c-da6e580382d9
  why: client request
< cmd: quit
> cmd: end
  why: client request

Explained:

• When we connect, we tell the server that we want to talk in YAML.
• The server sends the welcome command, telling us our UUID.
• We ask who is connected with list peers.
• The server responds with a RES:list peers.
• The server informs us that another peer has connected with peer connected.
• We don't like this guy, so we send a deny
• The server acknowledges our request with a RES:deny. It also informs us that 2 people including us have denied this client.
  • Note that, if we were the deciding vote in the deny, then we will see the disconnect message before the RES:deny.
• We REALLY don't like this guy, so we send another deny.
• The server replies with an ERROR, because we have already denied this guy.
• The server sends a peer left, informing us that 3 people have denied him.
• The server sends a peer left with why: client request informing us that some guy left on his own.
• We send a quit to tell the server we are done, and to clean everything up nicely.
• The server sends an end and closes the pipe.

If you want, the same session in JSON:

< json
> { "cmd": "welcome",
    "id":"35dac294-e36e-4efb-a74c-88b864ef6387" }
< { "cmd": "list peers" }
> { "cmd": "RES:list peers",
    "peers": [
        "e7b25b29-62ed-4bca-821b-8066765c32de",
        "65537abc-0b17-4e03-88cc-29945b65c6ce",
        "0f0c71b5-ee3b-4b48-971c-da6e580382d9"
    ] }
> { "cmd": "peer connected",
    "id": "6666762c-00ac-495e-a83f-96d1437449ff" }
< { "cmd": "deny",
    "id": "6666762c-00ac-495e-a83f-96d1437449ff" }
> { "cmd": "RES:deny",
    "success": true,
    "denied": 2 }
< { "cmd": "deny",
    "id": "6666762c-00ac-495e-a83f-96d1437449ff" }
> { "cmd": "ERROR"
    "type": "redundant",
    "info": "already denied",
    "message": "You have already denied the connection of 6666762c-00ac-495e-a83f-96d1437449ff" }
> { "cmd": "peer left",
    "id": "6666762c-00ac-495e-a83f-96d1437449ff",
    "why": "denied",
    "by": [
        "e7b25b29-62ed-4bca-821b-8066765c32de",
        "35dac294-e36e-4efb-a74c-88b864ef6387",
        "65537abc-0b17-4e03-88cc-29945b65c6ce"
    ] }
> { "cmd": "peer left",
    "id": "0f0c71b5-ee3b-4b48-971c-da6e580382d9",
    "why": "client request" }
< { "cmd": "quit" }
> { "cmd": "end",
    "why": "client request" }