CCats/Client-Server Protocol.md

Client-Server Protocol

Protocol version: "0.2"

Every json message must be minimized and be followed by a newline. This rule makes receiving and parsing the messages easier because you can read until a newline comes and you will parse every json message seperately because you won't read multiple json messages from the buffer at a time.

1. Start a connection

To start a connection you have to check the versions and verify the login or signup. Only if step 1.1 and 1.2 have been accomplished a usable connection is negotiated. You can close the connection by sending a cancel message.

1.1 Version check

Client:

{
	"version": string
}

Server:

{
	"version": string,
	"accept": bool
}

If accept is true the connection is valid. Else the connection will be terminated after the server answered.

1.2 Login / Signup

The client is supposed to always send every field used for the login requests: login, user, pass and cancel. The server is supposed to always send every field used for the login answer: accept and error.

1.2.1 Login

Client:

{
	"login": true,
	"user": string,
	"pass": string,
	"cancel": false
}

Server:

{
	"accept": bool,
	"error": string
}

If accept is true the connection is valid and the user is logged in. Else error has an error string and the connection will be terminated after the server answered.

1.2.2 Signup

Client:

{
	"login": false,
	"user": string,
	"pass": string,
	"cancel": false
}

Server:

{
	"accept": bool,
	"error": string
}

If accept is true the connection is valid and the user is logged in and signed up. Else error has an error string and the connection will be terminated after the server answered.

1.2.3 Cancel login

Client:

{
	"login": bool,
	"user": string,
	"pass": string,
	"cancel": true
}

After the cancel message was sent the connection will be closed.

2. Sending commands

Commands can be sent by the client after a connection has been negotiated (See 1). Commands can be used unrelated to each other.

2.1 Status command

Client:

{
	"command": "status"
}

Server:

{
	"command": "status",
	"response": string
}

2.2 List command

List is split in two commands. list to request a list download and listdata to download the list.

2.2.1 list - request file list download

Client:

{
	"command": "list"
}

Server:

{
	"command": "list",
	"accept": bool,
	"items": int,
	"chunks": int,
	"error": string
}

2.2.2 listdata - download file list

Client:

{
	"command": "listdata",
	"chunk": int,
	"cancel": bool
}

Server:

{
	"command": "listdata",
	"remaining": int,
	"cancel": bool,
	"names": string[],
	"error": string
}

The client has to request every chunk until all names have been sent and remaining hits 0.

2.3 Put command

Put is split in two commands. put to request a file upload and putdata to upload the data.

2.3.1 put - request upload

Client:

{
	"command": "put",
	"file": string,
	"size": int,
	"chunks": int
}

Server:

{
	"command": "put",
	"file": string,
	"accept": bool,
	"error": string
}

If accept is true the connection is valid and the client can start sending the file. Else the put request was rejected and is hereby canceled. error should contain an error string if the request was rejected.

2.3.2 putdata - upload data

Client:

{
	"command": "putdata",
	"file": string,
	"data": string,
	"remaining": int,
	"cancel": bool
}

data is a base64 string and contains a piece of the file. The client will loop this until the file is completely sent and the server has to send and received message for every chunk. remaining is a counter how many chunks will follow and the transfer is over after it hits 0. If cancel is true the file transfer will be canceled.

Server:

{
	"command": "putdata",
	"file": string,
	"recieved": int,
	"cancel": bool,
	"error": string
}

If cancel is true then the upload of the file is canceled and an error message should be in error.

2.4 Get command

Get is split in two commands. get to request a file download and getdata to download the data.

2.4.1 get - request download

Client:

{
	"command": "get",
	"file": string
}

Server:

{
	"command": "get",
	"file": string,
	"accept": bool,
	"chunks": int,
	"error": string
}

If accept is true the connection is valid and the server can start sending the file. Else the get request was rejected and is hereby canceled. error should contain an error string if the request was rejected. chunks is the number of chunks of the file.

2.4.2 getdata - download data

Client:

{
	"command": "getdata",
	"file": string,
	"chunk": int,
	"cancel": bool
}

If cancel is true then cancel the download of the file.

Server:

{
	"command": "getdata",
	"file": string,
	"data": string,
	"remaining": int,
	"cancel": bool,
	"error": string
}

data is a base64 string and contains a piece of the file. The client must request every chunk. remaining is a counter how many chunks will follow and the transfer is over after it hits 0. If cancel is true then the download of the file is canceled and an error message should be in error.

TODO

3. Close connection

3.1 Close command

Client:

{
	"command": "close"
}

Server:

{
	"command": "close",
	"response": "bye"
}