Cheetah / Cheetah documentation

Delivery and worker topology

Connection and RPC views are necessary but insufficient for delivery operations. A client can be registered while admitted commands accumulate, a WebSocket node's mailbox listener has stopped, or capacity reservations remain occupied. Cheetah therefore exposes delivery as its own inspector capability.

Inspect admitted work without exposing command payloads

GET /delivery/summary returns bounded deployment aggregates:

• tracked and currently due commands;
• sampled oldest deadline and queued age, with the sample size used;
• legacy command-stream and pending-command depth detected during migration checks.

The oldest age is explicitly sampled rather than presented as an exact global maximum. Alerting thresholds and sampling interpretation belong to the deployment.

GET /delivery/nodes pages recently reporting dispatcher nodes. Each entry reports whether its mailbox listener and reconciliation loop are alive, active drainers, connection waiters, last update, staleness, and low-cardinality recovery, outcome, acknowledgement, and related counters. This is the view that can distinguish a live client registry entry from unhealthy delivery machinery.

GET /delivery/tenants pages trusted capacity scopes and their reserved command counts and oldest deadlines. The scope_id is an admission/quota scope, not a promise that every product maps it to a commercial tenant. The route never returns command payloads.

GET /delivery/status requires user_id, client_id, and command_id. It returns one payload-free delivery record or 404 when no status is retained. Invalid identities or combinations return a bounded client error. Read its admission, attempt, acknowledgement, recovery, and terminal fields according to the command evidence model; no one field silently means external completion.

Direct mode supplies the corresponding process-local subset. Redis mode supplies shared mailbox, reservation, listener, reconciliation, recovery, and legacy-migration evidence within the selected deployment namespace. Neither mode provides deployment-specific alert routing or thresholds.

Contexts describe execution sites

Execution-context routes report browser tabs, console flows, and other client execution sites. GET /contexts can filter by canonical user, client, client type, status, ownership, and browser window. Current enum values are:

• client type: browser, console, mobile, or web;
• status: active, idle, closed, or stale;
• ownership: user-owned or worker.

List and count routes return current registry state, not retained task history. A context can disappear when its client stops reporting or its platform resource closes.

Browser-window views connect capacity to placement

Window routes expose current browser window identity, ownership, focus, type, state, incognito flag, tab count, configured capacity, draining state, and open/stale/closed status. When a context registry is present, the API derives live worker, idle, and busy counts from contexts; otherwise it uses the counts stored in the window snapshot.

That distinction prevents a snapshot from pretending to be a fresh cross-registry calculation. The diagnostics TypeScript client and DevConsole currently do not expose dedicated browser-window queries or panels, even though the server routes exist.

Worker routes are filtered context views

GET /workers, /workers/available, and /workers/tasks/{task_id} inspect contexts whose ownership is worker. Every route requires a canonical user_id; the first two optionally filter by client type. The list separates idle contexts from those assigned to a task and carries task assignment time where available.

Worker inspection does not create, acquire, renew, or release work. Those are application-side coordination operations. A task identifier on a context proves a current registry assignment, not that a durable job system owns the task or that its external effect completed.

The reusable TypeScript client has worker methods but still defaults an omitted user to the legacy string default. The server now requires a canonical user identity, so multi-user and current integrations should always pass the resolved scope explicitly. The DevConsole summarizes worker pressure from sampled contexts and offers a context view; it does not yet present the complete delivery or window inspector surfaces.

For assignment and lease behavior rather than observation, continue with Worker pools. For operating investigation order, return to Observe and diagnose.