Files
alex d517820088
PLBA package CI / Python tests (push) Failing after 2s
PLBA package CI / Package version increment (push) Skipped
PLBA2-2. Архивация спек
2026-10-10 20:55:13 +03:00

87 lines
14 KiB
Markdown
Raw Permalink 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 — библиотека компонентов и runtime. Приложение владеет entrypoint, composition root, бизнес-логикой, рабочими сообщениями, схемой БД и HTTP host. Изменение объединяет десять capabilities, перечисленных в [proposal.md](proposal.md), и использует PLBA v1 как ориентир для workers, health, workflow и business trace.
## Goals / Non-Goals
**Goals:**
- Запускать именованные workers независимо и управлять ими через lifecycle приложения.
- Предоставить единые contracts для lifecycle, health, workflow, HTTP API, application identity, двух слоёв конфигурации и business trace.
- Отделить business trace от технических логов.
- Позволить бизнес-коду читать настройки через `SettingsReader`, не завися от PostgreSQL-адаптера.
**Non-Goals:**
- Не создавать entrypoint, composition root, HTTP server, сервис конфигурации, хранилище/API бизнес-истории.
- Не предоставлять общую очередь рабочих заданий или RabbitMQ API для них; приложение самостоятельно читает и публикует такие сообщения.
- Не выполнять миграции приложения, не реализовывать бизнес-логику workflow и не доставлять технические логи в платформенные системы.
## Decisions
### Runtime и workers
- `runtime/worker` задаёт уникальное стабильное имя worker, его независимый lifecycle, расписание, остановку и health. Отдельных API для запуска или остановки worker нет.
- При старте приложения запускаются workers, у которых `workers.<worker_name>.disabled` отсутствует или равно `false`. `disabled: true` исключает worker из запуска; изменение этого признака действует при следующем запуске приложения.
- Для включённого worker задаётся ровно одно положительное значение: `interval_seconds` или `pause_seconds`. Первый цикл начинается сразу, циклы одного worker не пересекаются. Интервал задаёт период между началами циклов; пауза задаётся после завершения цикла. Изменения расписания из активной конфигурации применяются при планировании следующего цикла.
- Graceful stop завершает текущий цикл и не запускает следующий. `force=true` прерывает активную обработку. Supervisor останавливает все запущенные workers и сообщает имена тех, кто ещё работает.
- Исключение цикла переводит автоматический health worker в `unhealthy`, но не завершает worker: runtime планирует следующий цикл. Превышение интервала даёт `degraded`; успешный следующий цикл восстанавливает автоматический статус `ok`. Итоговый статус — худший из автоматического и прикладного; прикладная health-логика не скрывает ошибку цикла.
### Lifecycle и health приложения
- `runtime/application-lifecycle` запускает все включённые workers; ошибка запуска переводит приложение в `failed`. При остановке lifecycle становится `stopped` после подтверждения остановки всех workers.
- Необязательный положительный `timeout_seconds` ограничивает ожидание ответа на stop-запрос. При истечении возвращается `stopping`, а остановка продолжается; без timeout ожидание не ограничено. Runtime не завершает OS process или HTTP host приложения.
- Health report включает `application_id`, lifecycle и состояния запущенных workers/contributors. Disabled workers не входят в набор ожидаемых компонентов. Статусы компонентов упорядочены `ok < degraded < unhealthy`; `unhealthy` некритичного компонента ограничивается до `degraded`. Отсутствующий некритичный worker даёт как минимум `degraded`, отсутствующий критичный — `unhealthy`. Lifecycle `new`/`failed` даёт `unhealthy`, `starting`/`stopping` — как минимум `degraded`, а `stopped` задаёт общий health `stopped`.
### Единый HTTP API
- `api/http/control-api` предоставляет общий route adapter, который приложение подключает к собственному HTTP host и listener. PLBA2 не запускает сервер и не открывает отдельный порт.
- Adapter предоставляет `GET /health`, `POST /runtime/start`, `POST /runtime/stop` и `GET /runtime/status`. Health делегируется aggregator, управление — lifecycle runtime; отдельные worker routes отсутствуют.
- `GET /health` возвращает health report без пересчёта в adapter. Start/status возвращают lifecycle status. Stop принимает `force` и необязательный положительный `timeout_seconds`; завершённая остановка возвращает HTTP 200 и `stopped`, продолжающаяся после timeout — HTTP 202 и `stopping`, некорректный запрос — HTTP 400.
### Workflow
- Приложение передаёт именованный `WorkflowDefinition` с начальным шагом и именованными узлами. Узел содержит `WorkflowStep` и карту переходов; шаг принимает `WorkflowContext` и возвращает `StepResult` с переходом, изменениями состояния и статусом.
- Engine применяет только объявленные переходы и не содержит бизнес-правил приложения. Переданный `WorkflowPersistence` сохраняет начало и итог запуска, начало и завершение каждого шага, snapshots контекста и ошибки.
- Исключение шага сохраняется и передаётся вызывающему коду; workflow прекращается без скрытого retry и без выполнения следующих шагов. Подключение к БД остаётся ответственностью приложения.
### Идентификатор приложения
- В корневом `config.yaml` приложение может задать необязательный строковый `application_id`. Непустое значение используется без изменений; иначе берётся `[project].name` из `pyproject.toml`, а при недоступности имени генерируется UUIDv4.
- Идентификатор разрешается до запуска зависимых компонентов, предоставляется runtime-контексту и не меняется в процессе. Сгенерированный UUIDv4 создаётся заново при следующем запуске, если имя проекта или значение в файле не заданы.
- Health report и технические логи используют этот ID; business trace adapter добавляет его в `attrs_json` контекста и каждого сообщения.
### Два слоя конфигурации
- `configuration/application-config-file` читает `config.yaml` из корня приложения по объявленной приложением типизированной модели. Общие поля PLBA2 — `application_id`, `workers.<worker_name>.disabled` (default `false`), `interval_seconds` и `pause_seconds`; остальные поля определяет приложение.
- YAML предназначен для редко меняемых технических параметров. Бизнес-параметры, feature toggles и технические значения, меняемые удалённо в runtime, хранятся в `settings`.
- Ошибка начальной загрузки файла блокирует запуск зависимых компонентов. При успешной проверке обновление атомарно заменяет активную конфигурацию без рестарта; уже полученные snapshots остаются неизменными. При ошибке перезагрузки остаётся последняя валидная конфигурация и приложению передаётся ошибка.
- `configuration/application-settings` задаёт таблицу `settings` в схеме приложения. В таблице хранятся `config_key`, `setting_key`, `setting_value`, `sort_order`, `is_enabled` и `description` вместе с идентификатором строки; уникальность `setting_key` не требуется. `is_enabled` включает строку в чтение, а значение feature toggle хранится в `setting_value`.
- Приложение создаёт таблицу `settings` и загружает начальные данные своей миграцией. PLBA2 миграции не запускает, строки не изменяет и YAML в БД не переносит.
- `SettingsReader` использует типизированные ключи и возвращает упорядоченные значения. PostgreSQL adapter читает через переданный приложением pool из его схемы, фильтрует по ключу, `config_key` и `is_enabled = TRUE`, сортирует по `sort_order`, затем `id`. Следующее чтение видит актуальные значения без рестарта.
### Business trace и технические логи
- Business trace adapter записывает контексты в `trace_contexts`, сообщения — в `trace_messages` схемы приложения. Публичный идентификатор называется `business_trace_id`, а в таблицах хранится как `trace_id`. В `attrs_json` обоих видов записей добавляется `application_id`.
- Приложение передаёт адаптеру PostgreSQL pool и имя схемы, а таблицы создаёт собственной миграцией. PLBA2 не владеет данными, не публикует business events в RabbitMQ и не предоставляет API бизнес-истории.
- Техническая запись — JSON-контракт с обязательными `timestamp`, `level`, `logger`, `message`, `application_id` и необязательными `attributes`, `business_trace_id`. Formatter использует stdlib `StreamHandler` для stdout; доставку и просмотр обеспечивает платформа.
## Risks / Trade-offs
- Если приложение не задаёт `application_id` и не имеет `[project].name`, UUIDv4 меняется между запусками; потребителям, которым нужен постоянный ID, следует задать его в `config.yaml`.
- Изменение `workers.<worker_name>.disabled` применяется только при следующем запуске приложения, тогда как валидные изменения расписания применяются при планировании следующего цикла.
- Приложению нужно владеть миграциями `settings`, `trace_contexts` и `trace_messages`, передавать PostgreSQL pool адаптерам и подключить HTTP routes к своему host.
## Migration Plan
1. Реализовать runtime, health, workflow, identity и контракты адаптеров согласно capabilities.
2. Добавить загрузку и перезагрузку `config.yaml`, PostgreSQL adapters для настроек и business trace, а также технический formatter для stdout.
3. Документировать для потребителей, что создание таблиц и начальных данных `settings`, `trace_contexts`, `trace_messages` выполняется миграциями приложения.
4. Подключить route adapter к host приложения и выпустить обновлённую версию библиотеки; миграции и изменение кода потребителей выполняются в самих приложениях.
## Open Questions
Нет. HTTP host и listener принадлежат приложению; PLBA2 предоставляет подключаемый route adapter.