@@ -1,214 +1,319 @@
# PLBA
`PLBA` (`Platform Runtime for Business Applications` ) - runtime для бизнес-приложений.
## 1. Назначение платформы
`Platform Runtime for Business Applications` ) - это runtime-слой для бизнес-приложений, который забирает на себя инфраструктурную часть исполнения. Платформа стандартизирует запуск и остановку рабочих процессов, контроль состояния приложения и эксплуатационные сервисы вокруг них. З а а `ApplicationModule` , `Worker` и прикладной `Routine` , где каждый уровень отвечает за свою часть ответственности. В
Платформа берет на себя инфраструктурные обязанности:
- lifecycle приложения
- запуск и остановку воркеров
- health/status
- tracing
- logging
- control plane
- загрузку конфигурации
## 2. Концепция использования
`ApplicationModule` - точка сборки приложения: здесь создаются зависимости, собираются рутины, создаются воркеры и регистрируются дополнительные health-контрибьюторы.
Бизнес-приложение на базе `plba` собирается вокруг трех уровней:
- `ApplicationModule` собирает приложение и регистрирует воркеры
- `Worker` управляет исполнением и lifecycle
- `Routine` реализует бизнес-функцию
`Worker` - основной runtime-контракт платформы: он управляет исполнением (потоки, цикл, стратегия остановки), возвращает `health()` и `status()` , а
`Routine` не является контрактом `plba` . Это рекомендуемый архитектурный паттерн для прикладного кода .
`Routine` - прикладной паттерн (не обязательный контракт платформы): класс или набор классов, где сосредоточена бизнес-логика, которую воркер регулярно или однократно запускает .
Правила построения приложений на платформе собраны отдельно в [application_guidelines.md ](/Users/alex/Dev_projects_v2/apps/plba/requirements/application_guidelines.md ).
Вспомогательные сервисы платформы дополняют core-модель:
- `tracing` (`TraceService` , транспорты) - операционная трассировка контекстов и сообщений.
- `logging` (`LogManager` ) - применение конфигурации логирования из runtime-конфига.
- `health` (`HealthRegistry` ) - агрегирование здоровья воркеров и дополнительных компонентов.
- `workflow` (`WorkflowEngine` и persistence-слой) - исполнение шагов бизнес-процесса с
- `control plane` (`ControlPlaneService` , `HttpControlChannel` ) - внешние health/action endpoints.
- `queue` (`InMemoryTaskQueue` ) - локальный in-memory буфер как утилита прикладного уровня.
## Installation
## 3. Архитектура
``` mermaid
class ApplicationModule {
<<abstract>>
+name: str
+register(registry)
}
class ModuleRegistry {
+add_worker(worker)
+add_health_contributor(contributor)
+register_module(name)
}
class RuntimeManager {
+register_module(module)
+add_config_file(path)
+start()
+stop(timeout, force)
+status()
+current_health()
}
class WorkerSupervisor {
+register(worker)
+start()
+stop(timeout, force)
+statuses()
+healths()
}
class Worker {
<<abstract>>
+name: str
+critical: bool
+start()
+stop(force)
+health()
+status()
}
class Routine {
<<pattern>>
+run()
}
Установка `plba` через `pip` из git-репозитория:
class ConfigurationManager
class LogManager
class HealthRegistry
class TraceService
class ControlPlaneService
class WorkflowRuntimeFactory
class WorkflowEngine
class WorkflowPersistence
class WorkflowRepository
class CheckpointRepository
class InMemoryTaskQueue
class MySqlTraceTransport
``` bash
"plba @ git+https://git.lesha.spb.ru/alex/plba.git"
ApplicationModule --> ModuleRegistry : register(...)
RuntimeManager --> ApplicationModule : register_module(...)
RuntimeManager --> ModuleRegistry
RuntimeManager --> ConfigurationManager
RuntimeManager --> LogManager
RuntimeManager --> HealthRegistry
RuntimeManager --> TraceService
RuntimeManager --> WorkerSupervisor
RuntimeManager --> ControlPlaneService
WorkerSupervisor --> Worker
Worker --> Routine : invokes
WorkflowRuntimeFactory --> WorkflowEngine : create_engine(...)
WorkflowEngine --> WorkflowPersistence
WorkflowPersistence --> WorkflowRepository
WorkflowPersistence --> CheckpointRepository
TraceService --> MySqlTraceTransport
```
## Runtime model
## 4. Описание компонентов
1. приложение объявляет `ApplicationModule`
2. модуль регистрирует один или несколько `Worker`
3. `RuntimeManager` запускает все воркеры
4. каждый `Worker` запускает свою бизнес-активность
5. runtime агрегирует health и status
6. runtime останавливает воркеры graceful или forcefully
### 4.1 Core модули
## Main contracts
#### ApplicationModule
- Назначение: композиция прикладного приложения и регистрация runtime-компонентов.
- Реализация: контракт `app_runtime.contracts.application.ApplicationModule` , регистрация через `app_runtime.core.registration.ModuleRegistry` .
- Как работает / API / вызовы / таблицы:
- API: `name` , `register(registry)` .
- Типичные вызовы: `registry.add_worker(worker)` , `registry.add_health_contributor(contributor)` .
- `RuntimeManager.register_module()` вызывает `module.register(...)` и добавляет имя модуля в снимок runtime.
- В
- Типовая схема использования:
- Создать инфраструктурные и доменные сервисы.
- Создать `Routine` .
- Создать `Worker` с
- Зарегистрировать воркер и опциональные health contributors.
### `ApplicationModule`
#### Worker
- Назначение: runtime-исполнение бизнес-активности, управление lifecycle, интерпретация health/status.
- Реализация: контракт `app_runtime.contracts.worker.Worker` , оркестрация через `app_runtime.workers.supervisor.WorkerSupervisor` .
- Как работает / API / вызовы / таблицы:
- API: `start()` , `stop(force=False)` , `health() -> WorkerHealth` , `status() -> WorkerStatus` , свойства `name` , `critical` .
- `WorkerSupervisor.start()` запускает все воркеры, `stop()` останавливает и ждет state=`stopped` .
- `RuntimeManager` получает агрегированные `statuses()` /`healths()` у
- В
- Типовая схема использования:
- Внутри `start()` поднимать поток/пул или запускать одноразовую задачу.
- В `routine.run()` .
- Ошибки бизнес-логики транслировать в `health()` /`status()` .
Описывает, из чего состоит приложение.
#### Routine
- Назначение: изоляция прикладной бизнес-логики от runtime-обвязки.
- Реализация: прикладной класс (паттерн), обычно с `run()` ; платформой не навязывается отдельный интерфейс.
- Как работает / API / вызовы / таблицы:
- Типичный API: `run()` + дополнительные domain-методы.
- Вызывается воркером в выбранной стратегии выполнения (single-run/loop, 1..N потоков).
- Может вызывать сервисы интеграций, workflow, очереди, доменные репозитории.
- Запись в таблицы определяется прикладными сервисами, а
- Типовая схема использования:
- Оставлять рутину тонким оркестратором бизнес-действий.
- Сложную логику выносить в отдельные доменные сервисы.
Ответственность:
- дать имя модуля
- зарегистрировать воркеры
- зарегистрировать health contributors при необходимости
- собрать прикладные зависимости
### 4.2 Service модули
### `Worker`
#### Configuration
- Назначение: централизованная загрузка и слияние runtime-конфигурации.
- Реализация: `ConfigurationManager` , `FileConfigProvider` , `ConfigFileLoader` .
- Как работает / API / вызовы / таблицы:
- API: `add_provider()` , `load()` , `reload()` , `get()` , `section()` .
- `RuntimeManager.start()` вызывает `configuration.load()` .
- Поддерживается YAML/JSON через `ConfigFileLoader.parse()` .
- В
- Типовая схема использования:
- В `runtime.add_config_file("config.yml")` .
- Читать секции из `runtime.configuration.section("...")` в прикладных фабриках.
Главный runtime-контракт платформы.
#### Logging
- Назначение: применение и восстановление валидной конфигурации логирования.
- Реализация: `LogManager` .
- Как работает / API / вызовы / таблицы:
- API: `apply_config(config)` .
- `RuntimeManager.start()` вызывает `logs.apply_config(config)` .
- Если секция `log` некорректна, сервис пытается восстановить предыдущую валидную конфигурацию.
- В
- Типовая схема использования:
- Передать `log` секцию в конфиг и запускать runtime стандартно через `start()` .
Контракт:
- `name`
- `critical `
- `start()`
- `stop(force=False )`
- `health()`
- `status( )`
`Worker` отвечает только за runtime-поведее
- как запускается бизнес-активность
- в одном потоке или нескольких
- single-run или loop
- graceful shutdown
- интерпретацию ошибок в `health/status`
### `Routine`
Рекомендуемый application-level паттерн.
`Routine` описывает бизнес-функцию:
- что читать
- какие сервисы вызывать
- какие бизнес-решения принимать
- что сохранять или отправлять наружу
Обычно воркер получает одну routine через конструктор и вызывает е е `start()` или во внутренних helper-методах.
## Minimal example
#### Health
- Назначение: сводный health приложения по воркерам и дополнительным контрибьюторам.
- Реализация: `HealthRegistry` + контрибьюторы по контракту `HealthContributor ` .
- Как работает / API / вызовы / таблицы:
- API: `register()` , `snapshot(worker_healths)` , `payload(state, worker_healths )` .
- Агрегация: `unhealthy` при критичном `unhealthy` , `degraded` при любой деградации, иначе `ok` .
- `RuntimeManager.current_health()` использует `HealthRegistry.payload(... )` .
- В
- Типовая схема использовая :
- Зарегистрировать contributor в `ApplicationModule.register(...)` .
- Отдавать health наружу через control plane `/health` .
#### Tracing
- Назначение: фиксация контекстов выполнения и событий по шагам операций.
- Реализация: `TraceService` , `TraceContextStore` , `NoOpTraceTransport` , `MySqlTraceTransport` .
- Как работает / API / вызовы / таблицы:
- API: `create_context()` , `open_context()` , `step()` , `info()/warning()/error()/exception()` , `new_root()` , `child_of()` , `attach()` , `resume()` .
- `TraceService` пишет записи через transport; ошибки транспорта изолируются в логах.
- При `MySqlTraceTransport` записи идут в таблицы:
- `trace_contexts`
- `trace_messages`
- Эталонная схема и migration для MySQL: `requirements/sql/trace_mysql_schema.sql` .
- Trace Context:
- Что это: запись о
- Для чего нужен: позволяет собрать дерево исполнения и связать все сообщения конкретной бизнес-операции.
- Атрибуты контекста (`TraceContextRecord` ): `trace_id` , `alias` , `parent_id` , `type` , `event_time` , `attrs` .
- Иерархия: `parent_id` указывает на родительский контекст; так строится цепочка root -> child.
- Таблица: `trace_contexts` .
- Как объявляется в коде:
``` python
from threading import Event , Lock , Thread
from time import sleep
with traces . open_context ( alias = " orders-worker " , kind = " worker " , attrs = { " routine " : " orders " } ) as trace_id :
. . .
```
``` python
root = traces . new_root ( " orders.sync " )
child = traces . child_of ( root , " orders.process_batch " )
```
- Trace Message:
- Что это: событие внутри активного context (статус шага, предупреждение, ошибка, служебная информация).
- Роль `step` : текущая стадия операции (`parse` , `validate` , `persist` и т.д.), которую выставляют через `traces.step("...")` .
- Уровни сообщений: `INFO` , `WARNING` , `ERROR` ; `exception(...)` пишет сообщение уровня `ERROR` .
- Атрибуты сообщения (`TraceLogMessage` ): `trace_id` , `step` , `status` , `message` , `level` , `event_time` , `attrs` .
- Связь с с `trace_id` ; без активного контекста `TraceService` выбрасывает ошибку.
- Таблица: `trace_messages` .
- Как правильно применять в проекте:
- Открывать один root-context на единицу бизнес-работы (например, обработка одного сообщения/заказа).
- Перед важными этапами явно менять `step` .
- `info` использовать для нормального прогресса, `warning` для recoverable ситуаций (retry/fallback), `error` /`exception` для сбоев.
- В `attrs` класть диагностические ключи (`entity_id` , `attempt` , `integration` , `duration_ms` ), чтобы ускорить расследование инцидентов.
- Типовая схема использования:
- В `open_context` ) и на каждом шаге рутины писать `step()/info()` .
from plba import (
ApplicationModule ,
Worker ,
WorkerHealth ,
WorkerStatus ,
create_runtime ,
)
#### Workflow
- Назначение: исполнение step-based workflow с
- Реализация: `WorkflowRuntimeFactory` , `WorkflowEngine` , `WorkflowPersistence` , `WorkflowRepository` , `CheckpointRepository` .
- Как работает / API / вызовы / таблицы:
- API верхнего уровня: `WorkflowRuntimeFactory.create_engine(workflow)` , `WorkflowEngine.run(context)` .
- `WorkflowEngine` по шагам вызывает `WorkflowStep.run(context)` , применяет `TransitionResolver` , вызывает hooks.
- `WorkflowPersistence` пишет состояние run/step/checkpoint через репозитории.
- При настроенном подключении к БД записи идут в таблицы:
- `workflow_runs`
- `workflow_steps`
- `workflow_checkpoints`
- Без подключения работает in-memory fallback репозиториев.
- Типовая схема использования:
- Описать `WorkflowDefinition` (узлы и transitions).
- Создать engine через фабрику.
- Запускать из рутины или воркера: `engine.run(context)` .
#### Control Plane
- Назначение: внешний канал управления runtime и чтения health/status.
- Реализация: `ControlPlaneService` , `HttpControlChannel` , `HttpControlAppFactory` .
- Как работает / API / вызовы / таблицы:
- API: `register_channel()` , `start(runtime)` , `stop()` , `snapshot(runtime)` .
- HTTP-канал поднимает endpoint'ы:
- `GET /health`
- `GET|POST /actions/{action}` (`start` , `stop` , `status` )
- Колбэки action'ов вызывают async-методы `RuntimeManager` .
- В
- Типовая схема использования:
- При создании runtime включить `enable_http_control=True` .
- Использовать `/health` для readiness/liveness и `/actions/*` для операционного контроля.
#### Queue
- Назначение: простой in-memory буфер задач/сообщений внутри приложения.
- Реализация: `InMemoryTaskQueue[T]` .
- Как работает / API / вызовы / таблицы:
- API: `put(item)` , `get(timeout)` , `task_done()` , `qsize()` , `stats()` .
- Может использоваться между воркерами/сервисами как локальная очередь.
- В
- Типовая схема использования:
- Producer в рутине кладет элементы через `put` .
- Consumer-воркер извлекает через `get(timeout)` и обрабатывает.
## 5. MVP бизнес-приложения
1. Создать один `ApplicationModule` .
2. В `Routine` и один `Worker` (1 worker -> 1 routine).
3. Зарегистрировать воркер через `registry.add_worker(...)` .
4. Создать runtime: `create_runtime(module, config_path="config.yml")` .
5. Вызвать `runtime.start()` .
Минимальный пример:
``` python
from plba import ApplicationModule , Worker , WorkerHealth , WorkerStatus , create_runtime
from app_runtime . core . registration import ModuleRegistry
class Orders Routine:
def __init__ ( self , service ) - > None :
self . _service = service
class Demo Routine:
def run ( self ) - > None :
self . _service . process_new_orders ( )
print ( " business action " )
class Orders Worker( Worker ) :
def __init__ ( self , routine : Orders Routine, interval : float = 1.0 - > None :
class Demo Worker( Worker ) :
def __init__ ( self , routine : Demo Routine) - > None :
self . _routine = routine
self . _interval = interval
self . _thread : Thread | None = None
self . _stop_requested = Event ( )
self . _lock = Lock ( )
self . _in_flight = 0
self . _failures = 0
self . _started = False
@property
def name ( self ) - > str :
return " orders -worker"
return " demo -worker"
@property
def critical ( self ) - > bool :
return True
def start ( self ) - > None :
if self . _thread and self . _thread . is_alive ( ) :
return
self . _stop_requested . clear ( )
self . _thread = Thread ( target = self . _run_loop , daemon = True )
self . _thread . start ( )
self . _started = True
self . _routine . run ( )
def stop ( self , force : bool = False ) - > None :
del force
self . _stop_requested . set ( )
self . _started = False
def health ( self ) - > WorkerHealth :
if self . _failures > 0 :
return WorkerHealth ( self . name , " degraded " , self . critical )
return WorkerHealth ( self . name , " ok " , self . critical )
return WorkerHealth ( name = self . name , status = " ok " , critical = self . critical )
def status ( self ) - > WorkerStatus :
aliv e = self . _thread is not None and self . _thread . is_alive ( )
state = " busy " if self . _in_flight else " idle "
if not alive :
state = " stopped "
elif self . _stop_requested . is_set ( ) :
state = " stopping "
return WorkerStatus ( name = self . name , state = state , in_flight = self . _in_flight )
def _run_loop ( self ) - > None :
while not self . _stop_requested . is_set ( ) :
with self . _lock :
self . _in_flight + = 1
try :
self . _routine . run ( )
except Exception :
self . _failures + = 1
finally :
with self . _lock :
self . _in_flight - = 1
sleep ( self . _interval )
return WorkerStatus ( nam e= self . name , state = " idle " if self . _started else " stopped " )
class Orders Module( ApplicationModule ) :
class Demo Module( ApplicationModule ) :
@property
def name ( self ) - > str :
return " orders "
return " demo "
def register ( self , registry ) - > None :
service = OrderService ( )
routine = OrdersRoutine ( service )
registry . add_worker ( OrdersWorker ( routine ) )
def register ( self , registry : ModuleRegistry - > None :
registry . add_worker ( DemoWorker ( DemoRoutine ( ) ) )
runtime = create_runtime ( Orders Module( ) , config_path = " config.yml " )
runtime = create_runtime ( Demo Module( ) , config_path = " config.yml " )
runtime . start ( )
```
## Health and status
Практика такая:
- `Routine` выполняет бизнес-работу
- `Worker` ловит е е
- `Worker` интерпретирует outcome в `health()` и `status()`
Т о
## In-memory queue
`InMemoryTaskQueue` остается в платформе как простой in-memory utility.
Это не базовый платформенный контракт и не обязательный паттерн архитектуры.
Е е
``` python
from plba import InMemoryTaskQueue
queue = InMemoryTaskQueue [ str ] ( )
queue . put ( " payload " )
item = queue . get ( timeout = 0.1 )
```
## Public API
Основные публичные сущности:
- `ApplicationModule`
- `Worker`
- `WorkerHealth`
- `WorkerStatus`
- `RuntimeManager`
- `WorkerSupervisor`
- `TraceService`
- `HealthRegistry`
- `InMemoryTaskQueue`
- `create_runtime(...)`
Для production-сценария после MVP обычно добавляют `tracing` , `health contributors` , `workflow` и HTTP control plane, но базовый запуск не требует этих расширений.
