Files
plba_v2/README.md
T
2026-10-10 19:36:32 +03:00

4.1 KiB

PLBA v2

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.

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.

Capabilities

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

Install

pip install .

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:

config_loader = ApplicationConfigLoader(
    Path("config.yaml"), application_decoder=ServiceConfig.from_mapping
)
config_manager = ApplicationConfigManager(config_loader)
initial_config = config_manager.load_initial()

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 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 and configuration for the consumer-facing contracts. See integration guidance for wiring the HTTP, database, workflow, trace, and logging adapters into an application.

Development

python3 -m pytest