From 295cc30eadacafa9283d8f34dca6ad04de612ff4 Mon Sep 17 00:00:00 2001 From: zosimovaa Date: Sat, 10 Oct 2026 20:23:22 +0300 Subject: [PATCH] =?UTF-8?q?PLBA2-2.=20=D0=9F=D1=80=D0=B0=D0=B2=D0=BA=D0=B0?= =?UTF-8?q?=20readme.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 119 +++++++++++++++++++++++++++++------------------------- 1 file changed, 63 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 5e43491..a681e8a 100644 --- a/README.md +++ b/README.md @@ -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 ```