Build a Provider Plugin

A provider plugin is any installed Python package that publishes conda_broker_services() under the conda_broker entry point group.

Project Metadata

[project]
name = "conda-my-provider"
dependencies = ["conda-broker"]

[project.entry-points.conda_broker]
"conda-my-provider" = "conda_my_provider.broker"

Service Definition

import sys

from conda_broker.hookspec import hookimpl
from conda_broker.models import CondaService, EndpointSpec, HealthCheck, ProcessSpec


@hookimpl
def conda_broker_services():
    yield CondaService(
        name="my-provider.api",
        summary="Local API used by conda-my-provider",
        source="conda-my-provider",
        start_policy="manual",
        restart_policy="on-failure",
        endpoints=(
            EndpointSpec(
                protocol="http",
                path="/health",
                port_env="PORT",
                url_env="SERVICE_URL",
            ),
        ),
        health_check=HealthCheck(type="http", endpoint="default"),
        process=ProcessSpec(
            argv=(sys.executable, "-m", "conda_my_provider.server"),
            env={"PYTHONUNBUFFERED": "1"},
            grace_period_s=10,
        ),
    )

Query Status from the Provider

Provider code can decide whether to use the long-running path:

from conda_broker import Broker


def solve(request):
    service = Broker.current().service("my-provider.api")
    check = service.check()
    if check.ready and check.endpoint and check.endpoint.url:
        return solve_with_local_api(request, check.endpoint.url)
    log_fallback(check.reason)
    return solve_inline(request)

Readiness and endpoint queries never start the broker. Use Broker.start(), service.start(), or service.wait(start=True) only for explicit user-driven startup.

Validate the Provider Service

Run the conformance harness before relying on the service from another plugin:

cb dev validate my-provider.api
cb dev test my-provider.api --scenario health
cb dev test my-provider.api --scenario crash

Use cb dev report my-provider.api --json in CI to catch missing commands, unhealthy services, broken stop behavior, and restart-policy regressions.