Improve performance and reorganise code (#655)

* Improve performance and reorganise code
* Add internal updates for fast dispatching
* Update release notes

Author: tarsil

docs/en/docs/release-notes.md

@@ -5,6 +5,29 @@ hide:
 
 # Release Notes
 
+## 0.3.8
+
+!!! Note
+    This release focuses on performance and request-path optimization while preserving
+    existing routing and middleware behavior.
+
+### Added
+
+- New `benchmark_mode` setting for Ravyn applications.
+  When enabled, Ravyn uses a minimal middleware pipeline that runs directly through the router,
+  making micro-benchmark runs more representative of pure routing/handler overhead.
+
+### Changed
+
+- Optimized static HTTP route dispatch with an exact `method + path` fast lookup for safe route layouts.
+- Added a zero-kwargs handler fast path for simple endpoints, reducing per-request overhead when no request-bound kwargs are required.
+- Improved internal routing activation flow to precompute and refresh fast dispatch structures.
+
+### Fixed
+
+- Preserved route precedence guarantees for complex routing trees while introducing fast dispatch (includes, hosts, and dynamic routes continue to behave as expected).
+- Added tests validating benchmark mode wiring and middleware stack behavior.
+
 ## 0.3.7
 
 !!! Note

ravyn/__init__.py

@@ -2,7 +2,7 @@
 
 from monkay import Monkay
 
-__version__ = "0.3.7"
+__version__ = "0.3.8"
 
 if TYPE_CHECKING:
     from lilya import status

ravyn/applications.py

@@ -1,6 +1,6 @@
 import warnings
 from collections.abc import Callable, Iterable, Sequence
-from contextlib import asynccontextmanager
+from contextlib import asynccontextmanager, nullcontext
 from datetime import timezone as dtimezone
 from inspect import isclass
 from typing import (
@@ -56,7 +56,6 @@
 from ravyn.middleware.cors import CORSMiddleware
 from ravyn.middleware.csrf import CSRFMiddleware
 from ravyn.middleware.exceptions import (
-    ExceptionMiddleware,
     RavynAPIException,
 )
 from ravyn.middleware.trustedhost import TrustedHostMiddleware
@@ -134,6 +133,7 @@ class Application(BaseLilya):
         "deprecated",
         "description",
         "enable_openapi",
+        "benchmark_mode",
         "enable_scheduler",
         "exception_handlers",
         "include_in_schema",
@@ -1443,6 +1443,17 @@ async def home() -> dict[str, str]:
                 """
             ),
         ] = None,
+        benchmark_mode: Annotated[
+            Optional[bool],
+            Doc(
+                """
+                Enables a minimal middleware pipeline optimized for benchmark runs.
+
+                This mode bypasses the app-level middleware wrappers and executes
+                directly through the router.
+                """
+            ),
+        ] = None,
         redirect_slashes: Annotated[
             Optional[bool],
             Doc(
@@ -1636,6 +1647,9 @@ def extend(self, config: PluggableConfig) -> None:
         self.enable_openapi = self.load_settings_value(
             "enable_openapi", enable_openapi, is_boolean=True
         )
+        self.benchmark_mode = bool(
+            self.load_settings_value("benchmark_mode", benchmark_mode, is_boolean=True)
+        )
         self.redirect_slashes = self.load_settings_value(
             "redirect_slashes", redirect_slashes, is_boolean=True
         )
@@ -2683,6 +2697,9 @@ def build_user_middleware_stack(self) -> list["DefineMiddleware"]:
 
         It evaluates the middleware passed into the routes from bottom up
         """
+        if self.benchmark_mode:
+            return []
+
         user_middleware = []
 
         if self.allowed_hosts:
@@ -2727,6 +2744,9 @@ def build_middleware_stack(self) -> "ASGIApp":
         For APIViews, since it's a "wrapper", the handler will update the current list to contain
         both.
         """
+        if self.benchmark_mode:
+            return self.router
+
         debug = self.debug
         error_handler = None
         exception_handlers = {}
@@ -2751,11 +2771,6 @@ def build_middleware_stack(self) -> "ASGIApp":
             ]
             + self.user_middleware
             + [
-                DefineMiddleware(
-                    ExceptionMiddleware,
-                    handlers=exception_handlers,
-                    debug=debug,
-                ),
                 DefineMiddleware(
                     AsyncExitStackMiddleware,
                     config=self.async_exit_config,
@@ -2844,15 +2859,20 @@ def default_settings(
         return monkay_for_settings.settings
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
-        with monkay_for_settings.with_settings(self.settings):
+        settings_context = (
+            monkay_for_settings.with_settings(self.settings)
+            if self.settings_module is not None
+            else nullcontext()
+        )
+        with settings_context:
             if scope["type"] == "lifespan":
                 await self.router.lifespan(scope, receive, send)
                 return
 
             if self.root_path:
                 scope["root_path"] = self.root_path
 
-            scope["state"] = {}
+            scope.setdefault("state", {})
             await super().__call__(scope, receive, send)
 
     def websocket_route(self, path: str, name: Optional[str] = None) -> Callable:

ravyn/conf/global_settings.py

@@ -456,6 +456,17 @@ class AppSettings(RavynSettings):
             """
         ),
     ] = True
