stadium-proto/HANDSHAKE.md

# Handshake

После успешной установки защищённого соединения, происходит обмен характеристиками обоих сторон, AKA "рукопожатие". Запрашивающий соединение отправляет пакет следующего формата:

`[magic number: 8B][protocol version: 4B][sizes: 1B][crypto params: 2B][reconnection flags: 2B]`

- Магическое число
	- _Тип:_ `uint64_t`
	- Магическое число протокола, по которому определяется совместимость цели с протоколом Stadium. См. раздел "Магическое число" для справки.
- Версия протокола
	- _Тип:_ `uint32_t`
	- Поддерживаемая запрашивающим версия протокола.
- Размерности частей пакета
	- _Тип:_ `uint8_t`
	- Описывает некоторые параметры пакетов.
		- Маска `0b11000000`: выделено под размерности типа событий
			- `0b00`: резерв
			- `0b01`: категория и подкатегория это `uint8_t` (каждая)
			- `0b10`: категория - `uint8_t`, подкатегория - `uint16_t`
			- `0b11`: категория и подкатегория это `int16_t` (каждая)
		- Маска `0b00110000`: выделено под размерность ключа в ячейке полезной нагрузки
			- `0b00`: резерв
			- `0b01`: ключ это `uint8_t`
			- `0b10`: ключ это `uint16_t`
			- `0b11`: ключ это `int32_t`
		- Маска `0b00001100`: выделено под размерность данных в ячейке
			- `0b00`: резерв
			- `0b01`: размер данных это `uint8_t`
			- `0b10`: размер данных это `uint16_t`
			- `0b11`: размер данных это `uint64_t`
		- Маска `0b00000011`: резерв
- Параметры криптографии
	- _Тип:_ `uint16_t`
	- Описывает используемые криптографические алгоритмы.
		- Если равно нулю, то используются опции данной версии протокола по умолчанию
<!-- TODO -->
- Флаги переподключения
	- _Тип:_ `uint16_t`
	- Описывает параметры нового подключения:
		- `0b0000000000000000`: оставить текущее подключение
		- `0b0000000000000001`: переподключиться к тому-же порту
		- `0b0000000000000010`: запросить новый порт для подключения
		- `0b0000000000000100`: использовать TCP
		- `0b0000000000001000`: использовать TLS
		- `0b0000111111110000`: резерв под расширение
		- `0b1111000000000000`: резерв под под нужды сторонних реализаций

На что целевой сервер отвечает пакетом либо с согласием, либо ошибкой.

Пакет с согласием имеет следующий формат:

`[magic number: 8B][0x00][reconnection port: 2B]`

- Магическое число
	- _Тип:_ `uint64_t`
	- См. выше.
- `0x00`
	- _Тип:_ `uint8_t`
	- Байт с фиксированным нулевым значением, свидетельствующий об успешном подключении и принятии целевым сервером обозначенных условий.
- Порт для переподключения
	- _Тип:_ `uint8_t`
	- К указанному порту целевой сервер предлагает подключиться запрашиваемому, если тот запросил его. Значение должно быть нулём, если порт не был запрошен.

Пакет с ошибкой имеет следующий формат:

`[magic number: 8B][error code: 1B][error description: ~B, zero-terminated]`

- Магическое число
	- _Тип:_ `uint64_t`
	- См. выше.
- Код ошибки
	- _Тип:_ `uint8_t`
	- Код, описывающий ошибку конкретнее.
		- 0x01: магическое число ложно.
		- 0x02: неподдерживаемая версия протокола.
		- 0x03: невозможно выделить новый порт для подключения.
		- 0x04: указанный транспортный протокол не поддерживается.
		- 0x05: указанная конфигурация размерностей не поддерживается.
		- 0x06: недопустимые параметры криптографии.
		- 0x07: один из указанных криптографических алгоритмов отключён на сервере.
- Описание ошибки
	- _Тип:_ `uint8_t`
	- Текстовое описание ошибки. Является строкой в кодировке ASCII, оканчивающейся нулевым байтом.

Если цель не поддерживает указанную при рукопожатии версию протокола, запрашивающий может попробовать установить соединение снова, указав более низкую и поддерживаемую им версию протокола.

Если при хэндшейке запрашивающим был указан новый способ подключения и получен валидный ответ с согласием от сервера - то они обязаны разорвать текущее соединение, затем, спустя случайное количество времени, от 50 мс до 500 мс, создать новое.

## Магическое число

Магическим числом протокола является следующая последовательность байт:

```
HEX: 0x53 0x74 0x61 0x64 0x69 0x75 0x6d 0x50
DEC:  83   116  97   100  105  117  109  80
```

Что соответствует строке "StadiumP" в кодировке ASCII.