Cheetah / Cheetah documentation

Events and actions

Cooperative mode adds two domain-level relationships to the HTTP relay. A local application or helper can publish a named event when something meaningful changes, and a viewer can ask the application to invoke one explicitly allowed Cheetah action. Both use existing Cheetah identity, policy, correlation, and history paths.

Events return through authenticated ingestion

The console event publisher obtains the connected runtime's current client_id and instance_id, builds an ordinary Cheetah event message, and sends it to the configured REST ingest endpoint. The message uses stream suffix sites/{site_id}/events; the server canonicalizes it under the authenticated host user.

The broker projects an accepted message onto the site's event bus only when:

• the message is an event on the exact canonical site stream;
• the authenticated host matches the descriptor owner;
• its payload has a valid event name; and
• when event_names is non-empty, the name appears in that allowlist.

The authenticated ingest route must call ingest_cooperative_site_message(). Passing the same payload only to the ordinary RestNode ingest method can retain it in Cheetah history, but it does not publish it to current site subscribers.

The supplied event bus is live fan-out. It does not replay retained history to a later subscriber. Each subscription queue holds 100 events and discards its oldest event when full. Use ordinary Cheetah history or an application-owned durable stream when a missed notification must be recoverable.

Actions remain governed commands

The runtime invokes an action only when the session is active, the site uses cooperative mode, capability_profile.action_invocation is true, and the action appears in the descriptor's allowed names. It adds two reserved parameters:

• __cooperative_site_session_id;
• __cooperative_site_id.

It then sends the named action to the session's connector as ordinary RPC. The normal handler registry, argument validation, local authorizer, optional approval, lease, cancellation, result sink, correlation, and history behavior still apply. The site allowlist is an additional product boundary, not a replacement for client-side policy.

Use bounded domain names such as refresh_index or publish_preview. A generic execute action would hide authority and argument semantics precisely where the cooperative contract is meant to make them visible.

The local control server is optional glue

startCooperativeSiteControlServer() can expose a small local API for a site or build process:

• PUT /sites/{site_id} updates and registers a definition;
• DELETE /sites/{site_id} removes and unregisters it;
• POST /sites/{site_id}/events publishes one event.

It requires its configured bearer token and rejects callers whose remote address is not loopback. Keep it bound to loopback. It is a convenience boundary between trusted local processes, not a multi-user network service.

The event publisher must reuse the connected runtime's identity provider and REST credentials. Creating a second client identity for the control server produces a stale or unrelated instance and defeats instance fencing.

Browser cooperation is deliberately small

CooperativeSiteBrowserClient provides two operations: subscribe to the session's server-sent event stream and invoke a session-scoped action. It does not open sessions, render the relayed site, decide confirmation policy, recover missed events, or interpret domain payloads.

The application should treat an event as an invalidation or domain notification rather than an authoritative state transfer. After site_changed, for example, it can refresh the relevant resource through the relay. This keeps the source of truth in the local application while avoiding constant polling.

The browser helper's credential constraint and the router's optional identity behavior still apply. Protect events and actions with the same complete session policy described in Sessions and sharing.

Next: Composition and lifecycle.