test: add integration test for idle session cleanup (issue #1283)

Add tests/issues/test_1283_idle_session_cleanup.py demonstrating the memory
leak from issue #1283 where idle sessions are never cleaned up. The tests
verify:

1. Sessions are terminated and removed after idle timeout expires
2. Activity (requests) resets the idle timer and prevents premature reaping
3. Multiple sessions are reaped independently

Github-Issue: #1283

Author: felixweinberger

tests/issues/test_1283_idle_session_cleanup.py

@@ -0,0 +1,159 @@
+"""Test for issue #1283 - Memory leak from idle sessions never being cleaned up.
+
+Without an idle timeout mechanism, sessions created via StreamableHTTPSessionManager
+persist indefinitely in ``_server_instances`` even after the client disconnects.
+Over time this leaks memory.
+
+The ``session_idle_timeout`` parameter on ``StreamableHTTPSessionManager`` allows
+the manager to automatically terminate and remove sessions that have been idle for
+longer than the configured duration.
+
+These tests verify:
+1. Sessions are terminated after idle timeout expires.
+2. Activity (requests) resets the idle timer and prevents premature reaping.
+3. After activity stops, the session is eventually cleaned up.
+"""
+
+import anyio
+import pytest
+from starlette.types import Message
+
+from mcp.server.lowlevel import Server
+from mcp.server.streamable_http import MCP_SESSION_ID_HEADER
+from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+
+
+def _make_scope() -> dict:
+    return {
+        "type": "http",
+        "method": "POST",
+        "path": "/mcp",
+        "headers": [(b"content-type", b"application/json")],
+    }
+
+
+async def _mock_receive() -> Message:  # pragma: no cover
+    return {"type": "http.request", "body": b"", "more_body": False}
+
+
+def _make_send(sent: list[Message]):
+    async def mock_send(message: Message) -> None:
+        sent.append(message)
+
+    return mock_send
+
+
+def _extract_session_id(sent_messages: list[Message]) -> str:
+    for msg in sent_messages:
+        if msg["type"] == "http.response.start":
+            for name, value in msg.get("headers", []):
+                if name.decode().lower() == MCP_SESSION_ID_HEADER.lower():
+                    return value.decode()
+    raise AssertionError("Session ID not found in response headers")
+
+
+def _make_blocking_run(stop_event: anyio.Event):
+    """Create a mock app.run that blocks until stop_event is set."""
+
+    async def blocking_run(*args, **kwargs):
+        await stop_event.wait()
+
+    return blocking_run
+
+
+@pytest.mark.anyio
+async def test_idle_session_is_reaped():
+    """Session should be removed from _server_instances after idle timeout."""
+    app = Server("test-idle-reap")
+    stop = anyio.Event()
+    app.run = _make_blocking_run(stop)  # type: ignore[assignment]
+
+    manager = StreamableHTTPSessionManager(
+        app=app,
+        session_idle_timeout=0.15,
+    )
+
+    async with manager.run():
+        sent: list[Message] = []
+        await manager.handle_request(_make_scope(), _mock_receive, _make_send(sent))
+        session_id = _extract_session_id(sent)
+
+        assert session_id in manager._server_instances
+
+        # Wait long enough for the reaper to fire (scan_interval = timeout/2 = 0.075s)
+        await anyio.sleep(0.4)
+
+        assert session_id not in manager._server_instances
+        assert session_id not in manager._last_activity
+
+        # Let the server task finish cleanly
+        stop.set()
+
+
+@pytest.mark.anyio
+async def test_activity_resets_idle_timer():
+    """Requests during the timeout window should prevent the session from being reaped."""
+    app = Server("test-idle-reset")
+    stop = anyio.Event()
+    app.run = _make_blocking_run(stop)  # type: ignore[assignment]
+
+    manager = StreamableHTTPSessionManager(
+        app=app,
+        session_idle_timeout=0.3,
+    )
+
+    async with manager.run():
+        sent: list[Message] = []
+        await manager.handle_request(_make_scope(), _mock_receive, _make_send(sent))
+        session_id = _extract_session_id(sent)
+
+        # Simulate ongoing activity by updating the activity timestamp periodically
+        for _ in range(4):
+            await anyio.sleep(0.1)
+            manager._last_activity[session_id] = anyio.current_time()
+
+        # Session should still be alive because we kept it active
+        assert session_id in manager._server_instances
+
+        # Now stop activity and let the timeout expire
+        await anyio.sleep(0.6)
+
+        assert session_id not in manager._server_instances
+
+        stop.set()
+
+
+@pytest.mark.anyio
+async def test_multiple_sessions_reaped_independently():
+    """Each session tracks its own idle timeout independently."""
+    app = Server("test-multi-idle")
+    stop = anyio.Event()
+    app.run = _make_blocking_run(stop)  # type: ignore[assignment]
+
+    manager = StreamableHTTPSessionManager(
+        app=app,
+        session_idle_timeout=0.15,
+    )
+
+    async with manager.run():
+        # Create session 1
+        sent1: list[Message] = []
+        await manager.handle_request(_make_scope(), _mock_receive, _make_send(sent1))
+        session_id_1 = _extract_session_id(sent1)
+
+        # Wait a bit, then create session 2
+        await anyio.sleep(0.05)
+        sent2: list[Message] = []
+        await manager.handle_request(_make_scope(), _mock_receive, _make_send(sent2))
+        session_id_2 = _extract_session_id(sent2)
+
+        assert session_id_1 in manager._server_instances
+        assert session_id_2 in manager._server_instances
+
+        # After enough time, both should be reaped
+        await anyio.sleep(0.4)
+
+        assert session_id_1 not in manager._server_instances
+        assert session_id_2 not in manager._server_instances
+
+        stop.set()