14 KiB
14 KiB
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. Lifecyclenew/failedдаётunhealthy,starting/stopping— как минимумdegraded, аstoppedзадаёт общий healthstopped.
Единый 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(defaultfalse),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 использует stdlibStreamHandlerдля 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
- Реализовать runtime, health, workflow, identity и контракты адаптеров согласно capabilities.
- Добавить загрузку и перезагрузку
config.yaml, PostgreSQL adapters для настроек и business trace, а также технический formatter для stdout. - Документировать для потребителей, что создание таблиц и начальных данных
settings,trace_contexts,trace_messagesвыполняется миграциями приложения. - Подключить route adapter к host приложения и выпустить обновлённую версию библиотеки; миграции и изменение кода потребителей выполняются в самих приложениях.
Open Questions
Нет. HTTP host и listener принадлежат приложению; PLBA2 предоставляет подключаемый route adapter.