besterd/spec3.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 (`v3`)

When a host connects to a bester daemon it must send the
following stanza:

````
{
	"header" : {
		"identify" : {
			"type" : "<type>",
			...
		}
	}
}
````

Where `<type>` is either `server` or `client`.

If `<type>` is set to `client` then the `...` field must
be a block named `"authentication"` and look as follows:

````
"authentication" : {
	"username" : "<username>",
	"password" : "<password>",
}
````

Where 

## Flow

### Client and Server

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

<hr>

#### 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.

*TODO*

<hr>

#### 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 a JSON type up to
the _message handler_ and *SHOULD* be interpreted in accordance to
its (the _message handler_'s) rules.


#### Server and Message Handler

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

<hr>

#### 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