Site relays and cooperative sites
A site relay makes a deliberately selected local HTTP application reachable through a Cheetah client that is already connected to the product. The local application can remain bound to its machine; it does not need to become a public server or implement the Cheetah wire protocol.
Typical examples include a documentation viewer, development dashboard, or product tool running beside a console client. A remote viewer opens an application-governed session. Browser requests then travel through the application, the normal Cheetah command path, and the connected client to the local HTTP origin. Responses return through the same relationship.
The relay is a composition of explicit boundaries. It is not a general tunnel into the host machine.
Two integration modes share one HTTP foundation
| Mode | Local application | Additional relationship | Use when |
|---|---|---|---|
external_compat | remains unaware of Cheetah | none beyond bounded HTTP relay | an existing or third-party site should work without modification |
cooperative | may still serve ordinary HTTP | named events and approved Cheetah actions | an owned site or local helper should participate in a richer workflow |
Both modes use the same descriptor, session, route allowlist, relay command, connector-side HTTP request, and response handling. Cooperative mode adds explicit event and action contracts; it does not weaken the HTTP or client-policy boundaries.
Four owners make one experience
The viewer application owns discovery, user authentication, sharing policy, session authorization, and the browser experience. The site-relay runtime supplies reusable registration, session, relay, event, and action services, but it cannot infer the product's access rules.
The Cheetah server path owns command dispatch, client identity, correlation, history, and returned evidence. A relay command therefore inherits the normal distinction between accepted delivery, client receipt, handler execution, and a terminal result.
The connected client owns access to the configured local origin. It advertises the site, handles cooperative_site_http_request, keeps local cookies isolated by site session, and performs the actual HTTP request.
The local site owns its routes, application authentication, and effects. Relaying a POST does not make the operation safe or idempotent; it only carries an allowed request to that site.
What the feature does not provide
Site relay is not a reverse-proxy product, arbitrary network access, website hosting, or a complete security perimeter. It supports GET, HEAD, and POST below configured route patterns. It does not provide transparent WebSocket relay, service-worker scope translation, streaming response bodies, or automatic compatibility with every browser application.
The supplied runtime and router are opt-in. No server preset mounts them. Their default registry, session store, access-decision store, and event bus are process-local. A product that needs restart survival, several application replicas, audit retention, or time-based session expiry must provide those policies and implementations explicitly.
The reusable router also does not consistently require identity on every session-specific route. Before exposure to untrusted callers, the application must enforce one complete authorization policy around session inspection, close and revoke, relay HTTP, event subscription, and action invocation. Sessions and sharing defines that boundary.
Read the reference in implementation order
Describe and register a site covers the descriptor, live client claim, authenticated registration, availability, and route/capability truth.
Relay HTTP follows one browser request across all boundaries, including exact path and query handling, headers, cookies, redirects, HTML compatibility, and failure mapping.
Sessions and sharing covers viewer identity, the supplied policy, route authorization, lifecycle, and persistence limits.
Events and actions adds cooperative notifications and approved commands without creating a second transport or authority plane.
Composition and lifecycle shows what the server host, connector, browser application, and deployment must each initialize and operate.
For the broader extension pattern, see Add optional facilities. For the command guarantees inherited by relay and action calls, use Protocol 1.0.
For a bounded consumer example, see the Sitewatch cooperative-site relay.