PLBA2-2. Реализация

This commit is contained in:
2026-10-10 19:36:32 +03:00
parent 473cde126f
commit 71998a6b13
120 changed files with 3675 additions and 21 deletions
+40
View File
@@ -0,0 +1,40 @@
# Application configuration
PLBA2 reads `config.yaml` from the application root. The application supplies a
typed decoder for its own fields; PLBA2 validates the common identity and worker
fields and keeps the application model in the same snapshot.
```yaml
application_id: inventory-service
workers:
inventory_sync:
disabled: false
interval_seconds: 60
cleanup:
pause_seconds: 300
database_url: "..."
```
`application_id` is optional. A non-empty value is used unchanged; otherwise
identity resolution uses `[project].name` from `pyproject.toml`, then a UUIDv4.
The resolved value is passed to `ApplicationRuntime` through `RuntimeContext`
before dependent components start.
Each worker entry may set `disabled` (default `false`) and one schedule:
`interval_seconds` or `pause_seconds`. Enabled workers need exactly one positive
finite schedule. A disabled worker is skipped at application start and does not
need a schedule. Changing `disabled` takes effect on the next application start;
valid schedule updates are used when the next worker cycle is planned.
The application defines every other YAML field and its typed model. This file is
for rarely changed technical parameters. Business parameters, feature toggles,
and technical values that must change remotely while the process is running
belong in the application-owned `settings` table, read through `SettingsReader`.
Load and validate the initial file before starting dependent components. A
missing, malformed, or invalid initial file raises `ApplicationConfigLoadError`
and blocks startup. After startup, `ApplicationConfigManager.watch` checks for
file changes. It swaps in a fully validated snapshot atomically; previously
returned snapshots remain unchanged. If an update is invalid or unreadable,
`reload_if_changed` returns a failure and the manager keeps the last valid
snapshot. The watcher passes that error to the application's callback.
+77
View File
@@ -0,0 +1,77 @@
# Database contracts
PLBA2 reads and writes application-owned tables through adapters. The application
owns the schema, migrations, initial values, and retention policy. PLBA2 does not
create tables or run migrations.
## `settings`
The application creates `settings` in its own schema and loads initial rows in
its migration. The table has this contract:
| Field | Type | Constraints | Purpose |
| --- | --- | --- | --- |
| `id` | `BIGINT` | Identity primary key, not null | Row identifier and final ordering key |
| `config_key` | `VARCHAR(128)` | Nullable | Application-defined scope or entity |
| `setting_key` | `VARCHAR(128)` | Not null | Stable setting name |
| `setting_value` | `TEXT` | Not null | Text value decoded by the application |
| `sort_order` | `INT` | Not null, default `0` | Order for repeated keys |
| `is_enabled` | `BOOLEAN` | Not null, default `TRUE` | Includes or excludes a row from reads |
| `description` | `TEXT` | Nullable | Human-readable explanation |
Indexes should support the adapter's filters and ordering, for example:
```sql
CREATE INDEX settings_key_enabled_order_idx
ON settings (setting_key, is_enabled, sort_order, id);
CREATE INDEX settings_scope_lookup_order_idx
ON settings (setting_key, config_key, is_enabled, sort_order, id);
```
There is no uniqueness constraint on `setting_key`; several enabled rows may
form an ordered list. Reads filter by `setting_key`, an optional `config_key`,
and `is_enabled = TRUE`, then order by `sort_order`, `id`. The value of a feature
toggle belongs in `setting_value`; `is_enabled` only controls whether the row is
read. `config_key` relationships are owned by the application.
`settings` stores business parameters, feature toggles, and technical values
that must change remotely while the process runs. Rarely changed technical
parameters remain in the root `config.yaml`; PLBA2 does not copy YAML into the
database.
## `trace_contexts` and `trace_messages`
The application creates both trace tables in its own schema through its own
migration. Public code calls the context identifier `business_trace_id`; both
tables store it as `trace_id`.
`trace_contexts` contains:
| Field | Type | Constraints | Purpose |
| --- | --- | --- | --- |
| `trace_id` | `UUID` | Primary key, not null | Public `business_trace_id` |
| `parent_id` | `UUID` | Nullable | Parent context identifier |
| `alias` | `TEXT` | Not null | Short context name |
| `trace_type` | `TEXT` | Not null | Business operation type |
| `event_time` | `TIMESTAMPTZ` | Not null | Context creation time |
| `attrs_json` | `JSONB` | Not null | Context attributes, including `application_id` |
Create indexes on `parent_id` and `event_time`.
`trace_messages` contains:
| Field | Type | Constraints | Purpose |
| --- | --- | --- | --- |
| `id` | `BIGINT` | Identity primary key, not null | Message identifier |
| `trace_id` | `UUID` | Not null, references `trace_contexts.trace_id` with `ON DELETE CASCADE` | Owning context |
| `event_time` | `TIMESTAMPTZ` | Not null | Message time |
| `step` | `TEXT` | Not null | Business step name |
| `status` | `TEXT` | Not null | Step result |
| `level` | `TEXT` | Not null | Business message level |
| `message` | `TEXT` | Not null | Human-readable business message |
| `attrs_json` | `JSONB` | Not null | Message attributes, including `application_id` |
Create indexes on `trace_id`, `event_time`, and `status`. The PostgreSQL
adapter only inserts rows, adds the runtime `application_id` to each
`attrs_json`, and passes database failures to the application. It does not
create tables, run migrations, publish RabbitMQ events, or expose a history API.
+52
View File
@@ -0,0 +1,52 @@
# 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](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.