Architecture#

conda-broker has five main parts:

  1. The conda plugin registers conda broker and broker settings lazily.

  2. The CLI parses commands and renders Rich or JSON output.

  3. ServiceRegistry is a pluggy manager that discovers provider hooks and stores validated CondaService objects.

  4. BrokerServer owns the user-scoped broker process, IPC server, state, and supervisor.

  5. ServiceSupervisor resolves endpoints, starts, stops, observes, restarts, and reports child processes.

Application behavior belongs to those objects rather than module-level helper collections. BrokerLease owns single-instance files and lock lifetime, BrokerRequest owns RPC authentication and normalization, ManagedProcess owns one child lifecycle, and BrokerConsole owns all Rich and JSON rendering. The remaining module-level functions are adapters required by conda hooks, argparse command dispatch, and Python entry points.

        flowchart LR
    User["User CLI"] --> CLI["cb / conda broker"]
    Plugin["Provider package"] --> Registry["ServiceRegistry"]
    Registry --> Broker["BrokerServer"]
    CLI --> IPC["Authenticated localhost JSON-RPC"]
    IPC --> Broker
    Broker --> Supervisor["ServiceSupervisor"]
    Supervisor --> Service["Child service process"]
    Supervisor --> Endpoints["Resolved endpoints"]
    Supervisor --> Logs["Service logs"]
    Broker --> Events["events.jsonl"]

The broker does not start during arbitrary conda invocations. Lightweight Service queries only ask a running broker and return immediately when it is absent. Explicit Broker.status(), list_services(), enable, and disable operations may discover providers offline because those operations need the catalog. Startup is reserved for explicit commands and explicit Broker API calls.

Endpoint resolution happens immediately before process launch. Static ports are reported as-is. Dynamic endpoints get a broker-assigned local port and environment variables that the child process can read before binding. The broker reserves all dynamic ports while composing one service launch, then releases them immediately before creating the child.

Show Source