10 KiB
PLBA v2
Подключение PLBA v2 к приложению
PLBA v2 подключается к Python-приложению как библиотека. Отдельный Docker-образ PLBA собирать и публиковать не нужно: образ приложения будет содержать само приложение и установленную библиотеку.
-
Отправьте нужный коммит PLBA в публичный репозиторий. В checkout PLBA получите его полный SHA:
git rev-parse HEAD -
Добавьте 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-тег только после того, как он создан и проверен. -
Из корня репозитория приложения установите его зависимости:
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