Files
plba_v2/README.md
T
2026-10-10 19:36:32 +03:00

95 lines
4.1 KiB
Markdown

# 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.
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.
## Capabilities
- `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.
## Install
```bash
pip install .
```
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.
## Composition outline
The application loads and validates configuration before building dependent
components. It supplies a decoder for its own typed fields:
```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)
```
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()`.
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.
## 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.
## Development
```bash
python3 -m pytest
```