# Build 059.9 — WebSocket Runtime Protocol

**Migration Build**

---

# Цель Build

Build 059.9 открывает новый этап миграции подсистемы получения рыночных данных.

До настоящего момента была полностью построена независимая цепочка обработки входящих сообщений:

```text
Raw Message
      │
Schema Validation
      │
Parser
      │
Value Validation
      │
Mapper
      │
Canonical Model
      │
Adapter
```

Данная архитектура уже позволяет корректно обрабатывать сообщения независимо от конкретного транспорта доставки.

Следующим этапом становится построение собственного Runtime уровня, который будет отвечать исключительно за транспортировку сообщений.

---

# Причина появления Runtime

Исторически получение данных осуществлялось через класс ExchangeWebSocketClient.

Этот класс одновременно выполнял множество различных обязанностей:

- открытие соединения;
- закрытие соединения;
- reconnect;
- heartbeat;
- отправку запросов;
- получение сообщений;
- обработку ошибок;
- маршрутизацию сообщений;
- работу с конкретной биржей.

Подобная архитектура нарушает принцип единственной ответственности (Single Responsibility Principle) и значительно усложняет расширение системы.

В новой архитектуре эти обязанности разделяются между несколькими независимыми компонентами Runtime.

---

# Основная идея новой архитектуры

Runtime не должен знать ничего о бизнес-логике.

Он отвечает исключительно за транспортный уровень.

После завершения всей серии Build'ов структура будет выглядеть следующим образом:

```text
                    Exchange Runtime
                           │
                 Connection / Session
                           │
                 Heartbeat / Reconnect
                           │
                Subscription Manager
                           │
                WebSocket Transport
                           │
                           ▼
              Unified WebSocket Adapter
                           │
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
      Quote             Candle            Trades
                           │
                           ▼
               Feed → Handler → Registry
```

Таким образом Runtime становится полностью независимым от конкретного вида сообщений.

---

# Почему Runtime создаётся отдельно

В подсистеме Acquisition уже существует файл

```
acquisition/protocol.py
```

Он содержит контракты уровня получения данных:

- InstrumentDocumentSource
- QuoteDocumentSource
- CandlesDocumentSource
- Feed Protocol
- Handler Protocol

Эти контракты ничего не знают о WebSocket.

Они работают уже после доставки сообщения.

Поэтому смешивать Acquisition Protocol и Runtime Protocol архитектурно неправильно.

В результате Runtime получает собственный уровень контрактов.

---

# Новые контракты Runtime

В Build 059.9 создаётся новый файл:

```text
src/market_data/acquisition/runtime/websocket_protocol.py
```

В нём определяются исключительно транспортные контракты:

- WebSocketTransportProtocol
- WebSocketSessionProtocol
- WebSocketSubscriptionManagerProtocol

Все контракты являются Protocol без реализации.

---

# Что входит в ответственность Runtime

Runtime отвечает только за транспортный уровень.

Например:

- открытие соединения;
- закрытие соединения;
- получение транспортных сообщений;
- отправку транспортных сообщений;
- жизненный цикл WebSocket Session;
- управление подписками.

Runtime **не выполняет**:

- schema validation;
- parsing;
- value validation;
- mapping;
- business routing;
- преобразование моделей;
- обработку рыночной логики.

Все эти обязанности уже реализованы в Acquisition.

---

# Что намеренно НЕ реализуется в Build 059.9

В рамках данного Build отсутствуют:

- WebSocket клиент;
- asyncio логика;
- reconnect;
- heartbeat;
- ping/pong;
- сериализация сообщений;
- JSON;
- модели транспортных сообщений;
- реальные подписки.

Build создаёт исключительно архитектурный фундамент.

---

# План дальнейшего развития Runtime

После Build 059.9 развитие Runtime планируется небольшими независимыми этапами.

## Build 059.10

Transport Message Models

Добавление immutable моделей транспортных сообщений.

Например:

- Connect
- Disconnect
- Subscribe
- Ping
- Pong

---

## Build 059.11

Subscription Manager

Появится полноценное управление активными подписками.

---

## Build 059.12

WebSocket Session

Жизненный цикл соединения.

---

## Build 059.13

Reconnect Manager

Автоматическое восстановление соединения.

---

## Build 059.14

Heartbeat

Поддержание активности соединения.

---

# Архитектурный принцип миграции

Все существующие Parser, Validator, Mapper и Adapter остаются неизменными.

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

В результате один и тот же Adapter сможет работать:

- со старым ExchangeWebSocketClient;
- с новым Runtime;
- с тестовыми сообщениями;
- с любым будущим источником данных.

Это позволяет выполнять миграцию постепенно без остановки работы существующего торгового бота.

---

# Новое архитектурное соглашение проекта

Во время выполнения Build принято дополнительное архитектурное решение.

Для крупных подсистем проекта рекомендуется использовать описательные имена файлов вместо слишком общих.

Например:

Хорошо:

```text
websocket_protocol.py
market_cache.py
exchange_service.py
```

Предпочтительно избегать новых файлов с названиями:

```text
protocol.py
service.py
utils.py
helpers.py
```

если их назначение можно описать более конкретно.

Это правило принято с расчётом на дальнейший рост проекта и будет постепенно применяться при плановой архитектурной ревизии существующих модулей.

---

# Проверка Build

Выполнены проверки:

- compileall
- unit tests
- runtime regression
- git diff --check

Все проверки успешно пройдены.

---

# Итог

Build 059.9 не добавляет новую функциональность получения рыночных данных.

Его задача — создать фундамент Runtime уровня, который позволит в последующих Build'ах полностью заменить существующий транспорт WebSocket без изменения уже реализованной цепочки обработки сообщений.