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

• Parses a versioned request envelope.
• Builds provider RequestContext/ProviderRequest and calls execute(...).
• Dispatches optional read-only provider assessment RPCs without task execution.
• 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 wire-version-4 request envelopes with task identity and cleared Gate keys separated from provider action payload.
• Provides ProviderIdentity so providers derive the same RabbitMQ queue/binding, routing prefix, and lane name 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.provider_lane    # "nrec_pr"

The common case stays small: ProviderIdentity("vmware", "dev") gives the vmware.dev routing prefix and vmware_dev lane name. Instance IDs refine routing within a lane without changing its attribution name.

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"]
• produced_resources: typed provider-native references produced by the operation

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. Use ProgressReporter so the same action also works without live delivery:

from osp_provider_contracts import ProducedResource, ProviderResult
from osp_provider_runtime import ProgressReporter


def execute(self, request, context, *, progress=None):
    reporter = ProgressReporter(progress)
    reporter.report("Creating virtual machine", {"stage": "openstack_create"})
    vm = create_virtual_machine(request)
    return ProviderResult(
        success=True,
        message="Virtual machine created",
        produced_resources=(ProducedResource(kind="vm", ref=vm.id),),
        data={"progress_events": reporter.events},
    )

With a callback, the event is published live and reporter.events stays empty. Without one, the event is returned through progress_events and the runtime expands it from the terminal update. This keeps each event on one delivery path. The callback is best-effort and transport-owned. request.action is the sole action source.

Active task cancellation

The .cancellation.rpc control binding invokes the optional provider-owned task_cancellation(task_ref) and cancel_task(task_ref) hooks on the separate control executor. Providers report current backend capability and perform the actual stop. A successful RPC only records the request; it emits no terminal task update. The execution must finish with TaskCancelled(ProviderResult(...)) after confirmed termination, retaining any surviving resource references. Providers without those hooks report unsupported cancellation.

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_ref: stable provider execution UUID
• 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(...)

Provider data is preserved inside result.resolved; its keys cannot override the shared result fields. Runtime extracts the existing progress_events and provenance metadata into their dedicated result fields.

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)

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