Cheetah / Cheetah documentation

Worker pools

WorkerContextManager is an optional application-side service for borrowing live execution contexts. It can select an idle browser tab or console flow, assign it to an application task, return a handle that targets commands to that context, renew the assignment, and release it. It is useful when a product needs several interchangeable execution sites without rebuilding the same coordination rules around every task.

It is not a server node, a durable task queue, or a guarantee that the commanded external effect completed. The product still owns its task record, retry decision, and business result.

The manager coordinates a lease over current client-reported state. Durable task intent and business reconciliation stay above that lease.

Three kinds of state cooperate

The pool is built from state with different lifetimes:

An assignment is deliberately smaller than a job record. Losing it can free a worker, but it cannot decide whether a timed-out browser action should be repeated. That decision needs the product task and the evidence already returned by the client or target system.

The service composes existing boundaries

WorkerContextManager requires both IContextRegistry and IConnectionRegistry. The context registry supplies current contexts and atomic task assignment. The connection registry supplies heartbeat-backed client liveness and metadata used for eligibility. Requiring both prevents a stale state report or missing metadata service from silently becoming a selectable worker.

Add AppNode when handles must send commands or the manager may create a new context. Add IBrowserWindowRegistry for browser-window placement and capacity. A replaceable dispatch strategy can choose among eligible workers when the registry's ordinary acquisition order is not enough.

from servercheetah.services import WorkerContextManager

wcm = WorkerContextManager(
    context_registry=components.context_registry,
    connection_registry=components.connection_registry,
    app_node=app_node,
    browser_window_registry=components.browser_window_registry,
)

No preset creates or starts the manager. A host may use registries from a component set, but it still owns this optional service's construction, lifecycle, and disconnect integration.

Acquisition is guarded coordination

For one acquisition, the manager:

1. reads connected presence for the canonical user;
2. removes clients that fail exact metadata requirements;
3. finds live, idle, worker-owned contexts of the requested type;
4. applies client affinity, placement, and the configured selection strategy;
5. asks the registry to assign the task atomically;
6. returns a ContextHandle only after the assignment succeeds.

Another caller may win between the query and assignment. The manager removes that candidate and tries the remaining eligible contexts. It never returns a handle merely because a prior snapshot looked idle.

If no existing context can be assigned, acquisition returns None. With explicit permission and the required collaborators, it may first create a browser worker tab, a worker window and tab, or a console flow. Creation still has to appear in a client state report before the new context can be assigned.

Read the reference by decision

Acquire, use, and release documents the manager API, ContextHandle, lease renewal, payload retrieval, and safe cleanup.

Matching and selection covers client type, metadata requirements, affinity, built-in strategies, and atomic selection races.

Browser placement and protection explains worker windows, placement modes, negotiated capacity, auto-provisioning, session-scoped worker identity, and the browser overlay.

Lifecycle and deployment covers timeout cleanup, disconnects, shared registries, process-local coordination, and the durable task boundary.

For read-only inspection of workers and windows, use Delivery and worker topology. For the client-side context model, start with Client runtime reference.