Protocol

Requirements

Clipsie’s wire protocol should be simple, compact, and self contained (e.g. you should never have to read some data, decode a JSON object, and look at one of its properties to know how much more data to read off the socket).

Versioning

First, the peers agree on a protocol version. The client who initiates the connection must start by sending one byte representing the highest protocol version it supports. The first version is 0. The peer must respond with the version to be used for the session, which must be equal to or less than the version number it received.

v0

A message is an ordered series of frames. A frames contains bytes. If a frame represents text, the text should be encoded as UTF-8.

A message starts with one byte representing the number of frames to follow. Each frame is a 64-bit number in network order representing the length of the data in the frame, followed by the data. That's it.

The first version of Clipsie only supports sending text. A text offer is two frames:

1. The string textoffer
2. The text

After the text offer has been completely sent the sender must close the socket.

v1

Same wire protocol as v0 but supports sending files too. A file offer is three frames:

1. The string fileoffer
2. The filename
3. The file data

The receiving client should feel free to pause receiving the file data (after receiving the filename and file data length) if it wishes to ask the user to confirm that they want the file; it may make more sense to just start saving the data somewhere though. The sending client may time out the connection, but the timeout should be long enough to support this kind of user interaction (e.g. several minutes).

If the receiver doesn't want the rest of the file for any reason (user cancelled the transfer, there isn't enough disk space, etc.) it should feel free to close the connection at any time. The sender must handle this gracefully. Otherwise, when the message has been completely sent the sender must close the socket.