# Protocol #

[Communication protocol proposal. Not yet fully implemented and expected to change.]

Nodes communicate by exchanging messages through network sockets. Basic message format is simple:

		json-length: ABC
		bin-length: DEF
		{... JSON payload ...}
		... binary payload ...

`ABC` is the JSON payload length (decimal integer), `DEF` is the binary payload length. JSON payload always contains a "command" field.

The client sends a request (a message) and the server answers with a response (another message).


## Commands ##
### <a name="init"></a>init ###
Initiates communication between the client and the server. Checks that the nodes can meaningfully talk to each other.

#### Params ####
- (str) version: program version. Both the client and the server are to check for compatibility with their partner.
- {push, pull} action: what the client desires to do
- (str) filename: name of the file to be synchronized
- (int) blockSize
- (int) blockCount

#### Responses ####
- [init](#r-init)
- [deny](#deny)


### <a name="req"></a>req ###
Requests hashes or a data chunk from the server.

#### Params ####
- {hash, data} dataType

hash
- [(int) i0, ...] index: list of requested node keys from the HashTree

data
- (int) index: requested data block number in the data file. Returns blockSize bytes starting at blockSize * index.

#### Responses ####
- [send](#send)
- [err](#err)


### <a name="send"></a>send ####
Sends data. Can be a client action or a response to a request.

#### Params ####
- {hash, data} dataType
- index: see [req](#req)

#### Responses ####
- [ack](#ack)
- [err](#err)


### <a name="end"></a>end ###
Cease talking and close the connection.

#### Params ####
- {push} (optional) action: unlocks the server's dirty lock

#### Responses ####
- end


## Responses ##
### <a name="r-init"></a>init ###
See [the init command](#init). If the client doesn't like server's protocol version, it is free to [end](#end) the connection.

#### Params ####
- (str) version


### <a name="deny"></a>deny ###
The server refuses connection. It might be busy, corrupted or incompatible.

#### Params ####
- (int) retry: suggested delay in seconds before another attempt at connection
- (str) msg


### <a name="ack"></a>ack ###
Everything is alright, but the server has nothing better to say.


### <a name="err"></a>err ###
Something bad happened.

#### Params ####
- (str) msg