besterd/specification.md

Bester protocol - Specification

This document aims to provide a detailed description of the Bester protocol. It provides information on the terminology used as well as the flow of data.

What does it entail?

1. The client
   • The client connects to the server and sends commands to it.
2. The server
   • The server receives commands from the client and dispatches them to the respective message handler, waits for a reply and then either sends the reply to a client (originator or otherwise) or another server.
3. The message handler
   • Receives commands from the client indirectly (via the server), processes them and then sends a response back to the server (as implied above, who the reply is sent to is decided by the message handler and the server will act accordingly)

Protocol flow

Client and Server

Describes client-to-server and server-to-client communications.

---

Client -> Server

If a client wants to send a command through to the server then the following bytes must be sent:

[ 4 bytes (size - little endian)][JSON message]

The [JSON message] contains information that the server will use to gain the following information:

* *Authentication*: Is the user allowed to use this server?
* *Scope*: Is this a client-to-server of server-to-server
	communication?
* *Type*: Which _message handler_ should be responsible for
	processing this message.
* *Payload*: The data to be processed by the _message handler_.

The structure of the [JSON message] is as follows:

{
	"header" : {
		"authentication" : {
			"username" : "username",
			"password" : "password"
		},
		"scope" : "client"
	},
	"payload" : {
		"type" : "type",
		"data" : ...
	}
}

• The [JSON message] MUST contain two fields, header and payload which MUST be JSON objects.
• The header field MUST contain a field named authentication which MUST be a JSON object and must contain two fields, username and password, which MUST be JSON strings. The header field MUST also contain a field named scope which MUST be a JSON string (and in this case must be equal to "client").
• The [JSON message] MUST contain a field named payload which MUST be a JSON object and MUST contain two fields, type and data, where type MUST be a JSON string and data can be any JSON type.

Note on authentication

It should be noted that the authentication block need only be transmitted the as the first message sent to the server (as to authenticate the user's self), after this it is never checked and can contain bogus data or be omitted entirely.

Authentication is not required when the scope field is set to "server" as then the communication is server-to-server and not client-to-server.

---

Client <- Server

If a server wants to reply to a client (that just sent a message to it) then the following bytes must be sent to the client:

[ 4 bytes (size - little endian)][JSON message]

The [JSON message] contains information that the client will use to gain the following information:

* *Status*: Did the command sent prior to this response
	run successfully?
* *Payload*: The data to be processed by the _client_.

The structure of the [JSON message] is as follows:

{
	"header" : {
		"status" : "status"
	},
	"payload" : {
		"data" : ...,
		"type" : "<type/handlerName>"
	}
}

The interpretation of the entirety of the [JSON message] is up to the client but the client SHOULD expect and interpret as follows:

• There is a field called header which is a JSON object and SHOULD be inetrpreted as such. Within it there is a field called status which is a JSON string and SHOULD be interpreted as such.
• There is a field called payload which MUST contain two fields, data and type.
• The data field is of a JSON type up to the message handler and SHOULD be interpreted in accordance to its (the message handler's) rules.
• The type field MUST be a string an will contain the name of the message handler that generated this response.

Server and Message Handler

Describes server-to-message-handler and message-handler-to-server communications.

---

Server -> Message Handler

If the server receives a message from the client and then checks the type field of the message as to determine what handler should run it, then the server will send the payload to the handler in the following format:

[4 bytes (size - little endian)][JSON message]

The [JSON message] contains the following information:

• The data field which indicates the payload to be sent to the handler.

There is not format really. The server get's a JSON payload as described in the [Client -> Server] section and all it does it extracts the JSON object at the field data, this then becomes the [JSON message] here and is then sent to the message handler as is.

---

Message Handler -> Server

If a message handler sends a reply back to the server then the following bytes should be sent to the server:

[ 4 bytes (size - little endian)][JSON message]

The [JSON message] contains information that the server will use to gain the following information:

* *Status*: Did the command sent prior to this response
	run successfully?
* *Command*: To tell the server what to do with the response.
* *Payload*: The data to be processed by the _server_.

The structure of the [JSON message] is as follows:

{
	"header" : {
		"status" : "status",
		"command" : "command",
		"commandData" : ...
	},
	"payload" : {
		"type" : "",
		"data" : ...
	}
}

Allowed values for command are:

1. `"sendClients"`: The generated response must be sent to a client(s)
	attached to the local server.
2. `"sendServers"`: The generated response must be sent to a remote
	server(s).

The above two tell the server where to send the response from the message handler to. Either it can be sent

The interpretation of the entirety of the [JSON message] is up to the client but the client SHOULD expect and interpret as follows:

• There is a field called header which is a JSON object and

TODO: Built in server commands

TODO: Authentication for users should be a command.

logout, authenticate, change password