gitadmin/dzentra_bot

Fork 0

Files

Sergey 433ac5d375 Build 060.21: integrate acquisition runtime protocols

2026-08-04 00:29:56 +03:00

28 KiB

Raw Blame History

Build 060.21 — Runtime Protocol Integration

Engineering Migration Report

Контроль документа

Свойство	Значение
Build	060.21
Название	Runtime Protocol Integration
Статус	Completed
Проект	Dzentra
Подсистема	Market Data Acquisition
Компонент	Acquisition Runtime Protocol Layer
Версия	1.0

Связанные документы

build_060_21_architecture.md — архитектурная спецификация Build.
build_060_20_1.md — Engineering Migration Report предыдущего корректирующего Build.
build_060_20_1_architecture.md — спецификация переноса владельца состояния Trade Stream.

Цель Build

Build 060.20.1 завершил архитектурную корректировку подсистемы Trades Feed (Time & Sales) и окончательно закрепил владельца состояния проверки согласованности потока сделок.

После предыдущего этапа архитектура сопровождения состояния приняла следующий вид.

TradeStreamConsistencyController
            │
            ▼
TradeStreamStateStore
            │
            ▼
TradeStreamState

Runtime перестал владеть состоянием предметной области и сохранил только инфраструктурную ответственность.

К началу Build 060.21 в проекте уже существовали:

транспортные WebSocket-протоколы;
типизированные Runtime-команды;
типизированные Runtime-события;
модели транспортных сообщений;
независимые подсистемы Trade Stream Consistency и Trade Recovery.

Однако отсутствовали публичные контракты, связывающие типизированные команды и события с будущей реализацией Runtime Service.

Главной задачей Build 060.21 стало расширение существующего Runtime Protocol Layer двумя узкими инфраструктурными контрактами:

AcquisitionRuntimeCommandDispatcherProtocol
AcquisitionRuntimeEventPublisherProtocol

Одновременно были введены точные типовые объединения:

AcquisitionRuntimeCommand
AcquisitionRuntimeEvent

Build сознательно не создаёт Runtime Service и не меняет поведение существующих компонентов.

Предпосылки

К началу настоящего Build Runtime Layer уже содержал базовые контракты:

WebSocketTransportProtocol
WebSocketSessionProtocol
WebSocketSubscriptionManagerProtocol

Они описывали:

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

Также существовали отдельные модели команд:

ConnectCommand
DisconnectCommand
SubscribeCommand
UnsubscribeCommand
SendTextCommand
SendBinaryCommand

и модели событий:

ConnectedEvent
DisconnectedEvent
ConnectFailedEvent
MessageReceivedEvent
MessageSentEvent
ReconnectStartedEvent
ReconnectCompletedEvent
ReconnectFailedEvent
HeartbeatTimeoutEvent

Несмотря на наличие всех перечисленных сущностей, в системе отсутствовал формальный контракт их передачи.

Не было определено:

каким образом команда поступает в Runtime;
каким образом Runtime публикует инфраструктурное событие;
какие типы команд допустимы;
какие типы событий допустимы;
как сохранить независимость Runtime от бизнес-логики Acquisition.

Именно эту контрактную границу формализует Build 060.21.

Результаты архитектурного аудита

Перед началом реализации был выполнен аудит следующих компонентов:

src/market_data/acquisition/runtime/websocket_protocol.py
src/market_data/acquisition/runtime/runtime_commands.py
src/market_data/acquisition/runtime/runtime_events.py
src/market_data/acquisition/runtime/transport_messages.py

Дополнительно были проанализированы:

Runtime unit-тесты;
Trades Feed;
WebSocket Trade Adapter;
Trade Stream Consistency;
Trade Recovery;
Acquisition Service и Registry;
repository-wide зависимости Runtime Protocol Layer.

Аудит подтвердил, что текущие команды и события уже достаточны для настоящего этапа.

Следовательно:

новые команды не требуются;
новые события не требуются;
существующие WebSocket Protocol не должны изменять ответственность;
Runtime Service не должен создаваться преждевременно;
Consistency и Recovery не должны получать Runtime-зависимости.

Отказ от общего RuntimeServiceProtocol в Build 060.21

На раннем этапе проектирования рассматривалось создание единого контракта:

RuntimeServiceProtocol

Предполагалось включить в него операции жизненного цикла, подписок, отправки сообщений и состояния соединения.

После аудита данный шаг был признан преждевременным.

В утверждённой дорожной карте следующий этап определён отдельно:

060.22 Runtime Service Integration

Создание полноценного сервисного контракта в Build 060.21 фактически перенесло бы часть ответственности Build 060.22 в текущий этап.

