PLBA2-2. Правка readme.md
This commit is contained in:
@@ -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
|
||||
|
||||
- `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.
|
||||
|
||||
## Install
|
||||
1. Отправьте нужный коммит PLBA в публичный репозиторий. В checkout PLBA получите его полный SHA:
|
||||
|
||||
```bash
|
||||
pip install .
|
||||
git rev-parse HEAD
|
||||
```
|
||||
|
||||
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.
|
||||
2. Добавьте PLBA в зависимости нового приложения в его `pyproject.toml`, подставив полученный SHA:
|
||||
|
||||
## Composition outline
|
||||
```toml
|
||||
[project]
|
||||
name = "my-application"
|
||||
dependencies = [
|
||||
"plba-v2 @ git+https://git.lesha.spb.ru/infra/plba_v2.git@<ПОЛНЫЙ_SHA_КОММИТА>",
|
||||
]
|
||||
```
|
||||
|
||||
The application loads and validates configuration before building dependent
|
||||
components. It supplies a decoder for its own typed fields:
|
||||
Репозиторий открыт, поэтому установка по 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
|
||||
python -m pip install -e ../plba_v2
|
||||
```
|
||||
|
||||
Такой локальный путь подходит для разработки, но не для CI или развёртывания. При сборке Docker-образа устанавливается зависимость из `pyproject.toml`; в Container Registry отправляется готовый образ приложения. Если позже появится внутренний Python Package Registry, PLBA можно будет публиковать туда как wheel и подключать по выпущенной версии.
|
||||
|
||||
## Назначение
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user