Provider API

Provider plugins implement conda_broker_services() and return CondaService objects. ServiceRegistry is a pluggy manager and the validated service catalog.

Hookspec

Private pluggy hooks owned by conda-broker.

conda_broker.hookspec.conda_broker_services() → Iterable[CondaService]

Return brokered service definitions provided by this package.

Models

Typed service models shared by providers, API users, and the supervisor.

class conda_broker.models.CondaService(name: str, summary: str, source: str, process: ProcessSpec | None = None, runtime: str = 'process', start_policy: str = 'manual', restart_policy: str = 'on-failure', health_check: HealthCheck = <factory>, endpoints: tuple[~conda_broker.models.EndpointSpec, ...]=(), dependencies: tuple[str, ...]=(), env: dict[str, str]=<factory>, cwd: str | None = None)

A service definition returned by a conda-broker provider.

endpoint_statuses() → dict[str, dict[str, Any]]

Return unresolved endpoint status rows for stopped services.

merged_process() → ProcessSpec

Return the process spec with service-level env/cwd defaults applied.

class conda_broker.models.EndpointSpec(name: str = 'default', protocol: str = 'tcp', host: str = '127.0.0.1', port: int | None = None, path: str = '/', port_env: str | None = None, url_env: str | None = None)

Network endpoint contract exposed by a service.

class conda_broker.models.EndpointStatus(name: str, protocol: str, host: str, port: int | None = None, path: str = '/', url: str | None = None)

Resolved endpoint state reported for a service.

classmethod from_dict(data: dict[str, Any]) → EndpointStatus

Build an endpoint status from a JSON payload.

class conda_broker.models.HealthCheck(type: str = 'process', interval_s: float = 30.0, timeout_s: float = 5.0, start_period_s: float = 5.0, endpoint: str | None = None, command: tuple[str, ...] = (), host: str | None = None, port: int | None = None, url: str | None = None)

Health check definition for a service.

class conda_broker.models.ProcessSpec(argv: tuple[str, ...], env: dict[str, str] = <factory>, cwd: str | None = None, stop_signal: str = 'TERM', grace_period_s: float = 5.0)

Host process runtime definition.

property signal_number: int

Return the configured stop signal as an OS signal number.

class conda_broker.models.ServiceEvent(type: str, service: str | None = None, message: str = '', data: dict[str, Any]=<factory>, timestamp: str = <factory>)

Append-only event record.

classmethod from_dict(data: dict[str, Any]) → ServiceEvent

Build a service event from a JSON payload.

class conda_broker.models.ServiceName(value: str)

A validated service or endpoint name.

class conda_broker.models.ServiceStatus(name: str, summary: str, source: str, runtime: str, enabled: bool, state: str, running: bool = False, pid: int | None = None, exit_code: int | None = None, started_at: str | None = None, restart_count: int = 0, health: str = 'unknown', ready: bool = False, endpoints: dict[str, dict[str, Any]]=<factory>)

Observed state for a registered service.

endpoint(name: str = 'default') → EndpointStatus | None

Return one typed endpoint status by name.

classmethod from_dict(data: dict[str, Any]) → ServiceStatus

Build a service status from a JSON payload.

Health Checks

HealthCheck supports four type values:

• process: child process is still alive.

• tcp: broker can open a TCP connection to host and port.

• http: broker can fetch url; status codes from 200 through 399 are healthy.

• exec: command exits with status code zero before timeout_s.

Each check runs every interval_s seconds while the service is running. Failed checks during start_period_s keep the service in the starting state. After that startup period, failed checks are restart triggers for services with restart_policy set to on-failure or always.

TCP and HTTP health checks can reference a declared endpoint instead of duplicating host and port values:

HealthCheck(type="http", endpoint="default")

Endpoints

EndpointSpec describes a local TCP or HTTP endpoint exposed by a service. Static ports are allowed, but omitting port lets the broker allocate a free local port at process start.

The supervisor injects automatic endpoint variables into the process environment:

• CONDA_BROKER_SERVICE_NAME

• CONDA_BROKER_ENDPOINT_<NAME>_PROTOCOL

• CONDA_BROKER_ENDPOINT_<NAME>_HOST

• CONDA_BROKER_ENDPOINT_<NAME>_PORT

• CONDA_BROKER_ENDPOINT_<NAME>_URL

port_env and url_env add provider-chosen variable names for services that already expect simple variables such as PORT.

Endpoint names must remain unique after conversion to their uppercase environment-variable form. Custom endpoint variable names must also be portable, unique, and distinct from broker-owned names.

Runtimes and Processes

Runtime names are open identifiers so future provider models remain discoverable. The installed broker currently activates only runtime="process"; starting any other runtime raises RuntimeUnavailableError.

Process services validate their argv, environment names and values, stop signal, and grace period when providers are collected. Exec health checks use the same merged environment and working directory as the service, plus resolved endpoint variables.

Registry

Service discovery and validation.

class conda_broker.registry.ServiceRegistry(services: Iterable[CondaService] = ())

Pluggy manager plus validated service registry keyed by service name.

dependency_errors() → dict[str, str]

Return dependency validation errors keyed by invalid service.

classmethod discover() → ServiceRegistry

Load services from the private conda-broker pluggy group.

startup_order(names: Iterable[str]) → tuple[CondaService, ...]

Resolve services and dependencies in launch order.

validate_dependencies() → None

Reject unknown dependencies and cycles before the supervisor starts.