vail

protocol.md

  1The Vail Protocol
  2=============
  3
  4Vail uses [WebSockets](https://en.wikipedia.org/wiki/WebSocket) at https://vail.woozle.org/chat?repeater=Foo. It accepts two subprotocols: both of these provide the same message information, in different encodings.
  5
  6The server will accept packets in either format, but will only send packets in the format described by the subprotocol.
  7
  8Go Definition
  9--------------------
 10
 11```go
 12type Message struct {
 13	// Timestamp of this message. Milliseconds since epoch.
 14	Timestamp int64
 15
 16	// Number of connected clients.
 17	Clients uint16
 18
 19	// Message timing in milliseconds.
 20	// Timings alternate between tone and silence.
 21	// For example, `A` could be sent as [80, 80, 240]
 22	Duration []uint16
 23}
 24```
 25
 26# JSON: `json.vail.woozle.org`
 27-------
 28
 29JSON-encoded Vail messages are a direct encoding of the struct:
 30
 31```json
 32{
 33    "Timestamp": 1702846980,
 34    "Clients": 2,
 35    "Duration": [80, 80, 240]
 36}
 37```
 38
 39This represents a transmission at Sun 17 Dec 2023 09:03:00 PM UTC, consisting of an 80ms tone, an 80ms silence, and a 240ms tone.
 402 clients were connectd to the repeater at this time.
 41
 42
 43Binary: `binary.vail.woozle.org`
 44---------------------
 45
 46The binary marshalled version of a Vail message is encoded big-endian:
 47
 48    00 00 00 00 65 7f 62 04   00 02 00 50 00 50 00 f0
 49
 50Is decoded as:
 51
 52* Timestamp (int64): `00 00 00 00 65 7f 62 04` = 1702846980
 53* Clients (uint16): `00 02` = 02
 54* Duration ([]uint16):
 55  * `00 50` = 80
 56  * `00 50` = 80
 57  * `00 f0` = 240
 58
 59This represents a transmission at Sun 17 Dec 2023 09:03:00 PM UTC, consisting of an 80ms tone, an 80ms silence, and a 240ms tone.
 60
 61
 62WebSockets
 63==========
 64
 65The reference Vail server accepts WebSockets communications to the path `/chat`,
 66with the channel sent as the 'repeater' query parameter.
 67
 68For instance, the "Example" channel is
 69wss://vail.woozle.org/chat?repeater=Example
 70
 71The WebSockets subprotocol may be either:
 72
 73* `json.vail.woozle.org` for JSON packets
 74* `binary.vail.woozle.org` for binary marshalled packets
 75
 76
 77Practical Considerations
 78==================
 79
 80I am a network protocol designer:
 81Vail was designed to contend with
 82Internet latency and jitter.
 83It relies heavily on an accurate Real-Time Clock on each client.
 84
 85Playback Delay
 86------------------
 87
 88Clients should implement a delay on playback of all recieved messages,
 89to allow for network latency and jitter.
 90
 91I have found that a 2-second delay is usually enough, but people on very high-latency links may need a larger delay.
 92
 93If the timestamp + delay on a recieved packet is after the current time of day,
 94it may be appropriate to increase the delay.
 95
 96Clock skew
 97---------------
 98
 99On connecting,
100clients will recieve a packet with no Durations.
101Clients should use this timestamp
102to estimate skew between the client and server's clock.