# PLBA v2 ## Подключение PLBA v2 к приложению PLBA v2 подключается к Python-приложению как библиотека. Отдельный Docker-образ PLBA собирать и публиковать не нужно: образ приложения будет содержать само приложение и установленную библиотеку. 1. Отправьте нужный коммит PLBA в публичный репозиторий. В checkout PLBA получите его полный SHA: ```bash git rev-parse HEAD ``` 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 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( Path("config.yaml"), application_decoder=ServiceConfig.from_mapping ) config_manager = ApplicationConfigManager(config_loader) initial_config = config_manager.load_initial() identity = ApplicationIdentityResolver( TomlProjectNameReader(Path("pyproject.toml")) ) runtime_context = identity.resolve(initial_config.application_id) workers = WorkerRegistry() workers.register(WorkerDefinition("inventory_sync", sync_inventory)) supervisor = WorkerSupervisor(workers, config_manager) runtime = ApplicationRuntime(runtime_context, supervisor) ``` Приложение создаёт собственный HTTP host и подключает `ControlApi` к тому же listener. `RuntimeHealthInputProvider` связывает runtime, supervisor worker-ов и зарегистрированные health-компоненты с `HealthAggregator`. Приложение само запускает сервер и определяет, когда вызвать `runtime.start()` и `runtime.stop()`. Чтобы применять изменения конфигурации, запустите `config_manager.watch(...)` как задачу приложения и обработайте ошибки перезагрузки в переданном callback. Уже выданные снимки конфигурации остаются неизменными; при некорректном обновлении активным остаётся последний корректный снимок. ## Владение базой данных Приложение создаёт таблицу `settings` и начальные значения в своих миграциях. Там же оно создаёт таблицы `trace_contexts` и `trace_messages`. PLBA v2 не создаёт таблицы, не запускает миграции приложения, не копирует YAML в БД, не предоставляет API бизнес-истории, не публикует бизнес-события в RabbitMQ и не предоставляет общую очередь рабочих сообщений. Контракты таблиц описаны в [документе о БД](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 python -m pip install -e ".[test]" python -m pytest ```