From 9c15f8e7d92f21fb2a3068447e5893425fe06f3b Mon Sep 17 00:00:00 2001 From: Ashish Sharma Date: Mon, 4 May 2026 10:34:02 +0800 Subject: [PATCH 1/2] docs(esp_http_server): adds doc and migration entry for ws server post handshake cb Closes https://github.com/espressif/esp-idf/issues/18539 --- .../release-6.x/6.0/protocols.rst | 74 +++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/docs/en/migration-guides/release-6.x/6.0/protocols.rst b/docs/en/migration-guides/release-6.x/6.0/protocols.rst index 1b39c34cd1b..dcf061ffff9 100644 --- a/docs/en/migration-guides/release-6.x/6.0/protocols.rst +++ b/docs/en/migration-guides/release-6.x/6.0/protocols.rst @@ -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 ---------- From d81a432a019ff6fb294339b055ba8f2ad38cfee4 Mon Sep 17 00:00:00 2001 From: Zhang Shuxian Date: Wed, 27 May 2026 14:33:20 +0800 Subject: [PATCH 2/2] docs: Update CN translation for protocols.rst --- .../release-6.x/6.0/protocols.rst | 18 ++--- .../release-6.x/6.0/protocols.rst | 68 +++++++++++++++++++ 2 files changed, 74 insertions(+), 12 deletions(-) diff --git a/docs/en/migration-guides/release-6.x/6.0/protocols.rst b/docs/en/migration-guides/release-6.x/6.0/protocols.rst index dcf061ffff9..8495cc57ff0 100644 --- a/docs/en/migration-guides/release-6.x/6.0/protocols.rst +++ b/docs/en/migration-guides/release-6.x/6.0/protocols.rst @@ -110,11 +110,9 @@ 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: +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 @@ -128,8 +126,7 @@ connection-time initialization: /* 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. +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 ^^^^^^^^^^^^^^^^^ @@ -137,8 +134,7 @@ 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. +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 @@ -164,9 +160,7 @@ Migration Options **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. +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 diff --git a/docs/zh_CN/migration-guides/release-6.x/6.0/protocols.rst b/docs/zh_CN/migration-guides/release-6.x/6.0/protocols.rst index 06597a93015..07e67ed91f0 100644 --- a/docs/zh_CN/migration-guides/release-6.x/6.0/protocols.rst +++ b/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 ----------