Create the routing cache per router instance

ASGIRouter.handle_routing was decorated with a class-level lru_cache, which
acts as a garbage collection root: every router instance (and, through it,
every Litestar app with all of its state) stayed strongly referenced by the
cache forever, so apps were never garbage collected. Long-running processes
that create many app instances (e.g. test suites) accumulated them all.

Bind the cache per instance in __init__ instead
(self.handle_routing = lru_cache(1024)(self._handle_routing)). The cache then
only participates in a self-referential cycle that the garbage collector can
reclaim once the app is no longer referenced. The call surface is unchanged,
including cache_clear()/cache_info() on the bound cache.

Fixes #4876

Author: uttam12331

litestar/_asgi/asgi_router.py

@@ -55,6 +55,7 @@ class ASGIRouter:
         "_static_routes",
         "_trie_initialized",
         "app",
+        "handle_routing",
         "root_route_map_node",
         "route_handler_index",
         "route_mapping",
@@ -73,6 +74,10 @@ def __init__(self, app: Litestar) -> None:
         self._registered_routes: set[HTTPRoute | WebSocketRoute | ASGIRoute] = set()
         self._trie_initialized = False
         self.app = app
+        # The routing cache is created per instance: a class-level lru_cache would
+        # act as a GC root keeping every router (and through it, every app) alive
+        # forever. See https://github.com/litestar-org/litestar/issues/4876
+        self.handle_routing = lru_cache(1024)(self._handle_routing)
         self.root_route_map_node: RouteTrieNode = create_node()
         self.route_handler_index: dict[str, RouteHandlerType] = {}
         self.route_mapping: dict[str, list[BaseRoute]] = defaultdict(list)
@@ -109,12 +114,14 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
             scope["path_template"] = path_template
         await asgi_app(scope, receive, send)
 
-    @lru_cache(1024)  # noqa: B019
-    def handle_routing(
+    def _handle_routing(
         self, path: str, method: Method | None
     ) -> tuple[ASGIApp, RouteHandlerType, str, dict[str, Any], str]:
         """Handle routing for a given path / method combo. This method is meant to allow easy caching.
 
+        The cached version of this method is available as ``self.handle_routing``,
+        set up in ``__init__``.
+
         Args:
             path: The path of the request.
             method: The scope's method, if any.

tests/unit/test_asgi/test_asgi_router.py

@@ -271,3 +271,29 @@ async def handler() -> None:
     assert state.exception_handlers is not Empty
     assert state.exception_handlers[RuntimeError] is app_exception_handlers_mock
     assert state.exception_handlers[TypeError] is handler_exception_handlers_mock
+
+
+def test_routing_cache_does_not_prevent_garbage_collection() -> None:
+    """The routing cache must not keep the app alive after all references are dropped.
+
+    A class-level ``lru_cache`` on ``handle_routing`` acted as a GC root anchoring
+    every router (and, through it, every app) forever.
+    https://github.com/litestar-org/litestar/issues/4876
+    """
+    import gc
+
+    def make_app_and_request() -> int:
+        # The client (which references the app) must go out of scope before
+        # collecting, hence the helper function.
+        @get("/ping", sync_to_thread=False)
+        def ping() -> str:
+            return "pong"
+
+        app = Litestar(route_handlers=[ping])
+        with TestClient(app) as client:
+            assert client.get("/ping").status_code == 200
+        return id(app)
+
+    app_id = make_app_and_request()
+    gc.collect()
+    assert not any(id(obj) == app_id for obj in gc.get_objects() if type(obj) is Litestar)