Event hub doc

docs/Parallels_Desktop_API.postman_collection.json

@@ -92,6 +92,87 @@
 				}
 			]
 		},
+		{
+			"name": "Events Hub",
+			"item": [
+				{
+					"name": "Subscribe (WebSocket handshake)",
+					"request": {
+						"method": "GET",
+						"header": [
+							{
+								"key": "Authorization",
+								"value": "Bearer {{token}}"
+							},
+							{
+								"key": "X-Source-Id",
+								"value": "Postman"
+							}
+						],
+						"url": {
+							"raw": "{{protocol}}://{{host}}/api/v1/ws/subscribe?event_types=pdfm,health",
+							"protocol": "{{protocol}}",
+							"host": [
+								"{{host}}"
+							],
+							"path": [
+								"api",
+								"v1",
+								"ws",
+								"subscribe"
+							],
+							"query": [
+								{
+									"key": "event_types",
+									"value": "pdfm,health"
+								}
+							]
+						},
+						"description": "Opens a WebSocket subscription to the Events Hub."
+					},
+					"response": []
+				},
+				{
+					"name": "Unsubscribe from channels",
+					"request": {
+						"method": "POST",
+						"header": [
+							{
+								"key": "Authorization",
+								"value": "Bearer {{token}}"
+							},
+							{
+								"key": "Content-Type",
+								"value": "application/json"
+							},
+							{
+								"key": "X-Source-Id",
+								"value": "Postman"
+							}
+						],
+						"body": {
+							"mode": "raw",
+							"raw": "{\n    \"client_id\": \"{{events_client_id}}\",\n    \"event_types\": [\"pdfm\"]\n}"
+						},
+						"url": {
+							"raw": "{{protocol}}://{{host}}/api/v1/ws/unsubscribe",
+							"protocol": "{{protocol}}",
+							"host": [
+								"{{host}}"
+							],
+							"path": [
+								"api",
+								"v1",
+								"ws",
+								"unsubscribe"
+							]
+						},
+						"description": "Removes one or more channels from an active Events Hub client."
+					},
+					"response": []
+				}
+			]
+		},
 		{
 			"name": "Config",
 			"item": [

docs/_data/docs_devops_menu.yml

@@ -45,3 +45,17 @@
       link: /docs/devops/reverse-proxy/getting-started/
     - name: Configuration
       link: /docs/devops/reverse-proxy/configuration/
+- label: Events Hub
+  items:
+    - name: Overview
+      link: /docs/devops/events-hub/overview/
+    - name: Monitor VM Events
+      link: /docs/devops/events-hub/how-to-monitor-VM-events/
+    - name: Monitor Orchestrator Events
+      link: /docs/devops/events-hub/how-to-monitor-orchestrator-events/
+    - name: Sending Heartbeats
+      link: /docs/devops/events-hub/how-to-send-heartbeat
+    - name: Knowing My Client ID
+      link: /docs/devops/events-hub/how-to-know-my-client-id/  
+    - name: Sending Unsubscribe Requests for Events channel
+      link: /docs/devops/events-hub/how-to-send-unsubscribe-requests/

docs/_includes/head.html

@@ -6,6 +6,10 @@
   <link rel="shortcut icon" type="image/png" {% if site.favicon %} href="{{ site.favicon | relative_url }}" {% else %} href="{{ site.baseurl }}/favicon.ico" {% endif %} />
   <script defer src="https://unpkg.com/[email protected]/dist/cdn.min.js"></script>
   <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,600,300' rel='stylesheet' type='text/css'>
+  <script type="module">
+    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
+    mermaid.initialize({ startOnLoad: true });
+  </script>
   <script type="text/javascript">
     // Clarity Consent Management
     window.ClarityConsent = {

docs/docs/devops/events-hub/how-to-know-my-client-id.md

@@ -0,0 +1,68 @@
+---
+layout: page
+title: Events Hub
+subtitle: How To Know My Client ID
+menubar: docs_devops_menu
+show_sidebar: false
+toc: true
+---
+# How to Know My Client ID
+When you connect to the Events Hub WebSocket service, each client is assigned a unique Client ID. This Client ID is essential for identifying your connection and managing events. Here’s how you can find out your Client ID.
+
+## Steps to Know Your Client ID
+1. First, ensure you have connected to the Events Hub WebSocket service and subscribed to the desired event channels. Refer to the [How to Send Heartbeats]({{ site.url }}{{ site.baseurl }}/docs/devops/events-hub/how-to-send-heartbeat) guide for connection instructions. When you send a ping message to the health channel, you will receive a pong response that includes your Client ID.
+2. Once connected, send a heartbeat ping message to the `health` event channel. A heartbeat message is a simple JSON object like this:
+    ```json
+    {"event_type": "health","message":"ping"}
+    ```
+3. After sending the ping message, you will receive a pong response from the server. The pong response will contain your Client ID in the `client_id` field. A typical pong response looks like this:
+    ```json
+    {
+        "id":"1495c450ab281318efc6b63482fde92630b66c0bf66acd5073fdc3a44402be67","ref_id":"cbd91850fad5fc286caa89916b081c9d34c4b7bde2ce4ce4392f47527a9cc27",
+        "event_type":"health",
+        "timestamp":"2025-12-12T15:57:55.570578Z",
+        "message":"pong",
+        "client_id":"d24c0350-936d-4c7a-8948-36f42343c87c"
+    }
+    ```
+4. Locate the `client_id` field in the pong response to find your unique Client ID.
+5. You can now use this Client ID for managing your connection and subscriptions within the Events Hub.
+
+Alternatively, you can find your Client ID in the initial connection confirmation message you receive when you first connect to the Events Hub. This message includes a `body` section that contains the `client_id`.
+
+You can also send a client info request to the server to retrieve your Client ID. Send a JSON message like this:
+
+```json
+{"event_type": "system","message":"client-id"}
+```
+
+The server will respond with a message containing your Client ID.
+```json
+{
+    "id":"73841562a9753aa06a88623a1d5d47c5e831a6911e4a79d80910d495c4ecedd7","ref_id":"4232a7922d4c21f08f25c0da09b07b74a054d033948cbf53fbaf17808b45069f",
+    "event_type":"system",
+    "timestamp":"2025-12-15T09:30:57.021027Z",
+    "message":"client-id",
+    "body":
+    {
+        "client-id":"26369eda-4802-49f7-a07f-2292721d1724"
+    },
+    "client_id":"26369eda-4802-49f7-a07f-2292721d1724"
+}
+```
+
+## FAQ
+#### Can I change my Client ID?
+No, the Client ID is automatically assigned by the Events Hub service and cannot be changed.
+#### Is the Client ID persistent across sessions?
+No, the Client ID is unique to each connection session. A new Client ID is assigned each time you connect to the Events Hub.
+#### How is the Client ID used?
+The Client ID is used if you want to unsubscribe from specific event channels or manage your subscriptions.
+#### What if I lose my Client ID?
+Send another heartbeat ping message to the `health` channel or a client info request to retrieve your Client ID again.
+#### Can I use the Client ID for multiple connections?
+No, each connection to the Events Hub has its own unique Client ID. You cannot use the same Client ID for multiple connections.
+#### Where can I find more information about unsubscribing using Client ID?
+Refer to the [How To Send Unsubscribe Requests for Events channel]({{ site.url }}{{ site.baseurl }}/docs/devops/events-hub/how-to-send-unsubscribe-requests) guide for detailed instructions on how to use your Client ID to unsubscribe from event channels.
+
+Refer to the troubleshooting section in the [overview guide]({{ site.url }}{{ site.baseurl }}/docs/devops/events-hub/overview#troubleshooting--faq) for common issues.

docs/docs/devops/events-hub/how-to-monitor-VM-events.md

@@ -0,0 +1,147 @@
+---
+layout: page
+title: Events Hub
+subtitle: How to Monitor VM Events
+menubar: docs_devops_menu
+show_sidebar: false
+toc: true
+---
+# How to Monitor VM Events
+
+To monitor VM events in real-time, you can subscribe to the `pdfm` event channel using the Events Hub WebSocket service. This allows you to receive instant notifications about VM lifecycle changes, such as when a VM is started, stopped, or deleted.
+
+<div class="mermaid">
+sequenceDiagram
+    participant Client
+    participant Server
+    Client->>Server: Connect & Subscribe (pdfm)
+    Server-->>Client: Subscription Confirmed
+    Note over Server: VM State Changes (e.g. Running -> Stopped)
+    Server-->>Client: Event: VM_STATE_CHANGED
+</div>
+
+## Steps to Monitor VM Events
+
+1. **Obtain Your Token**: Get a Bearer token or API Key from your
+    administrator, or refer to the
+    [API reference]({{ site.url }}{{ site.baseurl }}/docs/devops/restapi/reference/api_keys).
+2. **Connect to the Events Hub**:
+    You can subscribe to multiple event channels during connection, like `pdfm,health`, to receive both VM events and health check events. For this example, we are subscribing to `pdfm`.
+
+    For simplicity, the examples below use
+    `wscat` (a popular WebSocket client) to connect and subscribe to VM events.
+    You can use any WebSocket client of your choice. Refer to the REST API
+    [reference]({{ site.url }}{{ site.baseurl }}/docs/devops/restapi/reference/events/#v1-ws-subscribe-get)
+    if you want to use another client.
+
+     - Install `wscat` (if not already installed):
+
+         ```bash
+         brew install node
+         npm install -g wscat
+         ```
+
+     - Connect and subscribe to VM events on the `pdfm` channel:
+
+         ```bash
+         wscat -H "Authorization: Bearer <YOUR_TOKEN>" -c "ws://<YOUR_HOST>/api/v1/ws/subscribe?event_types=pdfm"
+         ```
+
+         - Note: Use `wss://` instead of `ws://` if your server
+             is configured for TLS.
+3. **Verify Subscription**: Upon successful connection, you will receive a
+    confirmation message indicating that you are subscribed to the `pdfm`
+    channel.
+
+    Example confirmation message:
+
+    ```json
+     {
+         "id": "985763c36f1a7f04663353ceb5515afaa497414ebec3226e9fa0d475b7713e34",
+         "event_type": "global",
+         "timestamp": "2025-12-11T13:04:37.484843Z",
+         "message": "WebSocket connection established; subscribed to global by default",
+         "body": {
+             "client_id": "338a28f7-666e-46e1-8e7d-4feba5edc061",
+             "subscriptions": [
+                 "pdfm",
+                 "global"
+             ]
+         }
+     }
+    ```
+
+4. **Monitor VM Events**: You will start receiving real-time VM events. Each
+    event contains details about VM state changes (e.g., when a VM starts,
+    stops, or is deleted).
+
+    Example VM state change event:
+
+    ```json
+     {
+         "id": "60adab5b984894719ecb83a0ad7da3d2027a63932c65d0f0585f3762083aa4a1",
+         "event_type": "pdfm",
+         "timestamp": "2025-12-11T13:21:21.514683Z",
+         "message": "VM_STATE_CHANGED",
+         "body": {
+             "previous_state": "suspended",
+             "current_state": "resuming",
+             "vm_id": "fb83295e-0ccb-46b1-8205-b03997f82b00"
+         }
+     }
+    ```
+
+### JSON Object Schemas
+
+On VM state change event:
+
+```go
+type VmStateChange struct {
+    PreviousState string `json:"previous_state"`
+    CurrentState  string `json:"current_state"`
+    VmID          string `json:"vm_id"`
+}
+```
+
+On VM added event:
+
+```json
+{
+    "id": "7cbc843fd99e2965fd4039410a0e20c2984b8b9c8889991954751d66b90cabb1",
+    "event_type": "pdfm",
+    "timestamp": "2025-12-12T12:12:14.164146Z",
+    "message": "VM_ADDED",
+    "body": {
+        "vm_id": "ae032783-53d3-49c3-babf-1475589d9a7b",
+        "new_vm": {
+            "name": "My New VM",
+            "os_type": "ubuntu",
+            "state": "running"
+        }
+    }
+}
+```
+
+On VM removed event:
+
+```json
+{
+    "id": "4f5e6d7c8b9a0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566778899aa",
+    "event_type": "pdfm",
+    "timestamp": "2025-12-12T13:15:20.123456Z",
+    "message": "VM_REMOVED",
+    "body": {
+        "vm_id": "ae032783-53d3-49c3-babf-1475589d9a7b"
+    }
+}
+```
+
+### FAQ
+#### What types of VM events can I monitor?
+You can monitor various VM events such as state changes (started, stopped, suspended, resumed..etc), additions, and deletions.
+#### Can I use other WebSocket clients besides `wscat`?
+Yes, you can use any WebSocket client that supports custom headers for authentication. Just ensure you include the appropriate authorization header.
+#### Is it possible to monitor events for multiple VMs?
+Yes, by subscribing to the `pdfm` event type, you will receive events for all VMs managed by the server.
+
+Refer troubleshooting section in the [overview guide]({{ site.url }}{{ site.baseurl }}/docs/devops/events-hub/overview#troubleshooting--faq) for common issues.