98 lines
3.7 KiB
Markdown
98 lines
3.7 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`.
|
|
|
|
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:
|
|
|
|
```python
|
|
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/health`
|
|
- `POST /api/v1/runtime/start`
|
|
- `POST /api/v1/runtime/stop`
|
|
- `GET /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](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.
|