3.7 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.
Register application endpoints as typed HttpRoute values when composing the
ASGI application. The built-in routes and application handlers share the same
ControlApi router and listener:
import json
from plba.http import ControlApi, HttpRoute
async def get_order(scope, receive, send):
body = json.dumps({"order_id": scope["path_params"]["order_id"]}).encode()
await send(
{
"type": "http.response.start",
"status": 200,
"headers": [(b"content-type", b"application/json")],
}
)
await send({"type": "http.response.body", "body": body})
api = ControlApi(
runtime,
health_aggregator,
application_routes=(
HttpRoute("GET", "/api/v1/orders/{order_id}", get_order),
),
)
The built-in API paths are:
GET /api/v1/healthPOST /api/v1/runtime/startPOST /api/v1/runtime/stopGET /api/v1/runtime/status
Application route templates must also start with /api/v{version}/, where
{version} is a positive integer such as v1. Named path segments are
available in scope["path_params"], and the application handler owns its
response.
For platform access, the public request path is
/{service-name}/api/v{version}/.... Caddy selects the service upstream and
removes /{service-name} before proxying, so the application receives the
internal /api/v{version}/... path. The application host still owns one
socket and listener; PLBA does not start a separate HTTP server. 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.