95 lines
4.1 KiB
Markdown
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
|
|
```
|