Connection and negotiation
A Cheetah WebSocket becomes a command route only after the server has validated transport posture, protocol compatibility, credentials, and the hello message. An accepted hello creates an authenticated route; the client then prepares its runtime with the negotiated configuration before exposing itself as ready for application work.
The hello message
The first WebSocket application message must be hello:
{
"type": "hello",
"client_id": "browser-main",
"instance_id": "runtime-018f7",
"protocol_version": "1.0",
"auth_token": "opaque-host-credential",
"timestamp_ms": 1784455200000,
"transport_security": { "mode": "strict" },
"client_type": "browser"
}| Field | Meaning |
|---|---|
client_id | stable logical address within the authenticated principal |
instance_id | current runtime lifetime; a rebuilt runtime uses a new value |
protocol_version | one exact version offered by the client |
auth_token | credential interpreted by the server authentication provider |
timestamp_ms | client-generated protocol timestamp in milliseconds |
transport_security.mode | strict or explicitly insecure development posture |
client_type | runtime family used for capability and state interpretation |
The hello can also advertise action names and descriptors, client configuration, metadata, and trace identity. Action advertisement is a startup snapshot, not a live guarantee that every target or permission remains available. Metadata must not carry credentials or secrets.
The TypeScript runtime calls the credential supplied by its host auth_proof; the serialized wire field is auth_token.
Exact protocol compatibility
The server accepts only versions listed in WebSocketNodeConfig.supported_protocol_versions. By default, the set contains the configured canonical version, 1.0. An unsupported but well-formed version is rejected with unsupported_protocol_version before authentication or registration.
This is compatibility checking, not version-range negotiation. The server does not choose a nearby version, downgrade the client, or fall back automatically. Configure each client runtime's protocolVersion to one exact version accepted by the deployment. The supplied TypeScript transport treats an unsupported version as fatal and stops its ordinary reconnect loop until configuration or software changes.
Transport posture is part of admission
In strict mode, the server needs trustworthy evidence that the externally observed WebSocket is secure and that the advertised HTTP return endpoint is secure. TLS may terminate at a proxy, but the transport adapter must receive trusted external scheme information. Arbitrary forwarded headers are not trustworthy by default.
Plaintext is accepted only when both sides explicitly select debug_insecure. This mode is for a controlled local development path. It is not inferred from a loopback address and should not appear in a production client configuration.
Transport posture is checked before credentials create a route. This avoids authenticating a session and only later discovering that its return endpoint or externally observed connection does not meet the deployment's security contract.
Acceptance and rejection
An accepted acknowledgement contains the effective principal and the service configuration the runtime may use:
{
"type": "hello_ack",
"accepted": true,
"user_id": "usr_02cd8db7-d030-4daf-ae72-810d4606fb42",
"config": {
"rest_message_endpoint": "https://api.example.test/cheetah/messages"
},
"heartbeat_interval_ms": 25000,
"acknowledged_actions": ["read_page"],
"timestamp_ms": 1784455200120
}The acknowledgement may also carry server configuration. A rejection has accepted: false and a reason, but no usable service configuration. A client must not retain an endpoint or server setting from an earlier accepted connection after a later hello is rejected.
Invalid JSON in the first message receives an invalid_json rejection and policy close. A different first message family receives expected_hello_message. Missing or malformed fields, unsupported transport posture, unsupported version, and failed authentication are rejected before registration. Shared-tenancy authentication failures are intentionally presented as a generic auth_failed result so detailed tenant-claim errors do not leak to the remote client.
Accepted is not yet application-ready
After an accepted acknowledgement, the supplied TypeScript runtime starts heartbeat handling and applies the negotiated endpoint and server settings. During this preparation it holds incoming commands in a bounded, ordered pre-ready buffer. The default bounds are 256 commands and 4 MiB for one connection generation.
Preparation is generation-fenced: completion from a superseded socket cannot make the new generation ready. If preparation fails or the buffer overflows, the runtime closes and reconnects visibly rather than silently running commands against stale configuration. An accepted socket is therefore a valid transport route, but application readiness begins only after this preparation step succeeds.
Heartbeat, reconnect, and replacement
The heartbeat repeats the logical and runtime IDs for observability:
{
"type": "heartbeat",
"client_id": "browser-main",
"instance_id": "runtime-018f7",
"timestamp_ms": 1784455225000
}The server refreshes liveness through the already authenticated connection route. Repeating IDs in the heartbeat body cannot re-authenticate or retarget that socket.
A transport reconnect made by the same live runtime preserves client_id and instance_id. A rebuilt browser service worker, restarted console, or other replacement keeps the stable logical client ID but creates a new instance ID. Registering that new instance replaces the current route and fences acknowledgements and returns tied to an older attempted delivery.
Client-generated timestamps are useful protocol evidence, but they are not measurements from the server clock. Use explicit server observations for lease, timeout, and operational decisions that require server time.