# 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