refactor(events): Update event types and related tests to remove deprecated types

Author: sai-kumar-peddireddy

docs/docs/devops/events-hub/index.md docs/docs/devops/events-hub-v1/index.mddocs/docs/devops/events-hub/index.md renamed to docs/docs/devops/events-hub-v1/index.md

@@ -0,0 +1,260 @@
+---
+layout: page
+title: Events Hub Guide
+show_sidebar: false
+---
+
+# Events Hub Guide
+
+The **Events Hub** is a real-time WebSocket service that enables DevOps engineers and SREs to subscribe to critical infrastructure events. Instead of polling REST APIs, you can receive instant updates about host health, VM lifecycle changes, and system alerts.
+
+## Overview
+
+- **Protocol**: WebSocket (RFC 6455)
+- **Endpoint**: `/v1/ws/subscribe`
+- **Auth**: Bearer Token or API Key
+- **Latency**: Sub-millisecond event propogation
+- **Connection Limit**: One active connection per IP address (enforced).
+
+## Quick Start
+
+Connect to the global channel (default) to start receiving events immediately.
+
+### 1. Get your Token
+Obtain a Bearer token or API Key from your administrator.
+
+### 2. Connect
+```bash
+wscat -H "Authorization: Bearer <YOUR_TOKEN>" -c "wss://<YOUR_HOST>/v1/ws/subscribe?event_types=pdfm,health"
+```
+
+### 3. Verify
+You will receive a confirmation message:
+```json
+{
+  "type": "global",
+  "message": "WebSocket connection established subscribed to global by default",
+  "body": {
+    "subscriptions": ["pdfm", "health", "global"]
+  }
+}
+```
+
+## Core Concepts
+
+### Event Channels
+Channels are topics you can subscribe to. You can specify multiple channels during connection.
+
+| Channel | Description | Use Case |
+| :--- | :--- | :--- |
+| **`global`** | System-wide broadcasts. **Auto-subscribed**; cannot be removed. | Critical maintenance alerts, shutdowns. |
+| **`pdfm`** | Host & VM events. | Monitoring VM starts, stops, and host resource changes. |
+| **`orchestrator`** | Cluster-level orchestration events. | tracking task assignments, cluster scaling. |
+| **`health`** | Ping/Pong heartbeat channel. | Implementing liveness checks (see [Client Responsibilities](#client-responsibilities)). |
+| **`system`** | System & Metadata info. | Retrieving your unique `client_id`. |
+
+### Connection Rules
+- **Single Connection per IP**: To prevent resource exhaustion, only one active WebSocket connection is allowed per client IP address. New connection attempts from the same IP will be rejected with `409 Conflict`.
+
+## Real-world Use Cases
+
+### 1. Monitoring VM Lifecycle
+Subscribe to `pdfm` to track VM states in real-time.
+- **Event**: VM Started, VM Stopped, VM Suspended.
+- **Action**: Update dashboard status, trigger billing events.
+
+### 2. Cluster Health Monitoring
+Subscribe to `orchestrator` to detect node failures or capacity issues instantly.
+
+### 3. Connection Liveness Checks
+Subscribe to `health` to implement a heartbeat. If the server stops responding to your pings, you can trigger a reconnection alert.
+
+## Client Responsibilities
+
+### 1. Heartbeat (Ping/Pong)
+The connection is bidirectional. To ensure the link is alive, your client **must** subscribe to the `health` channel and send periodic pings.
+
+**Client Request:**
+```json
+{
+  "type": "health",
+  "id": "ping-1",
+  "message": "ping"
+}
+```
+
+**Server Response:**
+```json
+{
+  "type": "health",
+  "ref_id": "ping-1",
+  "message": "pong",
+  "body": {
+      "server_time": "2023-10-27T10:00:00Z"
+  }
+}
+```
+
+### 2. Client ID Lookup
+After connecting, you might need your unique `client_id` for unsubscribe operations. Send a message to the `system` channel.
+
+**Client Request:**
+```json
+{
+  "type": "system",
+  "message": "client-id"
+}
+```
+
+**Server Response:**
+```json
+{
+  "type": "system",
+  "message": "client-id",
+  "body": {
+    "client-id": "550e8400-e29b-41d4-a716-446655440000"
+  }
+}
+```
+
+## API Reference
+
+### Subscribe
+**GET** `/v1/ws/subscribe`
+
+**Query Parameters:**
+- `event_types` (string, optional): Comma-separated list of channels (e.g., `pdfm,health,orchestrator`). `global` is always added automatically.
+
+**Headers:**
+- `Authorization`: `Bearer <token>`
+
+### Unsubscribe
+**POST** `/v1/ws/unsubscribe`
+
+Allows you to remove specific channel subscriptions without dropping the connection. **Note**: You cannot unsubscribe from `global`.
+
+**Body:**
+```json
+{
+  "client_id": "<your-client-id>",
+  "event_types": ["pdfm"]
+}
+```
+
+## Code Examples
+
+### Node.js (`ws`)
+
+```javascript
+const WebSocket = require('ws');
+
+const ws = new WebSocket('wss://api.example.com/v1/ws/subscribe?event_types=pdfm,health', {
+  headers: { 'Authorization': 'Bearer <YOUR_TOKEN>' }
+});
+
+ws.on('open', () => {
+  console.log('Connected');
+  // Send Heartbeat every 30s
+  setInterval(() => {
+    ws.send(JSON.stringify({ type: 'health', message: 'ping', id: Date.now().toString() }));
+  }, 30000);
+});
+
+ws.on('message', (data) => {
+  const event = JSON.parse(data);
+  if (event.type === 'health' && event.message === 'pong') {
+    console.log('Heartbeat OK');
+  } else {
+    console.log('Event received:', event);
+  }
+});
+```
+
+### Python (`websockets`)
+
+```python
+import asyncio
+import websockets
+import json
+import time
+
+async def listen():
+    uri = "wss://api.example.com/v1/ws/subscribe?event_types=pdfm,health"
+    headers = {"Authorization": "Bearer <YOUR_TOKEN>"}
+    
+    async with websockets.connect(uri, extra_headers=headers) as websocket:
+        print("Connected")
+        
+        while True:
+            # Send Ping
+            await websocket.send(json.dumps({
+                "type": "health", 
+                "message": "ping", 
+                "id": str(time.time())
+            }))
+            
+            # Wait for messages
+            message = await websocket.recv()
+            event = json.loads(message)
+            print(f"Received: {event}")
+
+if __name__ == "__main__":
+    asyncio.run(listen())
+```
+
+### Go (`gorilla/websocket`)
+
+```go
+package main
+
+import (
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+func main() {
+	header := http.Header{}
+	header.Add("Authorization", "Bearer <YOUR_TOKEN>")
+
+	c, _, err := websocket.DefaultDialer.Dial("wss://api.example.com/v1/ws/subscribe?event_types=pdfm,health", header)
+	if err != nil {
+		log.Fatal("dial:", err)
+	}
+	defer c.Close()
+
+	// Heartbeat routine
+	go func() {
+		for {
+			time.Sleep(30 * time.Second)
+			msg := map[string]string{"type": "health", "message": "ping"}
+			c.WriteJSON(msg)
+		}
+	}()
+
+	for {
+		_, message, err := c.ReadMessage()
+		if err != nil {
+			log.Println("read:", err)
+			return
+		}
+		log.Printf("recv: %s", message)
+	}
+}
+```
+
+## Troubleshooting & FAQ
+
+**Q: I get a `409 Conflict` error when connecting.**
+A: You likely have another active connection from the same IP. Close the existing connection or check for "zombie" processes.
+
+**Q: Can I unsubscribe from `global`?**
+A: No, the `global` channel is mandatory for system-wide alerts.
+
+**Q: I'm not receiving pongs.**
+A: Ensure you have subscribed to the `health` channel in your connection URL (`?event_types=health`).
+
+**Q: My connection drops after 60 seconds.**
+A: Check if your client is sending heartbeats. Some load balancers drop idle WebSocket connections.

docs/docs/devops/events-hub-v2/index.md

@@ -8,10 +8,8 @@ type EventType string
 // Clients subscribe to these types and receive messages of that type
 const (
 	EventTypeGlobal       EventType = "global"       // Broadcasts to all subscribers
-	EventTypeSystem       EventType = "system"       // System-level events
-	EventTypeVM           EventType = "vm"           // Virtual machine events
-	EventTypeHost         EventType = "host"         // Host-level events
 	EventTypePDFM         EventType = "pdfm"         // PDFM-specific events
+	EventTypeSystem       EventType = "system"       // System-level events
 	EventTypeHealth       EventType = "health"       // Health check events
 	EventTypeOrchestrator EventType = "orchestrator" // Orchestrator events
 )
@@ -23,7 +21,7 @@ func (e EventType) String() string {
 // IsValid checks if the EventType is valid
 func (e EventType) IsValid() bool {
 	switch e {
-	case EventTypeGlobal, EventTypeSystem, EventTypeVM, EventTypeHost, EventTypePDFM, EventTypeHealth, EventTypeOrchestrator:
+	case EventTypeGlobal, EventTypePDFM, EventTypeSystem, EventTypeHealth, EventTypeOrchestrator:
 		return true
 	default:
 		return false
@@ -34,9 +32,6 @@ func (e EventType) IsValid() bool {
 func GetAllEventTypes() []EventType {
 	return []EventType{
 		EventTypeGlobal,
-		EventTypeSystem,
-		EventTypeVM,
-		EventTypeHost,
 		EventTypePDFM,
 		EventTypeHealth,
 		EventTypeOrchestrator,

src/constants/event_emitter.go

@@ -33,7 +33,7 @@ func registerEventHandlers(ctx basecontext.ApiContext, version string) {
 // @Description	This endpoint upgrades the HTTP connection to WebSocket and subscribes to event notifications. Authentication is required via Authorization header (Bearer token) or X-Api-Key header.
 // @Tags			Events
 // @Produce		json
-// @Param			event_types	query		string	false	"Comma-separated event types to subscribe to (e.g., vm,host,system). Valid types: global, system, vm, host, pdfm. If omitted, subscribes to global events only."
+// @Param			event_types	query		string	false	"Comma-separated event types to subscribe to (e.g., global,pdfm,system). Valid types: global,pdfm and orchestrator. If omitted, subscribes to global events only."
 // @Success		101		{string}	string	"Switching Protocols"
 // @Failure		400		{object}	models.ApiErrorResponse
 // @Failure		401		{object}	models.ApiErrorResponse

src/controllers/events.go

@@ -35,7 +35,7 @@ func TestNewEventMessage_NilBody(t *testing.T) {
 }
 
 func TestNewEventMessage_EmptyMessage(t *testing.T) {
-	msg := NewEventMessage(constants.EventTypeVM, "", map[string]interface{}{})
+	msg := NewEventMessage(constants.EventTypeHealth, "", map[string]interface{}{})
 	assert.NotNil(t, msg)
 	assert.Empty(t, msg.Message)
 	assert.NotEmpty(t, msg.ID)

src/models/event_message_test.go

@@ -10,11 +10,11 @@ import (
 )
 
 func TestStringToEventTypes_ValidTypes(t *testing.T) {
-	result, err := stringToEventTypes([]string{"vm", "host", "global"})
+	result, err := stringToEventTypes([]string{"pdfm", "system", "global"})
 	require.NoError(t, err)
 	expected := []constants.EventType{
-		constants.EventTypeVM,
-		constants.EventTypeHost,
+		constants.EventTypePDFM,
+		constants.EventTypeSystem,
 		constants.EventTypeGlobal,
 	}
 	assert.Equal(t, expected, result)
@@ -27,41 +27,39 @@ func TestStringToEventTypes_EmptySlice(t *testing.T) {
 }
 
 func TestStringToEventTypes_InvalidTypes(t *testing.T) {
-	result, err := stringToEventTypes([]string{"invalid", "vm", "fake"})
+	result, err := stringToEventTypes([]string{"invalid", "pdfm", "fake"})
 	// Should return error but still include valid types
 	assert.Error(t, err)
 	assert.Len(t, result, 1)
-	assert.Equal(t, constants.EventTypeVM, result[0])
+	assert.Equal(t, constants.EventTypePDFM, result[0])
 }
 
 func TestStringToEventTypes_MixedCase(t *testing.T) {
-	result, err := stringToEventTypes([]string{"VM", "Host", "GLOBAL"})
+	result, err := stringToEventTypes([]string{"PDFM", "System", "GLOBAL"})
 	require.NoError(t, err)
 	expected := []constants.EventType{
-		constants.EventTypeVM,
-		constants.EventTypeHost,
+		constants.EventTypePDFM,
+		constants.EventTypeSystem,
 		constants.EventTypeGlobal,
 	}
 	assert.Equal(t, expected, result)
 }
 
 func TestStringToEventTypes_ExtraWhitespace(t *testing.T) {
-	result, err := stringToEventTypes([]string{"  vm  ", " host ", " global "})
+	result, err := stringToEventTypes([]string{"  pdfm  ", " system ", " global "})
 	require.NoError(t, err)
 	expected := []constants.EventType{
-		constants.EventTypeVM,
-		constants.EventTypeHost,
+		constants.EventTypePDFM,
+		constants.EventTypeSystem,
 		constants.EventTypeGlobal,
 	}
 	assert.Equal(t, expected, result)
 }
 
 func TestStringToEventTypes_AllValidTypes(t *testing.T) {
-	result, err := stringToEventTypes([]string{"vm", "host", "global", "system", "pdfm"})
+	result, err := stringToEventTypes([]string{"global", "system", "pdfm"})
 	require.NoError(t, err)
-	assert.Len(t, result, 5)
-	assert.Contains(t, result, constants.EventTypeVM)
-	assert.Contains(t, result, constants.EventTypeHost)
+	assert.Len(t, result, 3)
 	assert.Contains(t, result, constants.EventTypeGlobal)
 	assert.Contains(t, result, constants.EventTypeSystem)
 	assert.Contains(t, result, constants.EventTypePDFM)