PLBA2-2. Правка readme.md

This commit is contained in:
2026-10-10 20:23:22 +03:00
parent 71998a6b13
commit 295cc30ead
+63 -56
View File
@@ -1,52 +1,65 @@
# PLBA v2 # PLBA v2
PLBA v2 is a transport-neutral Python library for application lifecycle, ## Подключение PLBA v2 к приложению
workers, health aggregation, configuration snapshots, workflows, business
tracing, and structured technical logs. It is a separate package from PLBA v1.
The application owns its entrypoint and composition root, business logic, HTTP PLBA v2 подключается к Python-приложению как библиотека. Отдельный Docker-образ PLBA собирать и публиковать не нужно: образ приложения будет содержать само приложение и установленную библиотеку.
host and listener, database schema and migrations, and message queues. PLBA2
provides components and adapters that the application wires together; it does
not start a service or create a second HTTP port.
## Capabilities 1. Отправьте нужный коммит PLBA в публичный репозиторий. В checkout PLBA получите его полный SHA:
- `runtime/application-identity` resolves `application_id` from `config.yaml`, ```bash
then `[project].name` in `pyproject.toml`, then UUIDv4. git rev-parse HEAD
- `runtime/worker` registers uniquely named workers, applies the `disabled` ```
flag, runs sequential scheduled cycles, combines application and automatic
health, and supports graceful or force stop.
- `runtime/application-lifecycle` starts and stops all enabled workers and
reports application lifecycle states.
- `health/aggregation` combines worker and contributor states, criticality,
missing components, and application lifecycle into a health report.
- `api/http/control-api` is a mountable ASGI adapter for `GET /health`,
`POST /runtime/start`, `POST /runtime/stop`, and `GET /runtime/status`.
- `configuration/application-config-file` loads an application-typed root
`config.yaml` and atomically reloads valid snapshots without a restart.
- `configuration/application-settings` provides a typed `SettingsReader` and a
PostgreSQL adapter for the application's `settings` table.
- `workflow/orchestration` executes named object-based steps through declared
transitions and persists run and step snapshots through an application port.
- `observability/business-tracing` provides trace contracts and a PostgreSQL
writer for application-owned `trace_contexts` and `trace_messages` tables.
- `observability/technical-logging` formats JSON log records with application
and business trace identifiers for stdout.
## Install 2. Добавьте PLBA в зависимости нового приложения в его `pyproject.toml`, подставив полученный SHA:
```toml
[project]
name = "my-application"
dependencies = [
"plba-v2 @ git+https://git.lesha.spb.ru/infra/plba_v2.git@<ПОЛНЫЙ_SHA_КОММИТА>",
]
```
Репозиторий открыт, поэтому установка по HTTPS не требует PAT или SSH-ключа. Закрепляйте полный SHA, а не `main`: тогда локальная установка, CI и сборка образа приложения получат один и тот же код PLBA. Номер версии пакета и Git-ссылка — разные вещи; используйте Git-тег только после того, как он создан и проверен.
3. Из корня репозитория приложения установите его зависимости:
```bash
python -m pip install -e .
```
Для установки Git-зависимости в среде сборки должен быть доступен Git. После установки импортируйте компоненты библиотеки из пространства имён `plba`, например `from plba.runtime import ApplicationRuntime`. Если ваш менеджер пакетов создаёт lock-файл, сохраните его в репозитории приложения и используйте при установке зависимостей в CI и Docker-сборке.
При разработке PLBA и приложения на одной машине можно временно установить библиотеку из соседнего checkout:
```bash ```bash
pip install . python -m pip install -e ../plba_v2
``` ```
The PostgreSQL adapters accept the application's pool and schema. PLBA2 does Такой локальный путь подходит для разработки, но не для CI или развёртывания. При сборке Docker-образа устанавливается зависимость из `pyproject.toml`; в Container Registry отправляется готовый образ приложения. Если позже появится внутренний Python Package Registry, PLBA можно будет публиковать туда как wheel и подключать по выпущенной версии.
not install or manage a database driver. The HTTP adapter uses ASGI and does
not install or manage an HTTP server.
## Composition outline ## Назначение
The application loads and validates configuration before building dependent PLBA v2 — независимая от транспорта библиотека Python для управления жизненным циклом приложения, worker-ами, общей проверкой состояния, снимками конфигурации, workflow, бизнес-трассировкой и структурированными техническими логами. Она устанавливается как отдельный Python-пакет с именем `plba-v2`.
components. It supplies a decoder for its own typed fields:
Приложение владеет точкой входа и composition root, бизнес-логикой, HTTP host и listener, схемой БД и миграциями, а также очередями сообщений. PLBA v2 предоставляет компоненты и адаптеры для сборки приложения, но не запускает отдельный сервис и не открывает дополнительный HTTP-порт.
## Возможности
- `runtime/application-identity` определяет `application_id` из `config.yaml`, затем из `[project].name` в `pyproject.toml`, а при отсутствии этих значений создаёт UUIDv4.
- `runtime/worker` регистрирует worker-ы с уникальными именами, применяет флаг `disabled`, выполняет последовательные циклы по расписанию, объединяет прикладное и автоматическое состояние health и поддерживает штатную и принудительную остановку.
- `runtime/application-lifecycle` запускает и останавливает все включённые worker-ы и сообщает состояние жизненного цикла приложения.
- `health/aggregation` объединяет состояния worker-ов и дополнительных компонентов с учётом критичности, отсутствующих компонентов и состояния приложения.
- `api/http/control-api` — подключаемый ASGI-адаптер для `GET /health`, `POST /runtime/start`, `POST /runtime/stop` и `GET /runtime/status`.
- `configuration/application-config-file` загружает типизированную конфигурацию приложения из корневого `config.yaml` и атомарно применяет корректные обновления без перезапуска.
- `configuration/application-settings` предоставляет типизированный `SettingsReader` и PostgreSQL-адаптер для принадлежащей приложению таблицы `settings`.
- `workflow/orchestration` выполняет именованные шаги по объявленным переходам и сохраняет снимки запуска и шагов через порт, реализуемый приложением.
- `observability/business-tracing` предоставляет контракты трассировки и PostgreSQL writer для принадлежащих приложению таблиц `trace_contexts` и `trace_messages`.
- `observability/technical-logging` формирует JSON-записи технических логов с идентификаторами приложения и бизнес-трассы и направляет их в stdout.
## Сборка приложения
Приложение загружает и проверяет конфигурацию до создания зависимых компонентов. Оно передаёт загрузчику типизированный decoder для собственных полей:
```python ```python
config_loader = ApplicationConfigLoader( config_loader = ApplicationConfigLoader(
@@ -66,29 +79,23 @@ supervisor = WorkerSupervisor(workers, config_manager)
runtime = ApplicationRuntime(runtime_context, supervisor) runtime = ApplicationRuntime(runtime_context, supervisor)
``` ```
The application creates its HTTP host and mounts `ControlApi` on the same Приложение создаёт собственный HTTP host и подключает `ControlApi` к тому же listener. `RuntimeHealthInputProvider` связывает runtime, supervisor worker-ов и зарегистрированные health-компоненты с `HealthAggregator`. Приложение само запускает сервер и определяет, когда вызвать `runtime.start()` и `runtime.stop()`.
listener. `RuntimeHealthInputProvider` connects the runtime, worker supervisor,
and registered health contributors to `HealthAggregator`. The application
starts its own server and chooses when to call `runtime.start()` and
`runtime.stop()`.
For configuration changes, run `config_manager.watch(...)` in an application Чтобы применять изменения конфигурации, запустите `config_manager.watch(...)` как задачу приложения и обработайте ошибки перезагрузки в переданном callback. Уже выданные снимки конфигурации остаются неизменными; при некорректном обновлении активным остаётся последний корректный снимок.
task and handle reload errors in the supplied callback. Existing snapshots
remain stable; an invalid update leaves the latest valid snapshot active.
## Database ownership ## Владение базой данных
The application creates and seeds `settings` in its migrations. It also creates Приложение создаёт таблицу `settings` и начальные значения в своих миграциях. Там же оно создаёт таблицы `trace_contexts` и `trace_messages`. PLBA v2 не создаёт таблицы, не запускает миграции приложения, не копирует YAML в БД, не предоставляет API бизнес-истории, не публикует бизнес-события в RabbitMQ и не предоставляет общую очередь рабочих сообщений.
`trace_contexts` and `trace_messages` in its migrations. PLBA2 does not create
tables, run application migrations, copy YAML into the database, expose a
business-history API, publish business events to RabbitMQ, or provide shared
worker-message queues. See [database contracts](docs/database-contracts.md) and
[configuration](docs/configuration.md) for the consumer-facing contracts.
See [integration guidance](docs/integration.md) for wiring the HTTP, database,
workflow, trace, and logging adapters into an application.
## Development Контракты таблиц описаны в [документе о БД](docs/database-contracts.md), правила конфигурации — в [документе о конфигурации](docs/configuration.md). Подключение HTTP, DB, workflow, трассировки и логов описано в [руководстве по интеграции](docs/integration.md).
PostgreSQL-адаптерам приложение передаёт собственные pool и schema. PLBA v2 не устанавливает и не управляет драйвером PostgreSQL. HTTP-адаптер использует ASGI и не устанавливает и не запускает HTTP-сервер.
## Разработка PLBA v2
Из корня репозитория установите библиотеку в editable-режиме вместе с тестовыми зависимостями:
```bash ```bash
python3 -m pytest python -m pip install -e ".[test]"
python -m pytest
``` ```