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

12 KiB
Raw Blame History

Design

Context

PLBA2 — Python-библиотека компонентов и runtime. Приложение владеет entrypoint, composition root, бизнес-логикой, рабочими сообщениями, схемой БД и HTTP host. PLBA2 предоставляет десять capabilities из 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, отдельные 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.