Поэтому Build 060.21 ограничен только недостающими инфраструктурными контрактами:

dispatcher команд;
publisher событий.

Такое решение сохраняет строгую границу между этапами.

Архитектурное решение

После завершения Build Runtime Protocol Layer имеет следующий вид.

Acquisition Runtime Commands
            │
            ▼
AcquisitionRuntimeCommandDispatcherProtocol
            │
            ▼
Future Runtime Service
            │
            ▼
AcquisitionRuntimeEventPublisherProtocol
            │
            ▼
Acquisition Runtime Events

Новые Protocol не реализуют поведение.

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

AcquisitionRuntimeCommand

В websocket_protocol.py введён типовой alias:

AcquisitionRuntimeCommand

Он объединяет все допустимые инфраструктурные команды Acquisition Runtime:

ConnectCommand;
DisconnectCommand;
SubscribeCommand;
UnsubscribeCommand;
SendTextCommand;
SendBinaryCommand.

Таким образом будущая реализация dispatcher получает строго ограниченный тип входных данных.

Она не может принимать:

Trade;
Quote;
Candle;
Recovery Request;
произвольный объект приложения.

Это закрепляет независимость Runtime от предметной области.

AcquisitionRuntimeEvent

Также введён типовой alias:

AcquisitionRuntimeEvent

Он объединяет все допустимые инфраструктурные события Acquisition Runtime:

ConnectedEvent;
DisconnectedEvent;
ConnectFailedEvent;
MessageReceivedEvent;
MessageSentEvent;
ReconnectStartedEvent;
ReconnectCompletedEvent;
ReconnectFailedEvent;
HeartbeatTimeoutEvent.

Alias сознательно получил префикс Acquisition.

В проекте уже существует отдельная глобальная система событий:

src/runtime_events/

с собственной моделью RuntimeEvent.

Использование общего имени внутри Acquisition создало бы неоднозначность и риск ошибочных импортов.

Поэтому итоговые имена были уточнены:

AcquisitionRuntimeCommand
AcquisitionRuntimeEvent

Это решение полностью устраняет терминологический конфликт.

AcquisitionRuntimeCommandDispatcherProtocol

Добавлен новый публичный контракт:

AcquisitionRuntimeCommandDispatcherProtocol

Protocol определяет одну операцию:

dispatch(command: AcquisitionRuntimeCommand) -> None

Метод является асинхронным.

Dispatcher отвечает только за передачу одной типизированной инфраструктурной команды в Runtime.

Он не определяет:

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

Все перечисленные обязанности относятся к будущей реализации Runtime Service.

AcquisitionRuntimeEventPublisherProtocol

Добавлен второй публичный контракт:

AcquisitionRuntimeEventPublisherProtocol

Protocol определяет одну операцию:

publish(event: AcquisitionRuntimeEvent) -> None

Метод также является асинхронным.

Publisher отвечает исключительно за публикацию уже произошедшего инфраструктурного факта.

Он не определяет:

список подписчиков;
механизм доставки;
очередь событий;
обработку ошибок потребителей;
реакцию Trades Feed;
запуск Recovery;
правила reconnect.

Эти вопросы относятся к последующим Build.

Почему Protocol расположены в websocket_protocol.py

В рамках настоящего Build новые контракты добавлены в существующий файл:

src/market_data/acquisition/runtime/websocket_protocol.py

Причины данного решения:

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

При дальнейшем расширении Runtime Protocol Layer отдельный файл может быть введён отдельным согласованным Build, если объём контрактов действительно потребует этого.

Настоящий Build не выполняет структурную реорганизацию каталогов.

Разделение ответственности

После завершения Build окончательно закреплены следующие границы.

Runtime Commands

Команды являются неизменяемыми инфраструктурными намерениями.

Они описывают, что необходимо выполнить.

Они не выполняют операцию самостоятельно.

Command Dispatcher

Dispatcher принимает команду и передаёт её будущей реализации Runtime.

Он не содержит бизнес-логики.

Runtime Events

События являются неизменяемыми инфраструктурными фактами.

Они описывают уже произошедшее состояние транспорта.

Event Publisher

Publisher передаёт событие заинтересованным потребителям.

Он не определяет реакцию потребителя.

WebSocket Transport

Transport продолжает отвечать только за низкоуровневое соединение и транспортные сообщения.

WebSocket Session

Session продолжает отвечать за жизненный цикл WebSocket-сессии.

Subscription Manager

Subscription Manager продолжает отвечать за восстановление и очистку активных подписок.

Изменённые файлы

