fix: drop wall-clock total from MCP relay stream timeouts (#2034)

* fix: drop wall-clock total from MCP relay stream timeouts

An MCP response stream is long-lived by design (the upcoming spec's
subscriptions/listen holds one open indefinitely); the relay's
total=300 wall-clock bound cut healthy streams every 5 minutes and
forced clients to re-subscribe. sock_read idle detection still bounds
a dead stream.

Applied to the ha_mcp_tools component webhook relay and the webhook
proxy dev flavor (2.0.5.dev2); the stable proxy picks it up on the
next promote.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017iTWsCSMPqSHm7Po8yGzfk

* fix: address Codex relay-timeout findings

Add a finite connect bound (30 s) to both relay ClientTimeouts: it
covers connection-POOL acquisition, so a pool occupied by long-lived
streams fails a new request instead of hanging it forever now that
total is gone. Replace the hard-coded stable relay_timeout_total test
expectation with a source-derived predicate that flips automatically
when the promote workflow copies the dev tree — a hard-coded 300 would
have failed every generated promotion PR.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017iTWsCSMPqSHm7Po8yGzfk

* chore: re-bump webhook-proxy-dev to 2.0.5.dev3 after #2033 merged dev2

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017iTWsCSMPqSHm7Po8yGzfk

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: kingpanther13

custom_components/ha_mcp_tools/mcp_webhook.py

@@ -100,8 +100,15 @@
 # instead of a mislabeled JSON blob. ``text/html`` and friends stay coerced.
 _ALLOWED_CONTENT_TYPES = ("application/json", "text/event-stream", "text/plain")
 
-# Long timeout for streamed MCP responses (matches mcp_proxy).
-_CLIENT_TIMEOUT = aiohttp.ClientTimeout(total=300, sock_connect=10, sock_read=300)
+# Timeout for streamed MCP responses (matches mcp_proxy). Deliberately NO
+# wall-clock ``total``: an MCP response stream is long-lived by design (the
+# upcoming spec's ``subscriptions/listen`` holds one open indefinitely), so a
+# ``total`` bound would cut a *healthy* stream and force the client to
+# re-subscribe. ``sock_read`` bounds a *dead* one instead — idle detection, not
+# elapsed time. ``connect`` stays finite: it covers connection-POOL acquisition
+# (not just the TCP connect ``sock_connect`` bounds), so a pool exhausted by
+# long-lived streams fails a new request in 30 s instead of hanging it forever.
+_CLIENT_TIMEOUT = aiohttp.ClientTimeout(connect=30, sock_connect=10, sock_read=300)
 
 # TOP-LEVEL hass.data flag recording that the ha_auth discovery views are bound
 # for this HA session. Deliberately NOT under DOMAIN so it survives

homeassistant-addon-webhook-proxy-dev/CHANGELOG.md

@@ -9,6 +9,18 @@ history from before the fork.
 -->
 
 
+## v2.0.5.dev3 (2026-07-26)
+
+### Bug Fixes
+
+- Drop the 5-minute wall-clock `total` timeout from the relay's HTTP client so a
+  long-lived MCP response stream (the upcoming spec's `subscriptions/listen`) is
+  no longer cut every 300 s, forcing the client to re-subscribe. The `sock_read`
+  idle timeout still bounds a dead stream, and a new finite `connect` bound
+  keeps connection-pool acquisition from hanging new requests when long-lived
+  streams occupy the pool.
+
+
 ## v2.0.5.dev2 (2026-07-25)
 
 ### Features

homeassistant-addon-webhook-proxy-dev/config.yaml

@@ -1,6 +1,6 @@
 name: "Nabu Casa - Webhook Proxy for HA MCP (Dev)"
 description: "DEV CHANNEL (unstable) — remote access proxy via Nabu Casa or any reverse proxy. Cannot run alongside the stable Webhook Proxy add-on."
-version: "2.0.5.dev2"
+version: "2.0.5.dev3"
 slug: "ha_mcp_webhook_proxy_dev"
 url: "https://github.com/homeassistant-ai/ha-mcp"
 stage: experimental

homeassistant-addon-webhook-proxy-dev/mcp_proxy_dev/__init__.py

@@ -725,8 +725,17 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
             "this webhook will be logged here."
         )
 
+    # Timeout for streamed MCP responses (matches the ha_mcp_tools custom
+    # component). Deliberately NO wall-clock ``total``: an MCP response stream
+    # is long-lived by design (the upcoming spec's ``subscriptions/listen``
+    # holds one open indefinitely), so a ``total`` bound would cut a *healthy*
+    # stream and force the client to re-subscribe. ``sock_read`` bounds a
+    # *dead* one instead — idle detection, not elapsed time. ``connect`` stays
+    # finite: it covers connection-POOL acquisition (not just the TCP connect
+    # ``sock_connect`` bounds), so a pool exhausted by long-lived streams fails
+    # a new request in 30 s instead of hanging it forever.
     session = aiohttp.ClientSession(
-        timeout=aiohttp.ClientTimeout(total=300, sock_connect=10, sock_read=300),
+        timeout=aiohttp.ClientTimeout(connect=30, sock_connect=10, sock_read=300),
     )
 
     try:

homeassistant-addon-webhook-proxy-dev/mcp_proxy_dev/manifest.json

@@ -7,5 +7,5 @@
   "dependencies": ["webhook"],
   "documentation": "https://github.com/homeassistant-ai/ha-mcp",
   "iot_class": "local_push",
-  "version": "2.0.5.dev2"
+  "version": "2.0.5.dev3"
 }

