PLBA2-2. Реализация
This commit is contained in:
@@ -1,35 +1,94 @@
|
||||
# PLBA v2
|
||||
|
||||
PLBA v2 is a compact, transport-neutral runtime for business microservices. It owns application lifecycle, worker supervision, versioned configuration snapshots, traces, structured logging, health aggregation, workflows and an optional audit port.
|
||||
PLBA v2 is a transport-neutral Python library for application lifecycle,
|
||||
workers, health aggregation, configuration snapshots, workflows, business
|
||||
tracing, and structured technical logs. It is a separate package from PLBA v1.
|
||||
|
||||
It deliberately does not own task queues, RabbitMQ clients, gRPC servers, HTTP servers, a database driver, or business logic. A service supplies those as adapters and owns its entrypoint.
|
||||
The application owns its entrypoint and composition root, business logic, HTTP
|
||||
host and listener, database schema and migrations, and message queues. PLBA2
|
||||
provides components and adapters that the application wires together; it does
|
||||
not start a service or create a second HTTP port.
|
||||
|
||||
## Status
|
||||
## Capabilities
|
||||
|
||||
This repository contains the first executable skeleton and public contracts. It is a breaking, separate package from PLBA v1; no v1 compatibility facade is provided.
|
||||
- `runtime/application-identity` resolves `application_id` from `config.yaml`,
|
||||
then `[project].name` in `pyproject.toml`, then UUIDv4.
|
||||
- `runtime/worker` registers uniquely named workers, applies the `disabled`
|
||||
flag, runs sequential scheduled cycles, combines application and automatic
|
||||
health, and supports graceful or force stop.
|
||||
- `runtime/application-lifecycle` starts and stops all enabled workers and
|
||||
reports application lifecycle states.
|
||||
- `health/aggregation` combines worker and contributor states, criticality,
|
||||
missing components, and application lifecycle into a health report.
|
||||
- `api/http/control-api` is a mountable ASGI adapter for `GET /health`,
|
||||
`POST /runtime/start`, `POST /runtime/stop`, and `GET /runtime/status`.
|
||||
- `configuration/application-config-file` loads an application-typed root
|
||||
`config.yaml` and atomically reloads valid snapshots without a restart.
|
||||
- `configuration/application-settings` provides a typed `SettingsReader` and a
|
||||
PostgreSQL adapter for the application's `settings` table.
|
||||
- `workflow/orchestration` executes named object-based steps through declared
|
||||
transitions and persists run and step snapshots through an application port.
|
||||
- `observability/business-tracing` provides trace contracts and a PostgreSQL
|
||||
writer for application-owned `trace_contexts` and `trace_messages` tables.
|
||||
- `observability/technical-logging` formats JSON log records with application
|
||||
and business trace identifiers for stdout.
|
||||
|
||||
## Run checks
|
||||
## Install
|
||||
|
||||
```bash
|
||||
python -m unittest discover -s tests -v
|
||||
pip install .
|
||||
```
|
||||
|
||||
## Configuration-service shape
|
||||
The PostgreSQL adapters accept the application's pool and schema. PLBA2 does
|
||||
not install or manage a database driver. The HTTP adapter uses ASGI and does
|
||||
not install or manage an HTTP server.
|
||||
|
||||
## Composition outline
|
||||
|
||||
The application loads and validates configuration before building dependent
|
||||
components. It supplies a decoder for its own typed fields:
|
||||
|
||||
```python
|
||||
runtime = Runtime(
|
||||
configuration=ConfigurationSnapshotManager(
|
||||
client=configuration_grpc_adapter,
|
||||
scope="configuration-service",
|
||||
validator=validate_configuration,
|
||||
),
|
||||
workers=[grpc_server_worker, configuration_changed_consumer],
|
||||
config_loader = ApplicationConfigLoader(
|
||||
Path("config.yaml"), application_decoder=ServiceConfig.from_mapping
|
||||
)
|
||||
config_manager = ApplicationConfigManager(config_loader)
|
||||
initial_config = config_manager.load_initial()
|
||||
|
||||
await runtime.start()
|
||||
# The RabbitMQ adapter invokes the registered callback after configuration.changed.
|
||||
# The manager refetches and atomically swaps the validated snapshot.
|
||||
await runtime.stop(timeout_seconds=20)
|
||||
identity = ApplicationIdentityResolver(
|
||||
TomlProjectNameReader(Path("pyproject.toml"))
|
||||
)
|
||||
runtime_context = identity.resolve(initial_config.application_id)
|
||||
|
||||
workers = WorkerRegistry()
|
||||
workers.register(WorkerDefinition("inventory_sync", sync_inventory))
|
||||
supervisor = WorkerSupervisor(workers, config_manager)
|
||||
runtime = ApplicationRuntime(runtime_context, supervisor)
|
||||
```
|
||||
|
||||
The adapter authenticates using bootstrap values read by the service from environment/secrets. Business code reads `manager.current()` and never makes a synchronous configuration-service call.
|
||||
The application creates its HTTP host and mounts `ControlApi` on the same
|
||||
listener. `RuntimeHealthInputProvider` connects the runtime, worker supervisor,
|
||||
and registered health contributors to `HealthAggregator`. The application
|
||||
starts its own server and chooses when to call `runtime.start()` and
|
||||
`runtime.stop()`.
|
||||
|
||||
For configuration changes, run `config_manager.watch(...)` in an application
|
||||
task and handle reload errors in the supplied callback. Existing snapshots
|
||||
remain stable; an invalid update leaves the latest valid snapshot active.
|
||||
|
||||
## Database ownership
|
||||
|
||||
The application creates and seeds `settings` in its migrations. It also creates
|
||||
`trace_contexts` and `trace_messages` in its migrations. PLBA2 does not create
|
||||
tables, run application migrations, copy YAML into the database, expose a
|
||||
business-history API, publish business events to RabbitMQ, or provide shared
|
||||
worker-message queues. See [database contracts](docs/database-contracts.md) and
|
||||
[configuration](docs/configuration.md) for the consumer-facing contracts.
|
||||
See [integration guidance](docs/integration.md) for wiring the HTTP, database,
|
||||
workflow, trace, and logging adapters into an application.
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
python3 -m pytest
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user