В рамках Build изменены только два файла.

Runtime Protocol Layer

src/market_data/acquisition/runtime/websocket_protocol.py

Добавлены:

AcquisitionRuntimeCommand;
AcquisitionRuntimeEvent;
AcquisitionRuntimeCommandDispatcherProtocol;
AcquisitionRuntimeEventPublisherProtocol.

Существующие Protocol сохранены без изменения поведения:

WebSocketTransportProtocol;
WebSocketSessionProtocol;
WebSocketSubscriptionManagerProtocol.

Unit-тесты Runtime Protocol

tests/unit/market_data/acquisition/runtime/test_websocket_protocol.py

Добавлены тестовые реализации:

FakeRuntimeCommandDispatcher;
FakeRuntimeEventPublisher.

Добавлены проверки:

полная реализация dispatcher соответствует Protocol;
полная реализация publisher соответствует Protocol;
неполная реализация dispatcher не соответствует Protocol;
неполная реализация publisher не соответствует Protocol.

Все существующие тесты WebSocket Protocol сохранены.

Файлы, которые не изменялись

Аудит подтвердил отсутствие необходимости менять:

src/market_data/acquisition/runtime/runtime_commands.py
src/market_data/acquisition/runtime/runtime_events.py
src/market_data/acquisition/runtime/transport_messages.py

Их существующее поведение полностью соответствует новому Protocol Layer.

Также не изменялись:

Runtime Supervisor;
Reconnect;
Scheduler;
Heartbeat;
Trades Feed;
WebSocket Adapters;
Trade Stream Consistency;
Trade Recovery;
Acquisition Service;
Acquisition Registry.

Unit-тестирование

Новый Runtime Protocol Layer был покрыт структурными unit-тестами.

Проверялись следующие сценарии:

реализация WebSocket Transport удовлетворяет Protocol;
реализация WebSocket Session удовлетворяет Protocol;
реализация Subscription Manager удовлетворяет Protocol;
реализация Command Dispatcher удовлетворяет Protocol;
реализация Event Publisher удовлетворяет Protocol;
неполный Transport отклоняется;
неполный Command Dispatcher отклоняется;
неполный Event Publisher отклоняется.

Результат локального теста:

8 passed

Регрессионное тестирование Runtime Layer

После добавления новых контрактов выполнен полный прогон тестов каталога Runtime.

Проверены:

Runtime Commands;
Runtime Events;
Transport Messages;
WebSocket Protocols;
новые dispatcher и publisher Protocol.

Результат:

34 passed

Это подтверждает, что расширение Protocol Layer не изменило существующее поведение Runtime.

Расширенное регрессионное тестирование

Дополнительно выполнен совместный прогон трёх связанных подсистем:

Runtime
Consistency
Recovery

Результат:

136 passed

Тем самым подтверждено:

Runtime Protocol Layer работает корректно;
Trade Stream Consistency не затронута;
Trade Stream State Store не затронут;
Trade Recovery не затронута;
новые контракты не создали циклических или скрытых зависимостей.

Repository-wide аудит имён

После первоначальной реализации был выполнен поиск по репозиторию.

Аудит выявил существующую глобальную модель:

src.runtime_events.models.RuntimeEvent

Поэтому первоначальные общие имена:

RuntimeCommand
RuntimeEvent
RuntimeCommandDispatcherProtocol
RuntimeEventPublisherProtocol

были уточнены.

Итоговые имена:

AcquisitionRuntimeCommand
AcquisitionRuntimeEvent
AcquisitionRuntimeCommandDispatcherProtocol
AcquisitionRuntimeEventPublisherProtocol

Это разделяет:

Acquisition Runtime transport events;
глобальные application runtime events.

Терминологическая неоднозначность полностью устранена.

Обратная совместимость

Build сохраняет полную обратную совместимость.

Не изменились:

сигнатуры существующих WebSocket Protocol;
модели Runtime Commands;
модели Runtime Events;
модели Transport Messages;
алгоритмы Stream Consistency;
State Store;
Recovery Pipeline;
Trades Feed;
каноническая модель Trade.

Новые контракты являются исключительно расширением публичного Protocol Layer.

Существующие реализации не обязаны реализовывать новые Protocol до момента их подключения в последующих Build.

Производительность

Build не добавляет runtime-операций и не влияет на производительность системы.

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

Protocol также не создают дополнительного runtime-поведения, за исключением стандартной structural runtime-проверки через @runtime_checkable, уже применявшейся в существующем коде.

Следовательно Build не влияет на:

задержку обработки сообщений;
пропускную способность WebSocket;
использование памяти;
обработку Trade Stream;
Recovery Pipeline.

Подтверждённые архитектурные инварианты

Runtime не знает предметную область

Новые контракты принимают только Acquisition Runtime Commands и Events.

Они не используют модели Trade, Quote, Candle или Order Book.

Consistency не зависит от Runtime

TradeStreamConsistencyController продолжает зависеть только от собственного State Store.

Recovery не зависит от Runtime

TradeRecoveryController продолжает использовать только TradeStreamConsistencyProtocol.

Команды отделены от исполнения

Command-модели описывают намерение.

Dispatcher предоставляет контракт передачи команды.

Реализация выполнения отсутствует в настоящем Build.

События отделены от реакции

Event-модели описывают инфраструктурный факт.

Publisher предоставляет контракт публикации.

Реакция потребителей отсутствует в настоящем Build.

Runtime Service не входит в Scope

Настоящий Build не создаёт сервисную реализацию и не определяет полный сервисный API.

Эта ответственность закреплена за Build 060.22.

Что не входит в Scope Build

Настоящий Build сознательно ограничен расширением Runtime Protocol Layer.

В него не входят:

реализация Command Dispatcher;
реализация Event Publisher;
Runtime Service;
Runtime Supervisor;
запуск и остановка Runtime;
обработка команд;
доставка событий подписчикам;
очередь событий;
Reconnect orchestration;
Heartbeat orchestration;
Scheduler;
интеграция Trades Feed;
интеграция Acquisition Service;
автоматический запуск Recovery;
восстановление подписок после reconnect;
Composition Root.

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

Архитектурное значение Build

Несмотря на небольшой объём изменения production-кода, Build 060.21 является важным контрактным этапом.

До него Runtime Layer обладал моделями команд и событий, но не имел формального интерфейса их передачи.

После завершения Build появляются две стабильные точки расширения:

AcquisitionRuntimeCommandDispatcherProtocol
AcquisitionRuntimeEventPublisherProtocol

Именно через них последующие реализации смогут:

принимать инфраструктурные команды;
публиковать инфраструктурные события;
сохранять независимость от конкретного транспорта;
оставаться изолированными от предметной области Market Data Acquisition.

Это создаёт основу для Build 060.22 без преждевременного внедрения сервисной реализации.

Связь с последующими Build

Build 060.22 — Runtime Service Integration

Будущая реализация Runtime Service должна использовать новые Protocol как публичные границы передачи команд и событий.

Build 060.23 — Acquisition Integration

Acquisition Layer сможет использовать Runtime Service через утверждённые контракты без прямой зависимости от внутренней реализации Runtime.

Build 060.24 — Reconnect & Runtime Recovery

Reconnect, resubscribe и запуск Recovery смогут строиться на типизированных командах и событиях без изменения существующих контрактов Consistency и Recovery.

Build 060.25 — Integration & Regression

Будет выполнена полная проверка взаимодействия Runtime, Acquisition, Consistency и Recovery.

Заключение

Build 060.21 завершает формирование базового Runtime Protocol Layer внутри подсистемы Market Data Acquisition.

В рамках этапа не создавалась новая реализация и не менялось функциональное поведение системы.

Вместо этого были введены две узкие инфраструктурные границы:

AcquisitionRuntimeCommandDispatcherProtocol
AcquisitionRuntimeEventPublisherProtocol

Они дополняют уже существующие:

WebSocketTransportProtocol
WebSocketSessionProtocol
WebSocketSubscriptionManagerProtocol

и создают полный контрактный фундамент для будущего Runtime Service.

Build сохранил независимость:

Runtime от бизнес-моделей;
Consistency от Runtime;
Recovery от Runtime;
Feed от внутренней реализации транспорта.

Все изменения подтверждены unit- и regression-тестами.

Итог Build

После завершения Build 060.21 система обладает следующими возможностями.

✓ Определён полный типовой набор Acquisition Runtime Commands.

✓ Определён полный типовой набор Acquisition Runtime Events.

✓ Введён публичный Protocol передачи Runtime-команд.

✓ Введён публичный Protocol публикации Runtime-событий.

✓ Устранён терминологический конфликт с глобальной подсистемой src/runtime_events.

✓ Существующие Runtime Commands и Events сохранены без изменений.

✓ Consistency и Recovery сохранены без изменений.

✓ Runtime regression завершён результатом 34 passed.

✓ Расширенный regression завершён результатом 136 passed.

Build 060.21 — Runtime Protocol Integration считается полностью завершённым и готовым к фиксации в Git.

28 KiB Raw Blame History Unescape Escape