tests/addon/test_webhook_proxy.py

@@ -13,6 +13,7 @@
 import tempfile
 import time
 import types
+from dataclasses import dataclass
 from pathlib import Path
 from unittest.mock import AsyncMock, MagicMock, patch
 
@@ -48,6 +49,22 @@
     },
 }
 
+
+def _relay_total_unbounded() -> bool:
+    """Feature-detect whether the CURRENT flavor's relay session drops the
+    wall-clock ``total`` bound (long-lived MCP response streams). The marker is
+    the ``Deliberately NO wall-clock`` comment the dev change introduced next
+    to the relay ``ClientTimeout``; deriving the expectation from the staged
+    source (instead of a hard-coded variant value) means the stable flavor's
+    expectation flips automatically when the promote workflow copies the dev
+    tree across — a hard-coded ``300`` would fail every generated promotion PR."""
+    path = os.path.join(PROXY_ADDON_DIR, CURRENT["component"], "__init__.py")
+    if not os.path.exists(path):
+        return False
+    with open(path, encoding="utf-8") as fh:
+        return "Deliberately NO wall-clock" in fh.read()
+
+
 # Rebound per-variant by the autouse `_webhook_proxy_variant` fixture below.
 PROXY_ADDON_DIR = WEBHOOK_PROXY_VARIANTS["stable"]["addon_dir"]
 CURRENT = WEBHOOK_PROXY_VARIANTS["stable"]
@@ -93,6 +110,22 @@ class _FakeConfigEntryError(Exception):
     pass
 
 
