From a9b605e113cc10b26f47d7bc119422022314bff8 Mon Sep 17 00:00:00 2001
From: Razvan Grigore <razvan.grigore@vampirebyte.ro>
Date: Thu, 23 Oct 2025 14:41:34 +0300
Subject: [PATCH] add client disconnect reason text in events

---
 src/WebSocketsClient.cpp | 27 +++++++++++++++++++--------
 src/WebSocketsClient.h   |  5 ++++-
 2 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/src/WebSocketsClient.cpp b/src/WebSocketsClient.cpp
index ea0de6b1..1edb8146 100644
--- a/src/WebSocketsClient.cpp
+++ b/src/WebSocketsClient.cpp
@@ -532,10 +532,11 @@ void WebSocketsClient::messageReceived(WSclient_t * client, WSopcode_t opcode, u
 }
 
 /**
- * Disconnect an client
+ * Disconnect a client
  * @param client WSclient_t *  ptr to the client struct
+ * @param reason const char * disconnect reason (optional, defaults to NULL)
  */
-void WebSocketsClient::clientDisconnect(WSclient_t * client) {
+void WebSocketsClient::clientDisconnect(WSclient_t * client, const char * reason) {
     bool event = false;
 
 #ifdef HAS_SSL
@@ -584,7 +585,11 @@ void WebSocketsClient::clientDisconnect(WSclient_t * client) {
 
     DEBUG_WEBSOCKETS("[WS-Client] client disconnected.\n");
     if(event) {
-        runCbEvent(WStype_DISCONNECTED, NULL, 0);
+        if(reason && strlen(reason) > 0) {
+            runCbEvent(WStype_DISCONNECTED, (uint8_t *)reason, strlen(reason));
+        } else {
+            runCbEvent(WStype_DISCONNECTED, NULL, 0);
+        }
     }
 }
 
@@ -607,13 +612,13 @@ bool WebSocketsClient::clientIsConnected(WSclient_t * client) {
         if(client->status != WSC_NOT_CONNECTED) {
             DEBUG_WEBSOCKETS("[WS-Client] connection lost.\n");
             // do cleanup
-            clientDisconnect(client);
+            clientDisconnect(client, "Connection lost");
         }
     }
 
     if(client->tcp) {
         // do cleanup
-        clientDisconnect(client);
+        clientDisconnect(client, "TCP connection cleanup");
     }
 
     return false;
@@ -625,7 +630,7 @@ bool WebSocketsClient::clientIsConnected(WSclient_t * client) {
 void WebSocketsClient::handleClientData(void) {
     if((_client.status == WSC_HEADER || _client.status == WSC_BODY) && _lastHeaderSent + WEBSOCKETS_TCP_TIMEOUT < millis()) {
         DEBUG_WEBSOCKETS("[WS-Client][handleClientData] header response timeout.. disconnecting!\n");
-        clientDisconnect(&_client);
+        clientDisconnect(&_client, "Header response timeout");
         WEBSOCKETS_YIELD();
         return;
     }
@@ -860,7 +865,9 @@ void WebSocketsClient::handleHeader(WSclient_t * client, String * headerLine) {
                 default:     ///< Server dont unterstand requrst
                     ok = false;
                     DEBUG_WEBSOCKETS("[WS-Client][handleHeader] serverCode is not 101 (%d)\n", client->cCode);
-                    clientDisconnect(client);
+                    // Create disconnect reason with HTTP status code
+                    String reason = "HTTP " + String(client->cCode);
+                    clientDisconnect(client, reason.c_str());
                     _lastConnectionFail = millis();
                     break;
             }
@@ -904,7 +911,11 @@ void WebSocketsClient::handleHeader(WSclient_t * client, String * headerLine) {
             if(clientIsConnected(client)) {
                 write(client, "This is a webSocket client!");
             }
-            clientDisconnect(client);
+            String reason = "WebSocket handshake failed";
+            if(client->cCode > 0) {
+                reason += " - HTTP " + String(client->cCode);
+            }
+            clientDisconnect(client, reason.c_str());
         }
     }
 }
diff --git a/src/WebSocketsClient.h b/src/WebSocketsClient.h
index e1a7a000..f20aad9f 100644
--- a/src/WebSocketsClient.h
+++ b/src/WebSocketsClient.h
@@ -157,7 +157,10 @@ class WebSocketsClient : protected WebSockets {
 
     void messageReceived(WSclient_t * client, WSopcode_t opcode, uint8_t * payload, size_t length, bool fin);
 
-    void clientDisconnect(WSclient_t * client);
+    void clientDisconnect(WSclient_t * client) {
+        clientDisconnect(client, NULL);
+    }
+    void clientDisconnect(WSclient_t * client, const char * reason = NULL);
     bool clientIsConnected(WSclient_t * client);
 
 #if (WEBSOCKETS_NETWORK_TYPE != NETWORK_ESP8266_ASYNC)