Files
plba_v2/docs/integration.md
T
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

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/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.

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.