+@dataclass(frozen=True)
+class _FakeClientTimeout:
+    """Field-faithful stand-in for ``aiohttp.ClientTimeout``.
+
+    Mirrors aiohttp's own defaults — every bound is ``None`` unless passed — so
+    tests can assert on the timeout object the relay session is built with,
+    including the bounds it deliberately leaves unset.
+    """
+
+    total: float | None = None
+    connect: float | None = None
+    sock_read: float | None = None
+    sock_connect: float | None = None
+    ceil_threshold: float = 5
+
+
 def _install_runtime_stubs():
     """Inject homeassistant.* and aiohttp stubs into sys.modules.
 
@@ -119,7 +152,7 @@ def _install_runtime_stubs():
 
     aiohttp_mod = types.ModuleType("aiohttp")
     aiohttp_mod.ClientSession = MagicMock(name="ClientSession")
-    aiohttp_mod.ClientTimeout = MagicMock(name="ClientTimeout")
+    aiohttp_mod.ClientTimeout = _FakeClientTimeout
     aiohttp_mod.ClientError = type("ClientError", (Exception,), {})
     aiohttp_web = types.ModuleType("aiohttp.web")
     aiohttp_web.Request = MagicMock
@@ -1414,6 +1447,62 @@ async def test_no_config_file_returns_true(self, mod, hass):
         assert mod.DOMAIN not in hass.data
 
 
+class TestRelaySessionTimeout:
+    """An MCP response stream may stay open indefinitely (the upcoming spec's
+    ``subscriptions/listen``), so the relay session is bounded by read idleness
+    rather than elapsed wall-clock time — a ``total`` bound would cut a healthy
+    stream and force the client to re-subscribe."""
+
+    @pytest.fixture
+    def mod(self):
+        return _import_mcp_proxy()
+
+    @pytest.fixture
+    def hass(self):
+        h = MagicMock()
+        h.data = {}
+
+        async def run_executor(func, *args):
+            return func(*args)
+
+        h.async_add_executor_job = AsyncMock(side_effect=run_executor)
+        return h
+
+    async def _setup_timeout(self, mod, hass):
+        proxy_config = {
+            "target_url": "http://127.0.0.1:9583/private_zctpwlX7ZkIAr7oqdfLPxw",
+            "webhook_id": "mcp_test_webhook_id_12345",
+        }
+        with (
+            patch.object(mod, "_read_config", return_value=proxy_config),
+            patch.object(mod, "async_register"),
+            patch.object(
+                mod.aiohttp, "ClientSession", return_value=MagicMock()
+            ) as mock_session,
+        ):
+            await mod.async_setup_entry(hass, MagicMock())
+        return mock_session.call_args.kwargs["timeout"]
+
+    async def test_wall_clock_total_bound(self, mod, hass):
+        timeout = await self._setup_timeout(mod, hass)
+        if _relay_total_unbounded():
+            assert timeout.total is None
+        else:
+            # Pre-promote stable still carries the wall-clock cap; the
+            # source-derived predicate flips this branch off on promotion.
+            assert timeout.total == 300
+
+    async def test_idle_and_connect_bounds_still_set(self, mod, hass):
+        timeout = await self._setup_timeout(mod, hass)
+        assert timeout.sock_read == 300
+        assert timeout.sock_connect == 10
+        if _relay_total_unbounded():
+            # Pool-acquisition bound: with ``total`` gone, ``connect`` is what
+            # keeps a pool exhausted by long-lived streams from hanging new
+            # requests forever.
+            assert timeout.connect == 30
+
+
 class TestUnloadEntry:
     @pytest.fixture
     def mod(self):

tests/src/unit/_embedded_stubs.py

@@ -399,10 +399,26 @@ def _make_fake_web() -> SimpleNamespace:
     )
 
 
+@dataclass(frozen=True)
+class ClientTimeout:
+    """Field-faithful stand-in for ``aiohttp.ClientTimeout``.
+
+    Mirrors aiohttp's own defaults — every bound is ``None`` unless passed — so
+    tests can assert on the timeout object the relay session is built with,
+    including the bounds it deliberately leaves unset.
+    """
+
+    total: float | None = None
+    connect: float | None = None
+    sock_read: float | None = None
+    sock_connect: float | None = None
+    ceil_threshold: float = 5
+
+
 def _make_fake_aiohttp() -> ModuleType:
     mod = ModuleType("aiohttp")
     mod.ClientError = ClientError  # type: ignore[attr-defined]
-    mod.ClientTimeout = MagicMock(name="ClientTimeout")  # type: ignore[attr-defined]
+    mod.ClientTimeout = ClientTimeout  # type: ignore[attr-defined]
     mod.ClientSession = MagicMock(name="ClientSession")  # type: ignore[attr-defined]
     mod.web = _make_fake_web()  # type: ignore[attr-defined]
     return mod

tests/src/unit/test_mcp_webhook.py

@@ -306,6 +306,28 @@ async def test_none_mode_forwards_200_and_ignores_bearer(self):
         request.read.assert_awaited()
 
 
+# ---------------------------------------------------------------------------
+# Relay client timeout
+# ---------------------------------------------------------------------------
+
+
+class TestRelayClientTimeout:
+    """An MCP response stream may stay open indefinitely (the upcoming spec's
+    ``subscriptions/listen``), so the relay session must be bounded by read
+    idleness, never by elapsed wall-clock time."""
+
+    def test_no_wall_clock_total_bound(self):
+        assert mw._CLIENT_TIMEOUT.total is None
+
+    def test_idle_and_connect_bounds_still_set(self):
+        assert mw._CLIENT_TIMEOUT.sock_read == 300
+        assert mw._CLIENT_TIMEOUT.sock_connect == 10
+        # Pool-acquisition bound: with ``total`` gone, ``connect`` is what
+        # keeps a pool exhausted by long-lived streams from hanging new
+        # requests forever.
+        assert mw._CLIENT_TIMEOUT.connect == 30
+
+
 # ---------------------------------------------------------------------------
 # Auth gate — ha_auth posture
 # ---------------------------------------------------------------------------