From 18f0d028066fe6feab9d4262bcd3f663f6711f34 Mon Sep 17 00:00:00 2001
From: bryghtlabs-richard
 <146753361+bryghtlabs-richard@users.noreply.github.com>
Date: Wed, 22 Oct 2025 16:25:31 -0500
Subject: [PATCH] feat(websocket): add WEBSOCKET_EVENT_HEADER_RECEIVED (#827)

Send a new event for each HTTP header-line received.

Depends on https://github.com/espressif/esp-idf/pull/16119
Closes https://github.com/espressif/esp-protocols/issues/715
---
 .../esp_websocket_client/esp_websocket_client.c     | 12 ++++++++++++
 .../examples/linux/main/websocket_linux.c           |  5 +++++
 .../examples/target/main/websocket_example.c        |  5 +++++
 .../include/esp_websocket_client.h                  | 13 ++++++++++++-
 4 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/components/esp_websocket_client/esp_websocket_client.c b/components/esp_websocket_client/esp_websocket_client.c
index 87c3a7e6f..9f82d42fc 100644
--- a/components/esp_websocket_client/esp_websocket_client.c
+++ b/components/esp_websocket_client/esp_websocket_client.c
@@ -484,6 +484,14 @@ static esp_err_t stop_wait_task(esp_websocket_client_handle_t client)
     return ESP_OK;
 }
 
+#if WS_TRANSPORT_HEADER_CALLBACK_SUPPORT
+static void websocket_header_hook(void * client, const char * line, int line_len)
+{
+    ESP_LOGD(TAG, "%s header:%.*s", __func__, line_len, line);
+    esp_websocket_client_dispatch_event(client, WEBSOCKET_EVENT_HEADER_RECEIVED, line, line_len);
+}
+#endif
+
 static esp_err_t set_websocket_transport_optional_settings(esp_websocket_client_handle_t client, const char *scheme)
 {
     esp_transport_handle_t trans = esp_transport_list_get_transport(client->transport_list, scheme);
@@ -493,6 +501,10 @@ static esp_err_t set_websocket_transport_optional_settings(esp_websocket_client_
             .sub_protocol = client->config->subprotocol,
             .user_agent = client->config->user_agent,
             .headers = client->config->headers,
+#if WS_TRANSPORT_HEADER_CALLBACK_SUPPORT
+            .header_hook = websocket_header_hook,
+            .header_user_context = client,
+#endif
             .auth = client->config->auth,
             .propagate_control_frames = true
         };
diff --git a/components/esp_websocket_client/examples/linux/main/websocket_linux.c b/components/esp_websocket_client/examples/linux/main/websocket_linux.c
index a0d00a9f6..0a1cf935a 100644
--- a/components/esp_websocket_client/examples/linux/main/websocket_linux.c
+++ b/components/esp_websocket_client/examples/linux/main/websocket_linux.c
@@ -29,6 +29,11 @@ static void websocket_event_handler(void *handler_args, esp_event_base_t base, i
     case WEBSOCKET_EVENT_BEGIN:
         ESP_LOGI(TAG, "WEBSOCKET_EVENT_BEGIN");
         break;
+#if WS_TRANSPORT_HEADER_CALLBACK_SUPPORT
+    case WEBSOCKET_EVENT_HEADER_RECEIVED:
+        ESP_LOGI(TAG, "WEBSOCKET_EVENT_HEADER_RECEIVED: %.*s", data->data_len, data->data_ptr);
+        break;
+#endif
     case WEBSOCKET_EVENT_CONNECTED:
         ESP_LOGI(TAG, "WEBSOCKET_EVENT_CONNECTED");
         break;
diff --git a/components/esp_websocket_client/examples/target/main/websocket_example.c b/components/esp_websocket_client/examples/target/main/websocket_example.c
index 7d7a1121c..c13703f9e 100644
--- a/components/esp_websocket_client/examples/target/main/websocket_example.c
+++ b/components/esp_websocket_client/examples/target/main/websocket_example.c
@@ -77,6 +77,11 @@ static void websocket_event_handler(void *handler_args, esp_event_base_t base, i
     case WEBSOCKET_EVENT_BEGIN:
         ESP_LOGI(TAG, "WEBSOCKET_EVENT_BEGIN");
         break;
+#if WS_TRANSPORT_HEADER_CALLBACK_SUPPORT
+    case WEBSOCKET_EVENT_HEADER_RECEIVED:
+        ESP_LOGI(TAG, "WEBSOCKET_EVENT_HEADER_RECEIVED: %.*s", data->data_len, data->data_ptr);
+        break;
+#endif
     case WEBSOCKET_EVENT_CONNECTED:
         ESP_LOGI(TAG, "WEBSOCKET_EVENT_CONNECTED");
         break;
diff --git a/components/esp_websocket_client/include/esp_websocket_client.h b/components/esp_websocket_client/include/esp_websocket_client.h
index c125a6e35..84a3d26ae 100644
--- a/components/esp_websocket_client/include/esp_websocket_client.h
+++ b/components/esp_websocket_client/include/esp_websocket_client.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -14,6 +14,7 @@
 #include "freertos/FreeRTOS.h"
 #include "esp_err.h"
 #include "esp_event.h"
+#include "esp_idf_version.h"
 #include <sys/socket.h>
 #include "esp_transport_ws.h"
 
@@ -21,6 +22,13 @@
 extern "C" {
 #endif
 
+#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 0, 0)
+// Features supported in 6.0.0
+#define WS_TRANSPORT_HEADER_CALLBACK_SUPPORT    1
+#else
+#define WS_TRANSPORT_HEADER_CALLBACK_SUPPORT    0
+#endif
+
 typedef struct esp_websocket_client *esp_websocket_client_handle_t;
 
 ESP_EVENT_DECLARE_BASE(WEBSOCKET_EVENTS);         // declaration of the task events family
@@ -31,6 +39,9 @@ ESP_EVENT_DECLARE_BASE(WEBSOCKET_EVENTS);         // declaration of the task eve
 typedef enum {
     WEBSOCKET_EVENT_ANY = -1,
     WEBSOCKET_EVENT_ERROR = 0,      /*!< This event occurs when there are any errors during execution */
+#if WS_TRANSPORT_HEADER_CALLBACK_SUPPORT
+    WEBSOCKET_EVENT_HEADER_RECEIVED,/*!< This event occurs for each pre-upgrade HTTP header */
+#endif
     WEBSOCKET_EVENT_CONNECTED,      /*!< Once the Websocket has been connected to the server, no data exchange has been performed */
     WEBSOCKET_EVENT_DISCONNECTED,   /*!< The connection has been disconnected */
     WEBSOCKET_EVENT_DATA,           /*!< When receiving data from the server, possibly multiple portions of the packet */