stadium-proto/Overview.md

# Обзор



## Терминология

Здесь перечислены используемые в данной документации термины, значение которых может быть не очевидно и/или не соответствует тому, которое подразумевается обычно.

### Узел

Любая машина, способная выполнять коммуникацию по протоколу Stadium. Обычно используется в контексте коммуникации двух машин одного ранга или когда ранг не имеет значения.

### Сервер

Выполняющий роль сервера _узел_ в многоранговой сети.

### Клиент

Выполняющий роль клиента _узел_ в многоранговой сети.

### Шифрованное соединение/сессия

Соединение между двумя _узлами_, все _события_ в котором шифруются с помощью оговорённого симметричного алгоритма и ключа, а также подписываются с помощью известного приватного ключа подписи отправителя.

### Событие

Структура данных, обладающая конкретными семантическими свойствами в зависимости от типа и содержащая дополнительные поля, требуемые для верного отображения и интерпретации самой структуры. Проще говоря - то, чем обмениваются и что обрабатывают _узлы_ во время коммуникации между собой.

### Шумовое событие

_Событие_ предопределённой категории, имеющее случайно-сгенерированные поля.

### LBM

Аббревиатура наименования способа форматирования (сериализации) данных, используемого для полезной нагрузки _события_, которая расшифровывается как "Linear Binary Map". Подробнее - в [LBM.md](LBM.md).

### Шумовые данные

Случайно-сгенерированные данные, помещённые в специализированную ячейку полезной нагрузки _события_.



## Пример коммуникации двух узлов

Допустим, что у нас есть два неизвестных\* друг-другу _узла_ - `p1` и `p2`. Тогда полная коммуникация по шагам (от подключения неизвестного для `p2` _узла_ - до "правильного" уничтожения сессии и закрытия соединения) будет выглядеть так:

1. `p1` запрашивает открытое (нешифрованное) рукопожатие с избранными параметрами соединения у `p2`
2. `p2` отвечает `p1` согласием со своей частью параметров
3. `p1` запрашивает публичный ключ подписи у `p2`
4. `p2` передаёт свой публичный ключ, вместе с используемым алгоритмом
5. `p1` сохраняет полученный публичный ключ и разрывает\*\* соединение и заново устанавливает его, путём отправки `p2` запроса шифрованного хэндшейка
6. `p2` отвечает согласием со своей частью параметров подключения
7. `p1` отправляет зашифрованное _событие_ с запросом какого-то объекта
8. `p2` отвечает зашифрованным _событием_, содержащее статус-код или этот объект
9. `p1` отправляет _событие_ с сообщением о намерении уничтожить сессию и ждёт в течении n времени, по истечению которого может разорвать соединение "насильно"
10. `p2` принимает запрос и прекращает любой параллельный обмен данными
11. `p2` отвечает _событием_ с кодом успешности операции
12. `p2` закрывает соединение

И в виде схемы:

```
Requesting p2's public key:
[p1] ------[raw handshake request]----> [p2]
[p1] <-----[raw handshake accept]------ [p2]
[p1] ----[request public sign key]----> [p2]
[p1] <-[public key and crypto params]-- [p2]
[p1] ---------[close session]---------> [p2]
[p1] <--------[status code OK]--------- [p2]

Reconnecting in encrypted way and requesting object:
[p1] ---[encrypted handshake request]-> [p2]
[p1] <--[encrypted handshake accept]--- [p2]
[p1] ------[request some object]------> [p2]
[p1] <-[some object data/status code]-- [p2]
[p1] ---------[close session]---------> [p2]
[p1] <--------[status code OK]--------- [p2]
```

\* - _стоит уточнить, что в реальных сценариях использования публичный ключ целевого узла скорее всего уже известен, либо коммуникация должна производиться через транспорт, гарантирующий достоверность передаваемых данных. `p1` может узнать о существовании таковых, путём отправки события специального типа. В данном примере сей шаг опущен._

<!--TODO: таки описать этот шаг ^^^-->

\*\* - _"разрыв" соединения предполагает обмен между узлами событиями с информацией о завершении сессии; в данном пункте эти шаги опущены, но упомянуты ниже._