Cheetah / Cheetah documentation

Lifecycle and deployment

WorkerContextManager has a background timeout loop and an application-specific disconnect policy. Merely constructing it does not start either behavior. The host that creates the manager must start and stop it, attach the desired connection hook, and decide which process may create new browser resources.

Start the timeout sweeper deliberately

The default assignment timeout is 300,000 milliseconds and the default check interval is 30 seconds. start() creates the sweeper when the timeout is enabled; repeated starts are safe. stop() cancels the task and is also safe to repeat.

When task_timeout_ms is greater than zero, the constructor requires task_timeout_check_interval_s to be finite and strictly positive. Zero, negative, NaN, and infinite intervals fail at construction, preventing an accidental busy scan. Setting task_timeout_ms=0 disables the loop.

The sweep releases assignments older than the timeout. It does not send a client cancellation, close the context, change worker ownership, retry the product task, or prove that a command stopped. Long-running application work must renew its handle while it still owns the worker.

Supplied context registries provide timeout-aware release support. A custom registry can also implement the optional bulk timeout method; otherwise the manager uses an administrative cross-user scan and releases expired assignments individually.

Connect disconnect policy explicitly

on_client_disconnect(user_id, client_id) releases task assignments held by that client's worker contexts and returns the number released. It does not remove the contexts, create a replacement, or retry the task.

Call it from the host's authenticated connection-disconnect integration when immediate release is the desired product policy. Some applications instead tolerate a short reconnect window, so the manager does not attach itself automatically. Make the choice visible and keep it consistent with the registry's client-removal behavior.

A client state report is a complete snapshot for one context epoch. Contexts that vanish from a new report are removed, while server-owned assignments are preserved for surviving contexts in the same epoch. A browser restart creates a new epoch and cannot inherit a previous browser session's assignment merely by reusing a numeric tab ID.

Use shared registries across server roles

In-memory context, connection, and browser-window registries are suitable only when ingestion, WCM, diagnostics, and AppNode-side consumers share the same process and object graph.

In a multi-process deployment, use the Redis-backed registries so a state report accepted by a REST role is visible to the AppNode process running WCM. Redis context assignment, renewal, and handle-safe release use shared mutation primitives, preventing two manager processes from both owning the same context assignment.

Shared registries do not make the whole manager distributed:

• round-robin counters and custom strategy state live in one manager process;
• least-busy selection is a current registry snapshot rather than a global scheduler;
• browser creation locks and reservations are process-local;
• the polling loop waiting for a newly created context runs in the requesting process;
• application task records, priorities, attempts, and retry policy remain outside WCM.

Choose one process as the browser auto-provisioning owner for each user/client. Other processes may acquire existing workers but should keep auto_provision=False and use reuse_only when a placement is supplied. There is no constructor-level switch that globally disables creation; the caller controls it per acquisition.

Keep durable task state above the pool

A task ID stored on a context is a short-lived assignment label. WCM does not store task input, attempt number, product status, priority, deadline, or the accepted business result. A robust application persists those separately and associates them with command IDs and retained evidence.

Before repeating work after a timeout or disconnect, ask:

1. Was a command merely admitted, or did a send attempt begin?
2. Did the bound client acknowledge the command frame?
3. Is a terminal result or error retained in history?
4. Can the target system establish whether the external effect happened?
5. Is another attempt idempotent or otherwise safe?

The worker becoming idle answers none of those questions by itself. Use the command delivery evidence and the product's own reconciliation record.

Operate the pool as live coordination

The diagnostics API can show current worker contexts, available workers, task assignments, and browser-window topology. Delivery diagnostics separately show admitted work and dispatcher health. These views help explain why acquisition returned None, but they are not a durable task ledger and do not perform manager mutations.

A useful deployment verification should prove:

1. disconnected clients cannot be selected even when an old context snapshot exists;
2. metadata requirements admit only the intended clients;
3. two concurrent callers cannot acquire the same context;
4. a stale handle cannot send, renew, or release a later task's assignment;
5. legitimate long work renews before the timeout and abandoned work is released;
6. disconnect handling releases exactly the selected client's tasks;
7. browser creation respects negotiated window and tab limits;
8. only the elected process auto-provisions browser resources;
9. task retry waits for the evidence required by the product's side-effect policy.

The implementation has focused coverage for in-memory and Redis registries, selection races, lease renewal, stale-handle dispatch, timeout cleanup, disconnect behavior, browser placement, capacity reservations, and tracker recovery. Its principal limits are the process-local provisioning controls, the lack of WCM enforcement for console max_flows, and the deliberate absence of a durable task queue.

Return to Worker pools, or use Delivery and worker topology for the read-only operational surface.