osp-provider-runtime

Thin, boring runtime harness for OSP providers.

This package handles RabbitMQ message plumbing so provider implementations can focus on business logic.

What it does (v0.1)

Parses a versioned request envelope.
Builds provider RequestContext/ProviderRequest and calls execute(...).
Emits canonical asynchronous task updates and synchronous control-RPC replies.
Applies explicit ack/requeue/dead-letter decisions.
Emits structured logs for delivery decisions.
Supports explicit runtime knobs for prefetch/concurrency/retries/transport timeouts/DLQ.
Accepts contract_v1 request envelopes.
Provides ProviderIdentity so providers derive the same RabbitMQ queue/binding, routing prefix, and signing source from PROVIDER, PROVIDER_INSTANCE, and optional PROVIDER_INSTANCE_ID.

Provider identity

Use a provider family for permissions and API requests, then add an instance only when you need a separate runtime lane:

from osp_provider_runtime import ProviderIdentity

identity = ProviderIdentity(
    provider="nrec",
    instance="pr",
    instance_id=37,
)

identity.routing_prefix   # "nrec.pr.37"
identity.request_queue    # "provider.nrec.pr.37"
identity.request_binding  # "nrec.pr.37.#"
identity.signing_provider # "nrec_pr"

The common case stays small: ProviderIdentity("vmware", "dev") gives the vmware.dev routing prefix and vmware_dev signing source. Signing deliberately uses only provider + instance, so all nrec.pr.<id> runtimes share the nrec_pr signing scope without a separate override knob.

Result payload conventions

Provider results should keep ProviderResult.data focused on the resolved values for the task. The runtime builds the full update payload envelope:

success: provider outcome flag; false still represents a completed no-op or degraded outcome
resolved: your ProviderResult.data (after runtime normalization)
provenance: optional; extracted from ProviderResult.data["provenance"]
dry_run: derived from the request payload

Raise a ProviderError when the task should enter a failed lifecycle state. ProviderResult(success=False) does not turn a completed outcome into a task failure.

Special keys in ProviderResult.data:

progress_events (list): lifted into the update payload and removed from resolved to avoid duplicate TaskEvent rows.
provenance (dict): lifted into the top-level provenance field.

Providers may opt into live updates by accepting a keyword-only progress argument on execute. Call it with a short user-facing message and optional payload while work is running:

def execute(self, action, request, context, *, progress=None):
    if progress:
        progress("Creating virtual machine", {"stage": "openstack_create"})
    return create_virtual_machine(request)

The callback is best-effort and transport-owned. Providers without the argument keep the original three-argument contract unchanged.

Task logging

The runtime binds the task context once around execute() and emits one task.summary event when the delivery finishes. Provider log sinks must use JSON serialization so these fields are retained:

task_id: cross-service join key
dispatch_id: one delivery attempt
provider and task_type
step, outcome, and duration_ms
error.type, error.message, and error.code when applicable

Use task_step("external.operation") around meaningful external operations. It records the step in the summary trail and logs a full traceback before re-raising failures. Task code must not bind correlation fields itself.

from osp_provider_runtime import task_step

with task_step("openstack.create"):
    server = openstack.create_server(...)

Avoid embedding envelope-shaped keys (requested, resolved, request_input, request_defaults) inside ProviderResult.data. The runtime will drop them to keep the stored result compact and predictable.

The orchestrator already owns the original task request. Provider updates do not echo it; HTTP and CLI read models compose request and result when needed.

What it does not do

No provider framework.
No plugin system.
No workflow orchestration.

Install

pip install osp-provider-runtime

Development

env -u VIRTUAL_ENV uv sync --extra dev
hatch shell
hatch run dev:check
hatch run dev:build
hatch run dev:verify

Runtime Knobs

Set these via RuntimeConfig in your provider runtime_app.py:

prefetch_count (default 1)
concurrency (default 1)
max_attempts (default 5)
idempotency_cache_max_entries (default 1024)
dead_letter_exchange (optional)
dead_letter_routing_key (optional)
heartbeat_seconds (default 60)
blocked_connection_timeout_seconds (default 30)
updates_signing_enabled (default False)
signing_kid (required when signing enabled)
signing_secret (UTF-8 shared secret; set this or _b64)
signing_secret_b64 (base64-encoded shared secret; preferred for random bytes)

Update Emission

Use TaskReporter for provider task lifecycle updates. The runtime keeps transport details compatible with orchestrator consumers.

Docs:

docs/runtime-contract.md
docs/provider-updates.md
docs/migration-task-reporter.md
docs/runtime-upgrade-checklist.md
docs/release-notes-task-reporter.md

Tag and push:

git tag v0.2.0
git push origin v0.2.0

Development Status
- 3 - Alpha
Intended Audience
- Developers
License
- OSI Approved :: MIT License
Programming Language
- Python :: 3
- Python :: 3.13
Typing
- Typed

Release files for osp-provider-runtime 0.3.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for osp-provider-runtime 0.3.9
File	Size	Uploaded
osp_provider_runtime-0.3.9.tar.gz	98.8 kB	Aug 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for osp-provider-runtime 0.3.9
File	Interpreter	ABI	Platform	Reset
osp_provider_runtime-0.3.9-py3-none-any.whl 46.2 kB Aug 13, 2026	Python 3	none	any	Details

Total release size: 144.9 kB

Release files / osp_provider_runtime-0.3.9.tar.gz

Download URL	osp_provider_runtime-0.3.9.tar.gz
Size	98.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`ac200309ba2fad93243d2391c0d9d1b28c9d57b97c096a49ddfc2c1bfc7f10c1`
BLAKE2b-256 checksum How to use checksums	`2fd38306e41545e41b8e93b8144171c3bebcf3aad052ff13cc968394b912a3df`
Upload date	Aug 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.5`

Release files / osp_provider_runtime-0.3.9-py3-none-any.whl

Download URL	osp_provider_runtime-0.3.9-py3-none-any.whl
Size	46.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`268fa700e475378a5a94907aa0cbc5dd8b54362a6c9cb2bb92026a74b577f737`
BLAKE2b-256 checksum How to use checksums	`aad2d1fb8c275e052cb94f0d985df61eae0de0c47d5dbb1842fc569039984725`
Upload date	Aug 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.5`