53 lines
2.5 KiB
Markdown
53 lines
2.5 KiB
Markdown
# Integrating PLBA2
|
|
|
|
The application keeps its entrypoint and composes the library before it starts
|
|
its own HTTP host. The root `config.yaml` must load successfully before
|
|
dependent components are created.
|
|
|
|
## HTTP, runtime, and health
|
|
|
|
Register `WorkerDefinition` objects in a `WorkerRegistry`, pass the registry and
|
|
`ApplicationConfigManager` to `WorkerSupervisor`, resolve an
|
|
`ApplicationIdentityResolver` result into `RuntimeContext`, and construct
|
|
`ApplicationRuntime`. Register non-worker checks in `HealthContributorRegistry`
|
|
and connect it to `HealthAggregator` with `RuntimeHealthInputProvider`.
|
|
|
|
Mount `ControlApi(runtime, health_aggregator)` in the application's ASGI host.
|
|
The host owns the socket and listener; the adapter contributes `/health`,
|
|
`/runtime/start`, `/runtime/stop`, and `/runtime/status` to that same listener.
|
|
The application chooses when to start and stop the runtime.
|
|
|
|
## Configuration and settings
|
|
|
|
Pass an application decoder to `ApplicationConfigLoader`. Its typed model
|
|
validates application-specific fields while PLBA2 validates `application_id`
|
|
and worker settings. `ApplicationConfigManager` implements
|
|
`WorkerConfigReader`; its watcher atomically swaps valid snapshots and passes
|
|
reload failures to the application's callback.
|
|
|
|
Create `settings` and seed its initial values in an application migration. Pass
|
|
the application's pool and schema to `PostgresSettingsRepository`, then expose
|
|
it through `SettingsReader` and typed `SettingKey` definitions. The adapter
|
|
filters enabled rows and returns values in `sort_order`, `id` order. The full
|
|
schema contract is in [database-contracts.md](database-contracts.md).
|
|
|
|
## Workflow and business trace
|
|
|
|
Define a `WorkflowDefinition` from named `WorkflowNode` objects and explicit
|
|
transition maps. Give `WorkflowEngine` an application-owned implementation of
|
|
`WorkflowPersistence`; that adapter decides how and where to store snapshots.
|
|
PLBA2 does not connect workflow persistence to a database itself.
|
|
|
|
Create `trace_contexts` and `trace_messages` in the application's migrations.
|
|
Pass the application's pool, schema, and resolved application ID to
|
|
`PostgresBusinessTraceWriter`. Bind the public trace ID with
|
|
`business_trace_context(trace_id)` around async business work so technical logs
|
|
inherit it.
|
|
|
|
## Technical logs
|
|
|
|
Attach `create_stdout_handler(runtime_context.application_id)` to the
|
|
application's logger. It uses the standard library `StreamHandler` and emits
|
|
one JSON object per record. The platform remains responsible for log delivery
|
|
and retention.
|