Cheetah / Cheetah documentation

Diagnostics API and security

The diagnostics router presents read-only inspector interfaces through HTTP. Its URL structure is the same for a local process and a Redis-backed deployment; the source of truth behind the InspectorSet is different.

For an in-memory composition, create_dev_inspectors(components) wraps the exact live registry, history, correlator, deduplicator, dispatcher, and optional topology registries in that process. It does not copy their state. Mounting those inspectors in a second process produces a view of the wrong objects or no useful view at all.

For a Redis composition, create_redis_inspectors(redis_client, deployment_id=...) creates storage-backed inspectors in the selected deployment namespace. It can run in an independent observation service. Context and browser-window inspectors are included by default, and a compatible spill store can hydrate externalized history payloads. The deployment_id returned by the API is an operational routing identity: verify it before drawing conclusions about a shared Redis installation.

Mount one administrative read boundary

from servercheetah.admin_auth_helpers import resolve_admin_auth
from servercheetah.api.diagnostics import create_diagnostics_router

admin_auth = resolve_admin_auth(
    bind_host="0.0.0.0",
    strict=True,
)

app.include_router(
    create_diagnostics_router(
        inspectors,
        admin_auth=admin_auth,
        enable_raw_messages=False,
    ),
    prefix="/api/diag",
)

Every route uses the supplied IAdminAuth. resolve_admin_auth() prefers an explicit key, then CHEETAH_ADMIN_KEY, and otherwise returns NoOpAdminAuth. With strict=True, a non-loopback bind without a key fails before startup. The supplied API-key implementation reads X-Admin-Key.

NoOpAdminAuth accepts every request. It is appropriate only for a deliberately isolated local surface. Diagnostics can reveal identities, connection metadata, action descriptions, returned payloads, errors, topology, and delivery pressure. Calling a route read-only describes mutation authority, not data sensitivity.

Discover capabilities before selecting a view

GET /capabilities reports the inspector families supplied to this router:

{
  "history": true,
  "registry": true,
  "rpc": true,
  "deduplicator": true,
  "context_registry": true,
  "browser_window_registry": true,
  "delivery": true,
  "history_list_streams": true,
  "registry_connection_history": false,
  "rpc_instance_check": true,
  "dedup_per_user": false,
  "extensions": {}
}

A true value means the route can ask that inspector a question. It is not a readiness check and it does not guarantee a non-empty answer. A false value is also not a failure: the deployment may have deliberately omitted that facility.

When a route needs an absent inspector, it returns 501. A missing record returns 404 where the route addresses one object. Failed administrator authentication returns 403. Invalid query or body values normally receive FastAPI's 422; the typed connection, context, window, and worker filters expose their allowed enum values through OpenAPI.

Bounded answers state whether they are complete

Several aggregate endpoints deliberately sample or page their source instead of hiding an unbounded scan behind one request. /users, /users/{user_id}/summary, and /actions include a uniform completeness block:

{
  "complete": false,
  "truncated_sources": ["connections"],
  "examined": { "connections": 1000 },
  "limits": { "connections": 1000 }
}

complete means complete for the available inspector and the requested observation, not complete knowledge of the deployed application. When it is false, labels such as observed_connections and observed_action_types are samples rather than totals.

Paginated list routes return items, next_cursor, and has_more. Redis scan pagination may produce an empty items page while has_more is still true; continue with the opaque cursor until the response ends the scan. Raw history is intentionally different: it returns one bounded {items, count} sample and has no cursor contract.

The API root lists the known routes and a conventional dashboard path. It does not mount a UI or prove that static dashboard assets exist. Dashboard serving and write-capable control are separate host decisions covered in DevConsole and operator interfaces.