Websocket Wire Format

All encoding is done using msgpack with lists as the base structure that have a string type as the first element. Websockets with a binary message payload a re used. Message delivery follows a pub/sub pattern.

Motivation and Goals

• Keep local data local if possible (e.g., glass -> phone shouldn’t need to go through a server if they are connected)
• Pub/Sub over Point-to-Point: Focusing on channels which represent data types naturally handles 0-to-many devices reacting to it.
• Minimize data transfer, if nothing is listening on a channel then sending to it is a null-op
• Support a directed-acyclic-graph topology, where local devices can act as hubs (e.g., a phone is a hub for a watch, Glass, and arduino) and connect to other hubs (e.g., a remote server)
• Instead of having strict guarantees about delivery, provide a set of constraints that can be met given the fickle nature of mobile connectivity to eliminate edge cases

Protocol Rules

• Messages are delivered with “best effort” but not guaranteed: devices can pop in and out of existance and buffers are not infinite
• If a sender’s messages are delivered they are in order
• A message SHOULD only be sent to a client that is subscribed to it or is connected to clients that are
• A message sent to a client that neither it or its clients are subscribed to MUST ignore it
• The “subscriptions” channel is special in that it MUST be sent to all connected clients
• When a client connects to a server it MUST be send the subscriptions for itself and all other clients
• If multiple channels match for a client the most specific MUST be called and no others
• When a client subscribes to a channel a single callback MUST be provided

The following table gives examples for when data will be sent given that there is a listener for the specified channel.

sub	send	sent
“”	a	false
“”	“”	true
a	a	true
a	a:b	true
b	a:b	false
a:	a	false
a:	a:b	false
a:	a::b	true
a:b	a	false
a:b	a:b	true
a:b	a:bc	false
a:b	a:b:c	true