Files
alex d46993a092
PLBA package CI / Python tests (push) Successful in 23s
PLBA package CI / Package version increment (push) Skipped
PLBA2-4. Доработка регистрации http эндпоинтов
2026-10-11 10:44:59 +03:00

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.