Files
plba_v2/README.md
T
alex d46993a092
PLBA package CI / Python tests (push) Successful in 23s
PLBA package CI / Package version increment (push) Skipped
PLBA2-4. Доработка регистрации http эндпоинтов
2026-10-11 10:44:59 +03:00

10 KiB
Raw Blame History

PLBA v2

Подключение PLBA v2 к приложению

PLBA v2 подключается к Python-приложению как библиотека. Отдельный Docker-образ PLBA собирать и публиковать не нужно: образ приложения будет содержать само приложение и установленную библиотеку.

  1. Отправьте нужный коммит PLBA в публичный репозиторий. В checkout PLBA получите его полный SHA:

    git rev-parse HEAD
    
  2. Добавьте PLBA в зависимости нового приложения в его pyproject.toml, подставив полученный SHA:

    [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. Из корня репозитория приложения установите его зависимости:

    python -m pip install -e .
    

    Для установки Git-зависимости в среде сборки должен быть доступен Git. После установки импортируйте компоненты библиотеки из пространства имён plba, например from plba.runtime import ApplicationRuntime. Если ваш менеджер пакетов создаёт lock-файл, сохраните его в репозитории приложения и используйте при установке зависимостей в CI и Docker-сборке.

При разработке PLBA и приложения на одной машине можно временно установить библиотеку из соседнего checkout:

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 /api/v1/health, POST /api/v1/runtime/start, POST /api/v1/runtime/stop и GET /api/v1/runtime/status; приложение может передать ему собственные HttpRoute для той же маршрутизации.
  • 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 для собственных полей:

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. Встроенные endpoints PLBA и переданные через application_routes прикладные HttpRoute доступны через общий API; каждый путь начинается с /api/v{version}/. RuntimeHealthInputProvider связывает runtime, supervisor worker-ов и зарегистрированные health-компоненты с HealthAggregator. Приложение само запускает сервер и определяет, когда вызвать runtime.start() и runtime.stop().

Чтобы применять изменения конфигурации, запустите config_manager.watch(...) как задачу приложения и обработайте ошибки перезагрузки в переданном callback. Уже выданные снимки конфигурации остаются неизменными; при некорректном обновлении активным остаётся последний корректный снимок.

Владение базой данных

Приложение создаёт таблицу settings и начальные значения в своих миграциях. Там же оно создаёт таблицы trace_contexts и trace_messages. PLBA v2 не создаёт таблицы, не запускает миграции приложения, не копирует YAML в БД, не предоставляет API бизнес-истории, не публикует бизнес-события в RabbitMQ и не предоставляет общую очередь рабочих сообщений.

Контракты таблиц описаны в документе о БД, правила конфигурации — в документе о конфигурации. Подключение HTTP, DB, workflow, трассировки и логов описано в руководстве по интеграции.

PostgreSQL-адаптерам приложение передаёт собственные pool и schema. PLBA v2 не устанавливает и не управляет драйвером PostgreSQL. HTTP-адаптер использует ASGI и не устанавливает и не запускает HTTP-сервер.

Разработка PLBA v2

Из корня репозитория установите библиотеку в editable-режиме вместе с тестовыми зависимостями:

python -m pip install -e ".[test]"
python -m pytest