+    benchmark_mode: Annotated[
+        bool,
+        Doc(
+            """
+            Enables a minimal middleware pipeline optimized for benchmark runs.
+
+            When set to `True`, Ravyn bypasses app-level middleware wrappers and
+            runs directly through the router.
+            """
+        ),
+    ] = False
     redirect_slashes: Annotated[
         bool,
         Doc(

ravyn/middleware/asyncexitstack.py

@@ -8,6 +8,25 @@
 from ravyn.core.protocols.middleware import MiddlewareProtocol
 
 
+class _LazyAsyncExitStack:
+    __slots__ = ("_stack",)
+
+    def __init__(self) -> None:
+        self._stack: AsyncExitStack | None = None
+
+    def _ensure(self) -> AsyncExitStack:
+        if self._stack is None:
+            self._stack = AsyncExitStack()
+        return self._stack
+
+    async def aclose(self) -> None:
+        if self._stack is not None:
+            await self._stack.aclose()
+
+    def __getattr__(self, item: str) -> object:
+        return getattr(self._ensure(), item)
+
+
 class AsyncExitStackMiddleware(MiddlewareProtocol):
     def __init__(
         self,
@@ -32,12 +51,15 @@ async def __call__(self, scope: "Scope", receive: "Receive", send: "Send") -> No
             await self.app(scope, receive, send)  # pragma: no cover
 
         exception: Optional[Exception] = None
-        async with AsyncExitStack() as stack:
-            scope[self.config.context_name] = stack
-            try:
-                await self.app(scope, receive, send)
-            except Exception as e:
-                exception = e
+        lazy_stack = _LazyAsyncExitStack()
+        scope[self.config.context_name] = lazy_stack
+        scope["_ravyn_route_boundary"] = True
+        try:
+            await self.app(scope, receive, send)
+        except Exception as e:
+            exception = e
+        finally:
+            await lazy_stack.aclose()
 
         if exception and self.debug:
             traceback.print_exception(exception, exception, exception.__traceback__)  # type: ignore

ravyn/middleware/exceptions.py

@@ -1,6 +1,8 @@
 from typing import Any, Callable, Mapping, Optional, Type, Union
 
 from lilya import status
+from lilya.compat import is_async_callable
+from lilya.concurrency import run_in_threadpool
 from lilya.exceptions import HTTPException as LilyaException
 from lilya.middleware.exceptions import ExceptionMiddleware as LilyaExceptionMiddleware
 from lilya.responses import Response as LilyaResponse
@@ -87,17 +89,26 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
             await self.app(scope, receive, send)
         except Exception as ex:
             if scope["type"] == ScopeType.HTTP:
-                exception_handler = (
-                    self.get_exception_handler(self.exception_handlers, ex)
-                    or self.default_http_exception_handler
-                )
-                response = exception_handler(Request(scope, receive, send), ex)
+                exception_handler = self.get_exception_handler(self.exception_handlers, ex)
+                if (
+                    exception_handler is None
+                    and scope.get("_ravyn_route_boundary")
+                    and isinstance(ex, (HTTPException, LilyaException))
+                ):
+                    exception_handler = http_exception_handler  # type: ignore
+                if exception_handler is None:
+                    exception_handler = self.default_http_exception_handler  # type: ignore
+                request = Request(scope, receive, send)
+                if is_async_callable(exception_handler):
+                    response = await exception_handler(request, ex)
+                else:
+                    response = await run_in_threadpool(exception_handler, request, ex)
                 await response(scope, receive, send)
                 return
 
             if isinstance(ex, WebSocketException):
                 code = ex.code
-                reason = ex.detail
+                reason = ex.reason
             elif isinstance(ex, LilyaException):
                 code = ex.status_code + 4000
                 reason = ex.detail
@@ -149,6 +160,13 @@ def get_exception_handler(
         if not exception_handlers:
             return None
 
-        return self.exception_handlers.get(status_code) or self.exception_handlers.get(
-            exc.__class__
-        )
+        handler = self.exception_handlers.get(status_code)
+        if handler is not None:
+            return handler
+
+        for exc_cls in type(exc).__mro__:
+            handler = self.exception_handlers.get(exc_cls)
+            if handler is not None:
+                return handler
+
+        return None