6.2 KiB
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?
- The client
- The client connects to the server and sends commands to it.
- 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.
- 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
andpayload
which MUST be JSON objects. - The
header
field MUST contain a field namedauthentication
which MUST be a JSON object and must contain two fields,username
andpassword
, which MUST be JSON strings. Theheader
field MUST also contain a field namedscope
which MUST be a JSON string (and in this case must be equal to"client"
). - The
[JSON message]
MUST contain a field namedpayload
which MUST be a JSON object and MUST contain two fields,type
anddata
, wheretype
MUST be a JSON string anddata
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 calledstatus
which is a JSON string and SHOULD be interpreted as such. - There is a field called
payload
which MUST contain two fields,data
andtype
. - 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