Files
plba_v2/openspec/changes/plba2-runtime-and-adapters/design.md
T

98 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Design
## Context
PLBA2 — Python-библиотека компонентов и runtime. Приложение владеет entrypoint, composition root, бизнес-логикой, рабочими сообщениями, схемой БД и HTTP host. PLBA2 предоставляет десять capabilities из [proposal.md](proposal.md). Реализации PLBA v1 служат ориентиром для worker, health, workflow и бизнес trace контрактов.
## Goals / Non-Goals
**Goals:**
- Запускать несколько независимо выполняемых workers с уникальными именами; управлять ими только через lifecycle всего приложения.
- Дать приложению единые contracts для lifecycle, health, workflow, HTTP API, identity, двух слоёв конфигурации и business trace.
- Разделить персистентную бизнес-историю и технический вывод в stdout.
- Поддержать замену PostgreSQL settings adapter без изменения кода, использующего SettingsReader.
**Non-Goals:**
- Не создавать entrypoint, composition root, HTTP server, сервис настроек или API business history.
- Не предоставлять общую очередь, RabbitMQ consumer/producer для рабочих заданий, outbox или retry framework.
- Не управлять миграциями приложения, доставкой stdout логов или бизнес-правилами workflow.
## Decisions
### Runtime и workers
- Capability `runtime/worker` отвечает за имена, независимый lifecycle, расписание, внутреннюю остановку и health отдельных workers.
- Capability `runtime/application-lifecycle` управляет запуском и остановкой приложения; при запуске стартуют все workers без `disabled: true`. Отдельного API для запуска или остановки worker нет. Runtime не завершает принадлежащий приложению OS process или HTTP host.
- При обычной остановке каждый worker завершает текущий цикл и не начинает следующий; `force=true` прерывает активную обработку. Приложение становится `stopped` после остановки всех workers.
- `timeout_seconds` ограничивает только ожидание HTTP-вызова. При его истечении возвращается `stopping`, а остановка продолжается; отсутствие timeout означает неограниченное ожидание.
- Worker читает признак запуска из `workers.<worker_name>.disabled` и расписание из `workers.<worker_name>.interval_seconds` или `pause_seconds` в `config.yaml`. Отсутствующий `disabled` эквивалентен `false`; изменение признака во время работы вступает в силу при следующем запуске приложения.
- Интервал задаёт период между началами циклов, пауза — стабильное ожидание после каждого цикла; активные изменения расписания применяются при планировании следующего цикла.
- Исключение цикла не завершает worker. Runtime выставляет автоматический health status; прикладная health-логика добавляет собственные условия, а `critical` ограничивает влияние worker по правилам health aggregation.
### Health
- Сохраняется v1 модель worker health и агрегация `ok`, `degraded`, `unhealthy`.
- Health report содержит application_id, runtime state и health-состояния запущенных workers; contributors вычисляют собственное состояние. Некритичный компонент может ухудшить aggregate до `degraded`, но не до `unhealthy` по HL.AG-01.FR-01.
- Worker с `disabled: true` исключается из набора ожидаемых компонентов.
- Если runtime lifecycle приложения `stopped`, aggregate health возвращает `stopped`.
### Единый HTTP API
- PLBA2 предоставляет один router для health и lifecycle всего приложения; общий adapter описан в [API.HTTP.CA-01](specs/api/http/control-api/spec.md), отдельные endpoints — в своих Requirements.
- Приложение подключает router к одному HTTP host и listener. Все routes используют один порт; capabilities не запускают собственные серверы.
- HTTP слой делегирует расчёт health capability HL.AG-01 и управление приложением — RT.AL-01–RT.AL-02. Отдельных worker routes нет; состояния запущенных workers доступны в агрегированном health-отчёте.
### Workflow
- Сохраняется object-based API PLBA v1: WorkflowDefinition, WorkflowNode, WorkflowStep, WorkflowContext и StepResult.
- Engine применяет только объявленные переходы, сохраняет ход выполнения через WorkflowPersistence и передаёт исключения вызывающему приложению.
- Рабочие сообщения, retries и предметные решения остаются у приложения.
### Идентификатор приложения
- Необязательное `application_id` задаётся в корневом `config.yaml`. Если оно отсутствует или пустое, runtime берёт `[project].name` из `pyproject.toml`, а при недоступности метаданных генерирует UUIDv4.
- Идентификатор разрешается до старта зависимых компонентов, предоставляется runtime-контексту и не меняется в течение процесса. Health и логирование используют его согласно требованиям своих capabilities.
### Настройки
- CFG.AS-01 описывает таблицу `settings` для бизнес-параметров, feature toggles и технических значений, которые требуется менять удалённо в runtime.
- По CFG.AS-02 приложение создаёт таблицу и загружает начальные значения собственными миграциями. Дальнейшие обновления строк выполняются владельцем приложения; PLBA2 не запускает миграции и не предоставляет сервис изменения конфигурации.
- По CFG.AS-03 типизированный SettingsReader читает актуальные значения. Изменения в БД становятся доступны при следующем чтении без рестарта приложения; PostgreSQL adapter фильтрует строки и сортирует их по `sort_order`, `id`.
### Техническая конфигурация из файла
- CFG.ACF-01 читает `config.yaml` из корня приложения. PLBA2 задаёт общее необязательное поле `application_id`, `workers.<worker_name>.disabled` (по умолчанию `false`) и поля расписания `workers.<worker_name>.interval_seconds` / `workers.<worker_name>.pause_seconds`; остальные поля и типизированную модель файла определяет приложение.
- Локальный file provider заменяет текущую модель удалённых configuration snapshots; отдельный configuration-service и сетевой client не входят в PLBA2.
- Файл хранит редко меняемые технические параметры. Бизнес-параметры, feature toggles и технические значения для удалённых runtime-изменений находятся в таблице `settings`.
- CFG.ACF-02 обнаруживает изменения файла и атомарно заменяет активную конфигурацию после проверки. Последующие чтения получают новый снимок; уже полученные снимки не мутируют.
- Ошибка начальной загрузки блокирует запуск зависимых компонентов. При невалидном runtime-изменении сохраняется последний валидный снимок и приложению сообщается ошибка.
- Реализация требует YAML parser; механизм обнаружения изменения файла остаётся деталью адаптера и не входит в публичный контракт.
### Business trace и технические логи
- Business trace adapter пишет контексты и сообщения в `trace_contexts` и `trace_messages` схемы приложения; `application_id` входит в `attrs_json` контекста и каждого сообщения, без добавления колонок; migration приложения создаёт обе таблицы.
- В публичном контракте используется `business_trace_id`, в совместимой схеме таблиц — поле `trace_id`.
- Бизнес-события не публикуются через RabbitMQ. Чтение истории и API истории не входят в эту capability.
- Technical logger формирует JSON с фиксированными полями и пишет в stdout; platform agent отвечает за доставку и просмотр.
## Risks / Trade-offs
- Отсутствие индивидуального worker API упрощает управление приложением; уникальные имена нужны для конфигурации, регистрации и health.
- Повторяющиеся setting keys требуют упорядоченного списка значений; adapter не сводит их к одной строке.
- Приложению нужно подключить один route bundle и включить миграции до запуска адаптеров.
- Изменение публичных контрактов текущего скелета требует отдельной версии PLBA2 и осознанной миграции потребителей.
## Migration Plan
1. Реализовать core contracts для application identity, worker runtime, health, workflow, двух слоёв конфигурации и business trace.
2. Добавить YAML loader dependency и PostgreSQL adapters; не добавлять RabbitMQ extra.
3. Включить создание `settings`, `trace_contexts` и `trace_messages` в первые миграции каждого приложения.
4. Перевести приложения на named workers, единый route bundle, SettingsReader, business trace adapter и JSON stdout formatter.
5. Выпустить новую major-версию; при откате вернуть предыдущую версию пакета, не удаляя данные приложений.
## Open Questions
Нет. HTTP host и единственный listener остаются у приложения; PLBA2 отдаёт подключаемый router.