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

14 KiB
Raw Blame History

Design

Context

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