From b63794b53c8310b42e0d2a77a7cbfd482be81727 Mon Sep 17 00:00:00 2001
From: Jeroen <jjansen@gmail.com>
Date: Tue, 6 Oct 2026 17:00:50 +0200
Subject: [PATCH] [web_server_idf] Respect explicit HTTP header limit (#18657)

Co-authored-by: jeroen85 <26403565+jeroen85@users.noreply.github.com>
Co-authored-by: Jeroen Jansen <jeroen@Jeroens-MacBook-Air.local>
---
 esphome/components/esp32/__init__.py          |  7 ++--
 esphome/components/web_server_idf/__init__.py |  4 +--
 .../web_server/test_httpd_sdkconfig.py        | 32 +++++++++++++++++++
 .../web_server_header_limit_override.yaml     | 16 ++++++++++
 4 files changed, 54 insertions(+), 5 deletions(-)
 create mode 100644 tests/component_tests/web_server/test_httpd_sdkconfig.py
 create mode 100644 tests/component_tests/web_server/web_server_header_limit_override.yaml

diff --git a/esphome/components/esp32/__init__.py b/esphome/components/esp32/__init__.py
index be6b2c3266..ce1a66a4d2 100644
--- a/esphome/components/esp32/__init__.py
+++ b/esphome/components/esp32/__init__.py
@@ -742,9 +742,10 @@ def is_idf_sdkconfig_option_enabled(name: str) -> bool:
 def set_idf_sdkconfig_default(name: str, value: SdkconfigValueType) -> None:
     """Set an sdkconfig option unless it is already set.
 
-    For the FINAL priority reconcile jobs: they run after every to_code,
-    including the user's sdkconfig_options, and must not override an
-    existing value.
+    User sdkconfig_options take precedence regardless of to_code order:
+    esp32.to_code applies them unconditionally, and this helper preserves
+    values that are already set. FINAL priority reconcile jobs use the same
+    guard because they run after every to_code, including the user's options.
     """
     if name not in CORE.data[KEY_ESP32][KEY_SDKCONFIG_OPTIONS]:
         add_idf_sdkconfig_option(name, value)
diff --git a/esphome/components/web_server_idf/__init__.py b/esphome/components/web_server_idf/__init__.py
index 5a400dfbf3..5eac63212f 100644
--- a/esphome/components/web_server_idf/__init__.py
+++ b/esphome/components/web_server_idf/__init__.py
@@ -1,6 +1,6 @@
 from esphome.components.esp32 import (
-    add_idf_sdkconfig_option,
     include_builtin_idf_component,
+    set_idf_sdkconfig_default,
 )
 from esphome.config_helpers import filter_source_files_from_defines
 import esphome.config_validation as cv
@@ -16,7 +16,7 @@ CONFIG_SCHEMA = cv.All(
 
 async def to_code(config: ConfigType) -> None:
     # Increase the maximum supported size of headers section in HTTP request packet to be processed by the server
-    add_idf_sdkconfig_option("CONFIG_HTTPD_MAX_REQ_HDR_LEN", 1024)
+    set_idf_sdkconfig_default("CONFIG_HTTPD_MAX_REQ_HDR_LEN", 1024)
     # Re-enable esp-tls (excluded by default to save compile time);
     # web_server_idf.cpp includes <esp_tls_crypto.h> for digest auth
     include_builtin_idf_component("esp-tls")
diff --git a/tests/component_tests/web_server/test_httpd_sdkconfig.py b/tests/component_tests/web_server/test_httpd_sdkconfig.py
new file mode 100644
index 0000000000..d3b0acb384
--- /dev/null
+++ b/tests/component_tests/web_server/test_httpd_sdkconfig.py
@@ -0,0 +1,32 @@
+"""Tests for ESP-IDF web server sdkconfig defaults."""
+
+from collections.abc import Callable
+
+from esphome.components.esp32 import RawSdkconfigValue
+from esphome.components.esp32.const import KEY_ESP32, KEY_SDKCONFIG_OPTIONS
+from esphome.core import CORE
+
+
+def test_web_server_idf_uses_default_header_limit(
+    generate_main: Callable[[str], str],
+) -> None:
+    """The web server retains its existing 1024-byte default."""
+    generate_main("tests/component_tests/web_server/web_server_no_auth.yaml")
+
+    assert (
+        CORE.data[KEY_ESP32][KEY_SDKCONFIG_OPTIONS]["CONFIG_HTTPD_MAX_REQ_HDR_LEN"]
+        == 1024
+    )
+
+
+def test_web_server_idf_respects_explicit_header_limit(
+    generate_main: Callable[[str], str],
+) -> None:
+    """An explicit sdkconfig option takes precedence over the component default."""
+    generate_main(
+        "tests/component_tests/web_server/web_server_header_limit_override.yaml"
+    )
+
+    value = CORE.data[KEY_ESP32][KEY_SDKCONFIG_OPTIONS]["CONFIG_HTTPD_MAX_REQ_HDR_LEN"]
+    assert isinstance(value, RawSdkconfigValue)
+    assert value.value == "4096"
diff --git a/tests/component_tests/web_server/web_server_header_limit_override.yaml b/tests/component_tests/web_server/web_server_header_limit_override.yaml
new file mode 100644
index 0000000000..eb1c8a87dd
--- /dev/null
+++ b/tests/component_tests/web_server/web_server_header_limit_override.yaml
@@ -0,0 +1,16 @@
+---
+esphome:
+  name: test
+
+esp32:
+  board: nodemcu-32s
+  framework:
+    type: esp-idf
+    sdkconfig_options:
+      CONFIG_HTTPD_MAX_REQ_HDR_LEN: "4096"
+
+wifi:
+  ssid: MySSID
+  password: password1
+
+web_server: