From 4b1d25393c65b02d6d906e78c6c1cc1d4fa1cb70 Mon Sep 17 00:00:00 2001
From: Graham <gpe@openrs2.org>
Date: Sat, 2 Jan 2021 19:55:22 +0000
Subject: [PATCH] Add JS5 protocol documentation

Signed-off-by: Graham <gpe@openrs2.org>
---
 share/doc/protocol/js5.md | 77 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 share/doc/protocol/js5.md

diff --git a/share/doc/protocol/js5.md b/share/doc/protocol/js5.md
new file mode 100644
index 0000000000..7b7ecdb949
--- /dev/null
+++ b/share/doc/protocol/js5.md
@@ -0,0 +1,77 @@
+# JS5 protocol
+
+## Upstream
+
+| Opcode | Description              |
+|-------:|--------------------------|
+|      0 | Request group (prefetch) |
+|      1 | Request group (urgent)   |
+|      2 | Logged in                |
+|      3 | Logged out               |
+|      4 | Rekey                    |
+|      6 | Connected                |
+|      7 | Disconnect               |
+
+All upstream packets are exactly 4 bytes long, including the opcode. Unused
+payload bytes are set to zero.
+
+### Request group (prefetch/urgent)
+
+| Data type     | Description |
+|---------------|-------------|
+| UnsignedByte  | Archive ID  |
+| UnsignedShort | Group ID    |
+
+Requests a group. Urgent requests have a higher priority than prefetch requests,
+as the client needs the group immediately. Prefetch requests are used to
+prepopulate most of the cache in the background.
+
+### Rekey
+
+| Data type     | Description          |
+|---------------|----------------------|
+| UnsignedByte  | Key                  |
+| UnsignedShort | Unused (set to zero) |
+
+Sent to set the encryption key.
+
+### Logged in/out
+
+Sent whenever the player logs in or out of the game. Consensus in the community
+is that the logged in/out state is probably used for prioritisation, much like
+the distinction between prefetch/urgent requests.
+
+### Connected
+
+| Data type      | Description                 |
+|----------------|-----------------------------|
+| UnsignedMedium | Unknown (always set to `3`) |
+
+Sent immediately after the JS5 connection is established. Its purpose is not
+known.
+
+### Disconnect
+
+Requests that the server closes the connection. Sent by the `::serverjs5drop`
+command.
+
+## Downstream
+
+There is only a single type of response packet, and as such, there are no
+response opcodes. The packet contains a group requested by the client.
+
+| Data type      | Description                                               |
+|----------------|-----------------------------------------------------------|
+| UnsignedByte   | Archive ID                                                |
+| UnsignedShort  | Group ID                                                  |
+| UnsignedByte   | Compression type (ORed with `0x80` for prefetch requests) |
+| Int            | Compressed length                                         |
+| Int (optional) | Uncompressed length (present iff the group is compressed) |
+| Byte[]         | Compressed data (with `0xFF` markers, see below)          |
+
+If encryption is enabled, all downstream bytes are XORed with the encryption
+key. The client enables encryption if the checksum of a group does not match the
+expected checksum in the master index or index.
+
+After the first 512 bytes of a response, every subsequent block of 511 bytes is
+prefixed with a single `0xFF` byte.