PLBA2-2. Реализация
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user