WebSocket Event Hub & Telemetry Scaling

Cockpit utilizes a real-time event distribution hub to stream operational events and telemetry updates to client browsers. This architecture permits instant UI synchronization without requiring client-side polling.

---

Event Routing Architecture

The event hub utilizes WebSockets for client connections and PostgreSQL advisory notifications for inter-node communication:

• Upstream WebSocket Streaming: Clients establish persistent WebSocket connections to the /api/v1/events endpoint. This link remains open, allowing the server to push events directly to the browser.
• Inter-Node Routing (pg_notify): In multi-instance Cockpit deployments, clients may connect to different nodes. When a state change occurs on a Vapor host connected to Cockpit Instance A, that instance writes the event to the database and calls the PostgreSQL pg_notify channel. Cockpit Instance B, listening on the same channel, receives the notification and pushes it to its locally connected WebSocket clients.

┌──────────────┐   WebSocket    ┌──────────────┐   pg_notify    ┌──────────────┐   WebSocket    ┌──────────┐
│  Vapor Host  │───────────────►│  Cockpit #1  │───────────────►│  Cockpit #2  │───────────────►│ Browser  │
│  (Physical   │                │ (Active Node)│                │ (Active Node)│                │  Client  │
│   Server)    │                └──────────────┘                └──────────────┘                └──────────┘
└──────────────┘

---

Message Frame Structure

All events exchanged over the WebSocket interface are framed using a standardized JSON schema:

{
  "type": "<message_type>",
  "payload": {
    "kind": "<channel_name>",
    "data": { ... }
  }
}

Client Request Types

• auth: Transmits the JSON Web Token (JWT) credentials to authenticate the session.
• subscribe: Registers the client session to receive updates from a specific event channel.
• unsubscribe: Unregisters the client session from an event channel.

Server Response Types

• auth: Confirms authentication status.
• event: Delivers the payload associated with a subscribed event channel.
• error: Indicates request errors (e.g., token expiration or permission failure).

---

Supported Event Channels

To receive metrics or event updates, client browsers subscribe to specific channels:

Channel Name	Description
host-metrics:<host_id>	Streams real-time host-level CPU, memory, and disk I/O metrics.
vm-events:<host_id>	Broadcasts virtual machine lifecycle updates (e.g., VM start, shutdown, or crash events) for a specific host.
vm-metrics:<host_id>	Streams aggregated performance charts for all virtual machines running on the specified host.
vm-volume-migration-events:<uuid>:<disk>	Streams progress indicators (0% to 100%) for active storage migration processes.
task-events	Broadcasts status updates for system background operations (e.g., VM backup creation, template creation, or host syncs).