Protocol
In order to make understanding the protocol easy, this page will use a format in order to
define packets that will be used by excom. They will follow the following format, where
items encapsulated in <> are to be replaced by a value.
<Packet Description>
Field Type Description <Field 1 Name> <Field 1 Type><Field 1 Description>
The Packet Name is a name given to the packet to describe it. It will be used to refer
to the packet in other packet descriptions. The Packet Type is a number that contains an
identifier corresponding to that packet. It is the number that is sent as a part of the
protocol to notify the other end that the following is the specific packet. The Packet
Direction is the direction that the packet normally travels in. This should be any of
both, client, and server, or none if it's not applicable. The Packet
Description should be a block of text explaining how the packet should be used, and what
the fields mean/do.
The table following that contains a list of the fields within that packet. Each field
should have a name, a type, and a description. The name should be a one- or two- word text
describing the field. The type should be a type that describes the field, which should
correspond to a C type. A type ending in _t is preferred to any other types, i.e.
int32_t should be preferred to int. The only exception to these rules is the type
string, which can be expanded to these types:
| Field | Type | Description |
|---|---|---|
| size | size_t |
The number of characters in this string. |
| body | uint8_t[] |
A set of characters containing the body of the string. |
The description should contain a text describing the field inside the packet.
The Excom protocol is a custom protocol that separates data into packets, which are then set over the network to perform a specific purpose. All network communication should be in network byte order, or Big Endian. If an implementation does not understand a packet, it should be ignored, in order to maintain compatibility. Every packet contains a header, which is defined as the following:
A small header that describes the oncoming packet. Every packet should have this
prefix its body, in order to ensure that the destination understands the packet.
Both ends must read up to size bytes, in order to ensure forward compatibility
with other protocols that implement other fields in packets.
| Field | Type | Description |
|---|---|---|
| size | uint32_t |
A number denoting the size of the following packet. Note: it does not include the header. |
| ID | uint16_t |
A number denoting which packet this is. Each side has a counter starting at zero, and increments the counter every time a packet is sent. This number is set to the value of the counter before it is incremented. So, the first packet sent should have an ID of 0. |
| Type | uint16_t |
The type of packet. It corresponds to the number denoted here after the name of the packet. See the Format section for more information. |
If an error occurred on either side, a rejection packet is sent. On receiving, the connection must be closed, if it hasn't been closed already. On sending, the connection must be closed once the entire packet has been sent. See Reject for more information.
To start the connection, the client must message the server. The client first sends a Protocol version packet to the server. The server checks the packet, and then responds with an Ok packet or a Reject packet. If the server responds with an Ok packet, the encryption handshake can begin.
client --------------- protocol_version --------------> server
client <-------------- ok --------------- server
todo
todo
A response that is normally used to indicate that the sender has processed everything and is ready for more data. Normally, when this is used, a rejection packet could be sent in its place to indicate an error. This packet contains no fields.
| Field | Type | Description |
|---|
A response that indicates an error has occurred, and the connection must be closed. A reject packet can contain a reason, which denotes why it was rejected. A table of possible values is denoted as follows:
| Name | Value | Description |
|---|---|---|
StandardError |
0x00 |
A generic error has occurred. It is bad practice to use this error code; another error code should be used in order to explain the issue better. |
InvalidProtocolError |
0x01 |
The protocol version sent is not compatible with the protocol version that the sender is running. |
Error codes above 0x7f are reserved for private use.
| Field | Type | Description |
|---|---|---|
| reason | uint8_t |
The reason for rejection. This should be any of the values denoted above. |
Similar to Reject, but will not cause the connection to be closed.
| Name | Value | Description |
|---|---|---|
StandardError |
0x00 |
A generic error has occurred. It is bad practice to use this error code; another error code should be used in order to explain the issue better. |
ImproperPermissionsError |
0x01 |
The client tried to perform an operation that it did not have the permission to do. |
| Field | Type | Description |
|---|---|---|
| reason | uint8_t |
The reason for the error. This should be any of the values denoted above. |
The first packet sent by the client, and the packet sent in response by the server.
After that exchange occurs, the server will send an Ok or a
Reject packet depending on if the protocol versions are compatible
with each other. If a Reject packet is sent, it will have the reason
InvalidProtocolError.
| Field | Type | Description |
|---|---|---|
| version | string |
A string of the version, in the form of <major>.<minor>.<patch>. |
| major | uint8_t |
The major version of the protocol implementation. This denotes major changes, many of which are incompatible between differences in this number. If this number is different between each endpoint, the connection must be rejected. |
| minor | uint8_t |
The minor version of the protocol implementation. This denotes small, reverse-compatible changes; if this number is different between each endpoint, the connection may be rejected. |
| patch | uint8_t |
The patch version of the protocol implementation. This denotes patches (or bug fixes). If this number is different between each endpoint, the connection may be rejected. |
A command to run on the server. The exact formatting of the command is up to the server
implementation. If the client does not have the proper permissions to run the command,
an Error packet can be sent with the reason ImproperPermissionsError.
| Field | Type | Description |
|---|---|---|
| command | string |
The command to run on the server. |
The response to the command sent by the client.
| Field | Type | Description |
|---|---|---|
| response | string |
The response to the command that was sent to the server. |