refactor(routing)!: Refactor routes and route handlers (#3386)

* remove handler names
* Remove option handler creation from HTTPRoute
* Remove methods attribute from BaseRoute
* Move kwargs model to handlers and creation to on_registration
* Store kwargs model on handlers instead of routes
* Simplify HTTPRoute route_handler_map creation
* Simplify Router.route_handler_method_map
* Relax typing of HTTPRoute
* Move handling logic to route handlers
* Remove scope_type
* Don't pass route to HTTPRouteHandler during handling
* Don't pass scope to handle methods
* Resolve and establish connections in routes; Only pass connections to handlers

---------

Co-authored-by: Jacob Coffee <[email protected]>
Co-authored-by: Peter Schutt <[email protected]>

docs/conf.py

@@ -222,6 +222,7 @@
  (PY_RE, r"advanced_alchemy\.config.common\.EngineT"),
  (PY_RE, r"advanced_alchemy\.config.common\.SessionT"),
  (PY_RE, r".*R"),
+ (PY_RE, r".*ScopeT"),
  (PY_OBJ, r"litestar.security.jwt.auth.TokenT"),
  (PY_CLASS, "ExceptionToProblemDetailMapType"),
  (PY_CLASS, "litestar.security.jwt.token.JWTDecodeOptions"),

litestar/_asgi/routing_trie/mapping.py

@@ -143,8 +143,7 @@ def configure_node(
  node.path_parameters = {}
 
  if isinstance(route, HTTPRoute):
- for method, handler_mapping in route.route_handler_map.items():
- handler, _ = handler_mapping
+ for method, handler in route.route_handler_map.items():
  node.asgi_handlers[method] = ASGIHandlerTuple(
  asgi_app=build_route_middleware_stack(app=app, route=route, route_handler=handler),
  handler=handler,

litestar/_openapi/path_item.py

@@ -35,9 +35,7 @@ def create_path_item(self) -> PathItem:
  Returns:
  A PathItem instance.
  """
- for http_method, handler_tuple in self.route.route_handler_map.items():
- route_handler, _ = handler_tuple
-
+ for http_method, route_handler in self.route.route_handler_map.items():
  if not route_handler.resolve_include_in_schema():
  continue
 

litestar/_openapi/plugin.py

@@ -198,7 +198,7 @@ def receive_route(self, route: BaseRoute) -> None:
  if not isinstance(route, HTTPRoute):
  return
 
- if any(route_handler.resolve_include_in_schema() for route_handler, _ in route.route_handler_map.values()):
+ if any(route_handler.resolve_include_in_schema() for route_handler in route.route_handler_map.values()):
  # Force recompute the schema if a new route is added
  self._openapi = None
  self.included_routes[route.path] = route

litestar/app.py

@@ -44,7 +44,6 @@
 )
 from litestar.plugins.base import CLIPlugin
 from litestar.router import Router
-from litestar.routes import ASGIRoute, HTTPRoute, WebSocketRoute
 from litestar.stores.registry import StoreRegistry
 from litestar.types import Empty, TypeDecodersSequence
 from litestar.types.internal_types import PathParameterDefinition, TemplateConfigType
@@ -67,6 +66,7 @@
  from litestar.openapi.spec import SecurityRequirement
  from litestar.openapi.spec.open_api import OpenAPI
  from litestar.response import Response
+ from litestar.routes import ASGIRoute, HTTPRoute, WebSocketRoute
  from litestar.stores.base import Store
  from litestar.types import (
  AfterExceptionHookHandler,
@@ -668,14 +668,7 @@ def register(self, value: ControllerRouterHandler) -> None: # type: ignore[over
  route_handlers = get_route_handlers(route)
 
  for route_handler in route_handlers:
- route_handler.on_registration(self)
-
- if isinstance(route, HTTPRoute):
- route.create_handler_map()
-
- elif isinstance(route, WebSocketRoute):
- handler = route.route_handler
- route.handler_parameter_model = handler.create_kwargs_model(path_parameters=route.path_parameters)
+ route_handler.on_registration(self, route=route)
 
  for plugin in self.plugins.receive_route:
  plugin.receive_route(route)

litestar/handlers/asgi_handlers.py

@@ -11,6 +11,7 @@
 
 
 if TYPE_CHECKING:
+ from litestar.connection import ASGIConnection
  from litestar.types import (
  ExceptionHandlersMap,
  Guard,
@@ -82,5 +83,22 @@ def _validate_handler_function(self) -> None:
  if not is_async_callable(self.fn):
  raise ImproperlyConfiguredException("Functions decorated with 'asgi' must be async functions")
 
+ async def handle(self, connection: ASGIConnection[ASGIRouteHandler, Any, Any, Any]) -> None:
+ """ASGI app that authorizes the connection and then awaits the handler function.
+
+ .. versionadded: 3.0
+
+ Args:
+ connection: The ASGI connection
+
+ Returns:
+ None
+ """
+
+ if self.resolve_guards():
+ await self.authorize_connection(connection=connection)
+
+ await self.fn(scope=connection.scope, receive=connection.receive, send=connection.send)
+
 
 asgi = ASGIRouteHandler

litestar/handlers/base.py

@@ -2,7 +2,7 @@
 
 from copy import copy
 from functools import partial
-from typing import TYPE_CHECKING, Any, Callable, Mapping, Sequence, cast
+from typing import TYPE_CHECKING, Any, Callable, Iterable, Mapping, Sequence, cast
 
 from litestar._signature import SignatureModel
 from litestar.di import Provide
@@ -34,9 +34,9 @@
  from litestar.dto import AbstractDTO
  from litestar.params import ParameterKwarg
  from litestar.router import Router
+ from litestar.routes import BaseRoute
  from litestar.types import AnyCallable, AsyncAnyCallable, ExceptionHandler
  from litestar.types.empty import EmptyType
- from litestar.types.internal_types import PathParameterDefinition
 
 __all__ = ("BaseRouteHandler",)
 
@@ -526,11 +526,12 @@ def _validate_dependency_is_unique(dependencies: dict[str, Provide], key: str, p
  f"If you wish to override a provider, it must have the same key."
  )
 
- def on_registration(self, app: Litestar) -> None:
+ def on_registration(self, app: Litestar, route: BaseRoute) -> None:
  """Called once per handler when the app object is instantiated.
 
  Args:
  app: The :class:`Litestar<.app.Litestar>` app object.
+ route: The route this handler is being registered on
 
  Returns:
  None
@@ -567,9 +568,9 @@ def __str__(self) -> str:
  target = type(target)
  return f"{target.__module__}.{target.__qualname__}"
 
- def create_kwargs_model(
+ def _create_kwargs_model(
  self,
- path_parameters: dict[str, PathParameterDefinition],
+ path_parameters: Iterable[str],
  ) -> KwargsModel:
  """Create a `KwargsModel` for a given route handler."""
  from litestar._kwargs import KwargsModel
@@ -578,6 +579,6 @@ def create_kwargs_model(
  signature_model=self.signature_model,
  parsed_signature=self.parsed_fn_signature,
  dependencies=self.resolve_dependencies(),
- path_parameters=set(path_parameters.keys()),
+ path_parameters=set(path_parameters),
  layered_parameters=self.resolve_layered_parameters(),
  )

litestar/handlers/http_handlers/_options.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterable
+
+from litestar.enums import HttpMethod, MediaType
+from litestar.handlers import HTTPRouteHandler
+from litestar.response import Response
+from litestar.status_codes import HTTP_204_NO_CONTENT
+
+if TYPE_CHECKING:
+ from litestar.types import Method
+
+
+def create_options_handler(path: str, allow_methods: Iterable[Method]) -> HTTPRouteHandler:
+ """Args:
+ path: The route path
+
+ Returns:
+ An HTTP route handler for OPTIONS requests.
+ """
+
+ def options_handler() -> Response:
+ """Handler function for OPTIONS requests.
+
+ Returns:
+ Response
+ """
+ return Response(
+ content=None,
+ status_code=HTTP_204_NO_CONTENT,
+ headers={"Allow": ", ".join(sorted(allow_methods))}, # pyright: ignore
+ media_type=MediaType.TEXT,
+ )
+
+ return HTTPRouteHandler(
+ path=path,
+ http_method=[HttpMethod.OPTIONS],
+ include_in_schema=False,
+ sync_to_thread=False,
+ )(options_handler)

litestar/handlers/http_handlers/_utils.py

@@ -4,6 +4,7 @@
 from inspect import isawaitable
 from typing import TYPE_CHECKING, Any, Sequence, cast
 
+from litestar.datastructures import UploadFile
 from litestar.enums import HttpMethod
 from litestar.exceptions import ValidationException
 from litestar.response import Response
@@ -215,3 +216,9 @@ def is_empty_response_annotation(return_annotation: FieldDefinition) -> bool:
 
 
 HTTP_METHOD_NAMES = {m.value for m in HttpMethod}
+
+
+async def cleanup_temporary_files(form_data: dict[str, Any]) -> None:
+ for v in form_data.values():
+ if isinstance(v, UploadFile) and not v.file.closed:
+ await v.close()