This document describes the Sink protocol. It is a work in progress.
When a client connects to a server it sends a connection request to tell the server some attributes about itself. This is to ensure that the client and server are compatible and are who each other expects.
The attributes are:
- protocol version - the version of Sink the client is requesting to use
- client_instance_id - the instance_id of the client itself
- server_instance_id - the server_instance_id of the last successful connection if there has been one
- application_version - the application version running on the client
The instance_ids are intended to prevent devices who may authenticate fine, but had been connected to different instances before. For example, if a device used to connect to a staging environment also has somehow has credentials in production or if a device was wiped and no longer has the same history the server expects.
The server responds to a client's connection with one of the following responses:
The server agrees that the client is who the server expects and the server is who the client expected.
The server has accepted the new client's connection and is telling the client
its instance_id value.
The client and server's instance_ids did not match up. The connection will close.
The client has been quarantined and the connection will close. The client may retry at a later point.
The client requested to use a protocol version the server does not support. The connection will close.
The client is running an outdated or otherwise unsupported version the server does not support. The connection will close. The client should update and then try again.
Send a single event.
Triggers an ACK or NACK response on the peer.
Acknowledge a single event.
An ACK means an event was received and processed as expected and the subscription can consider the event delivered.
Report a problem with a single event.
A NACK should be considered to be an exceptional state and contains information about why the event was NACK'd. There is a field for a "machine message", which is meant to be a machine readable binary message, like a http status, determined by the implementer. The purpose is to have known error codes which might have a recovery path (ex: upgrading a device's firmware). There is also a field for a "human message", which is meant to be a human friendly description of the error and may be blank if bandwidth usage is a concern.
Request a pong from a peer.
Respond to a pong from a peer.