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-identityresolvesapplication_idfromconfig.yaml, then[project].nameinpyproject.toml, then UUIDv4.runtime/workerregisters uniquely named workers, applies thedisabledflag, runs sequential scheduled cycles, combines application and automatic health, and supports graceful or force stop.runtime/application-lifecyclestarts and stops all enabled workers and reports application lifecycle states.health/aggregationcombines worker and contributor states, criticality, missing components, and application lifecycle into a health report.api/http/control-apiis a mountable ASGI adapter forGET /health,POST /runtime/start,POST /runtime/stop, andGET /runtime/status.configuration/application-config-fileloads an application-typed rootconfig.yamland atomically reloads valid snapshots without a restart.configuration/application-settingsprovides a typedSettingsReaderand a PostgreSQL adapter for the application'ssettingstable.workflow/orchestrationexecutes named object-based steps through declared transitions and persists run and step snapshots through an application port.observability/business-tracingprovides trace contracts and a PostgreSQL writer for application-ownedtrace_contextsandtrace_messagestables.observability/technical-loggingformats 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