1 files changed, 59 insertions, 0 deletions
diff --git a/internal/server/protocol.txt b/internal/server/protocol.txt
new file mode 100644
index 0000000..9a0070d
--- /dev/null
+++ b/internal/server/protocol.txt
@@ -0,0 +1,59 @@
+# Eko Protocol V1
+
+## Packet Structure
+
+ 0                   1                   2                   3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|    Version    |En.|    Type   |         Payload Length        |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|              Payload... Payload Length bytes ...              |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+Order of bytes is from left to right, top to bottom.
+The first byte is always the version, any bytes after it
+depend on the specific value of the first byte.
+
+- Encoding: 0-3, determines the way the payload was encoded
+  - 0: JSON
+  - 1: MsgPack
+  - 2: Reserved for future use
+  - 3: Reserved for future use
+- Type: 0-63, determines the type ("schema"), of the payload
+- Payload Length: 0-65531, determines how long the payload is in bytes
+- Payload: 0 to 65531 bytes long, depending on the payload size (~64kb)
+
+## Handshake
+
+The first time a connection is established, the following packets are exchanged.
+
+- Server sends a special 1-byte for version then 32-byte the challenge nonce packet
+- Client sends a Challenge Response packet with:
+  * version (1-byte long)
+  - the client's ed25519 public key (32-bytes long)
+  - the client's ed25519 signature for the server-given nonce (64-bytes long)
+
+After the handshake the server may close the connection,
+for example due to an invalid signature.
+
+## Error handling
+
+The server may abruptly close a connection in these cases:
+
+- After the initial handshake
+- After any response
+  A server may not close the connection if it received a request, it must first response then close.
+
+The client may abruptly close a connection at any time
+
+### Malformed Packets
+
+- unsupported/invalid version: connection can be closed immediately
+- unsupported encoding: server must respond with an error type, may use any encoding, client may close the connection
+- unknown type: server must respond with an error, client may close the connection
+- malformed paylod: server must respond with an error, client may close the connection
+
+For application errors such as a client asking to send a message in a non-existent Frequency,
+the server must respond with an error packet.
+For internal errors such as database failure, the server must respond, it may choose to
+disclose as much information as it wants, or just say "internal server error".