besterd/spec2.md

Spec v2

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)

Flow

Client

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? * 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"
		}
	},
	"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 [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.

TODO

---

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"
	},
	"data" : ...
}

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 data which is of aa JSON type up to the message handler and SHOULD be interpreted in accordance to its (the message handler's) rules.