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

2.5 KiB

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.

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.