Merge branch 'docs/add_ws_post_handshake_cb_doc_v6.1' into 'release/v6.1'

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

See merge request espressif/esp-idf!49336

docs/en/migration-guides/release-6.x/6.0/protocols.rst

@@ -104,6 +104,74 @@ 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
 ----------
 

docs/zh_CN/migration-guides/release-6.x/6.0/protocols.rst

@@ -104,6 +104,74 @@ ESP-TLS 已移除内置的 wolfSSL TLS 协议栈支持。使用 wolfSSL 的用
 
 新 API 需要您使用 :cpp:func:`esp_tls_init` 创建 :cpp:type:`esp_tls_t` 结构，并提供对连接过程的更好控制。
 
+ESP HTTP 服务器
+---------------
+
+握手期间不再调用 WebSocket 处理器
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+自 v6.0.1 起，已注册的 URI 处理程序在 WebSocket 握手期间，针对 WebSocket 端点的回调 **不再被调用**。
+
+在此更改之前，处理程序会在握手完成后立即以 ``req->method == HTTP_GET`` 的状态被调用，常用于应用程序的连接初始化：
+
+.. code-block:: c
+
+    /* v6.0.1 之前的模式 — 自 v6.0.1 起不再生效 */
+    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;
+        }
+        /* 处理 WebSocket 帧 */
+    }
+
+自 v6.0.1 起，仅会针对后续的 WebSocket 数据帧调用该处理器，因此，帧处理程序中不再需要进行 ``HTTP_GET`` 检查。
+
+迁移选项
+^^^^^^^^^^^^^^^^^
+
+**选项 1（推荐）** — 将连接阶段的逻辑移动到一个专用的握手后回调中：
+
+1. 在 menuconfig 中启用 :ref:`CONFIG_HTTPD_WS_POST_HANDSHAKE_CB_SUPPORT`。
+2. 在 ``httpd_uri_t`` 结构体中注册 ``ws_post_handshake_cb`` 回调，使帧处理程序保持简洁，无需再进行 `HTTP_GET` 状态检查。
+
+.. 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)
+    {
+        /* 仅处理 WebSocket 帧 */
+    }
+
+    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,
+    };
+
+**选项 2（改动最少）** — 将 ``.ws_post_handshake_cb`` 设置为与 ``.handler`` 相同的函数：
+
+1. 在 menuconfig 中启用 :ref:`CONFIG_HTTPD_WS_POST_HANDSHAKE_CB_SUPPORT`。
+2. 在 URI 注册中设置 ``.ws_post_handshake_cb = ws_handler``。现有的 ``if (req->method == HTTP_GET)`` 检查在处理程序内部仍然有效，无需额外修改代码。
+
+.. 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,   /* 同一个函数可恢复原有行为 */
+    };
+
 ESP-Modbus
 ----------