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 is a transport-neutral Python library for application lifecycle,
workers, health aggregation, configuration snapshots, workflows, business
tracing, and structured technical logs. It is a separate package from PLBA v1.
## Подключение PLBA v2 к приложению
The application owns its entrypoint and composition root, business logic, HTTP
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.
PLBA v2 подключается к Python-приложению как библиотека. Отдельный Docker-образ PLBA собирать и публиковать не нужно: образ приложения будет содержать само приложение и установленную библиотеку.
## Capabilities
1. Отправьте нужный коммит PLBA в публичный репозиторий. В checkout PLBA получите его полный SHA:
- `runtime/application-identity` resolves `application_id` from `config.yaml`,
then `[project].name` in `pyproject.toml`, then UUIDv4.
- `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.
```bash
git rev-parse HEAD
```
## 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
pip install .
python -m pip install -e ../plba_v2
```
The PostgreSQL adapters accept the application's pool and schema. PLBA2 does
not install or manage a database driver. The HTTP adapter uses ASGI and does
not install or manage an HTTP server.
Такой локальный путь подходит для разработки, но не для CI или развёртывания. При сборке Docker-образа устанавливается зависимость из `pyproject.toml`; в Container Registry отправляется готовый образ приложения. Если позже появится внутренний Python Package Registry, PLBA можно будет публиковать туда как wheel и подключать по выпущенной версии.
## Composition outline
## Назначение
The application loads and validates configuration before building dependent
components. It supplies a decoder for its own typed fields:
PLBA v2 — независимая от транспорта библиотека Python для управления жизненным циклом приложения, worker-ами, общей проверкой состояния, снимками конфигурации, workflow, бизнес-трассировкой и структурированными техническими логами. Она устанавливается как отдельный Python-пакет с именем `plba-v2`.
Приложение владеет точкой входа и 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
config_loader = ApplicationConfigLoader(
@@ -66,29 +79,23 @@ supervisor = WorkerSupervisor(workers, config_manager)
runtime = ApplicationRuntime(runtime_context, supervisor)
```
The application creates its HTTP host and mounts `ControlApi` on the same
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()`.
Приложение создаёт собственный HTTP host и подключает `ControlApi` к тому же listener. `RuntimeHealthInputProvider` связывает runtime, supervisor worker-ов и зарегистрированные health-компоненты с `HealthAggregator`. Приложение само запускает сервер и определяет, когда вызвать `runtime.start()` и `runtime.stop()`.
For configuration changes, run `config_manager.watch(...)` in an application
task and handle reload errors in the supplied callback. Existing snapshots
remain stable; an invalid update leaves the latest valid snapshot active.
Чтобы применять изменения конфигурации, запустите `config_manager.watch(...)` как задачу приложения и обработайте ошибки перезагрузки в переданном callback. Уже выданные снимки конфигурации остаются неизменными; при некорректном обновлении активным остаётся последний корректный снимок.
## Database ownership
## Владение базой данных
The application creates and seeds `settings` in its migrations. It also creates
`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.
Приложение создаёт таблицу `settings` и начальные значения в своих миграциях. Там же оно создаёт таблицы `trace_contexts` и `trace_messages`. PLBA v2 не создаёт таблицы, не запускает миграции приложения, не копирует YAML в БД, не предоставляет API бизнес-истории, не публикует бизнес-события в RabbitMQ и не предоставляет общую очередь рабочих сообщений.
## 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
python3 -m pytest
python -m pip install -e ".[test]"
python -m pytest
```