docs(esp_http_server): adds doc and migration entry for ws server post handshake cb

Closes https://github.com/espressif/esp-idf/issues/18539
2026-10-01 18:50:34 +03:00 · 2026-06-05 17:31:43 +08:00
parent a0688c6e32
commit 4852f54610
1 changed files with 74 additions and 0 deletions
@@ -104,6 +104,80 @@ The deprecated :cpp:func:`esp_tls_conn_http_new` function has been removed. Use

 The new API requires you to create the :cpp:type:`esp_tls_t` structure using :cpp:func:`esp_tls_init` and provides better control over the connection process.

+ESP HTTP Server
+---------------
+
+WebSocket Handler No Longer Called During Handshake
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+From v6.0.1, the URI handler registered
+for a WebSocket endpoint is **no longer called** during the WebSocket handshake.
+Prior to this change, the handler was invoked with ``req->method == HTTP_GET``
+immediately after the handshake completed, which applications used for
+connection-time initialization:
+
+.. code-block:: c
+
+    /* Pre-v6.0.1 pattern — no longer works from v6.0.1 onwards */
+    static esp_err_t ws_handler(httpd_req_t *req)
+    {
+        if (req->method == HTTP_GET) {
+            ESP_LOGI(TAG, "New WebSocket connection established");
+            return ESP_OK;
+        }
+        /* Handle WebSocket frames ... */
+    }
+
+From v6.0.1, the handler is invoked only for subsequent WebSocket data frames,
+so the ``HTTP_GET`` check is no longer needed in frame handlers.
+
+Migration Options
+^^^^^^^^^^^^^^^^^
+
+**Option 1 (Recommended)** — Move connection-time logic into a dedicated post-handshake callback:
+
+1. Enable :ref:`CONFIG_HTTPD_WS_POST_HANDSHAKE_CB_SUPPORT` in menuconfig.
+2. Register a ``ws_post_handshake_cb`` on the ``httpd_uri_t`` struct. The frame handler
+   remains clean with no ``HTTP_GET`` check.
+
+.. code-block:: c
+
+    static esp_err_t ws_on_connect(httpd_req_t *req)
+    {
+        ESP_LOGI(TAG, "New WebSocket connection established");
+        return ESP_OK;
+    }
+
+    static esp_err_t ws_handler(httpd_req_t *req)
+    {
+        /* Handle WebSocket frames only */
+    }
+
+    static const httpd_uri_t ws_uri = {
+        .uri                  = "/ws",
+        .method               = HTTP_GET,
+        .handler              = ws_handler,
+        .is_websocket         = true,
+        .ws_post_handshake_cb = ws_on_connect,
+    };
+
+**Option 2 (Minimal change)** — Set ``.ws_post_handshake_cb`` to the same function as ``.handler``:
+
+1. Enable :ref:`CONFIG_HTTPD_WS_POST_HANDSHAKE_CB_SUPPORT` in menuconfig.
+2. Set ``.ws_post_handshake_cb = ws_handler`` in the URI registration. The existing
+   ``if (req->method == HTTP_GET)`` check inside the handler continues to work
+   without any further code changes.
+
+.. code-block:: c
+
+    static const httpd_uri_t ws_uri = {
+        .uri                  = "/ws",
+        .method               = HTTP_GET,
+        .handler              = ws_handler,
+        .is_websocket         = true,
+        .ws_post_handshake_cb = ws_handler,   /* same function restores old behavior */
+    };
+
 ESP-Modbus
 ----------