Refactor MiddlewareRegistry and Introduce MiddlewareConfiguration

Updated the MiddlewareRegistry class to remove inheritance from SingleInheritanceRequired and added methods for managing middleware registration, including adding, removing, and querying middlewares. Introduced a new MiddlewareConfiguration class for configuring middleware execution order. Updated related imports and adjusted type hints in PySpringApplication for better type safety.

Author: William-W-Chen

py_spring_core/__init__.py

@@ -12,7 +12,7 @@
 from py_spring_core.core.entities.entity_provider.entity_provider import EntityProvider
 from py_spring_core.core.entities.middlewares.middleware import Middleware
 from py_spring_core.core.entities.middlewares.middleware_registry import (
-    MiddlewareRegistry,
+    MiddlewareRegistry, MiddlewareConfiguration
 )
 from py_spring_core.core.entities.properties.properties import Properties
 from py_spring_core.core.interfaces.application_context_required import (
@@ -44,6 +44,7 @@
     "EventListener",
     "Middleware",
     "MiddlewareRegistry",
+    "MiddlewareConfiguration",
     "GracefulShutdownHandler",
     "ShutdownType",
 ]

py_spring_core/core/application/py_spring_application.py

@@ -1,6 +1,6 @@
 import logging
 import os
-from typing import Any, Callable, Iterable, Optional, Type
+from typing import Any, Callable, Iterable, Optional, Type, TypeVar
 
 import uvicorn
 from fastapi import APIRouter, FastAPI
@@ -30,6 +30,7 @@
 from py_spring_core.core.entities.entity_provider.entity_provider import EntityProvider
 from py_spring_core.core.entities.middlewares.middleware import Middleware
 from py_spring_core.core.entities.middlewares.middleware_registry import (
+    MiddlewareConfiguration,
     MiddlewareRegistry,
 )
 from py_spring_core.core.entities.properties.properties import Properties
@@ -45,6 +46,8 @@
 
 import py_spring_core.core.utils as framework_utils
 
+
+SingleInheritanceRequiredT = TypeVar("SingleInheritanceRequiredT", bound=SingleInheritanceRequired)
 class PySpringApplication:
     """
     The PySpringApplication class is the main entry point for the PySpring application.
@@ -237,7 +240,7 @@ def __init_controllers(self) -> None:
             self.fastapi.include_router(router)
             logger.debug(f"[CONTROLLER INIT] Controller {name} initialized")
 
-    def _init_external_handler(self, base_class: Type[SingleInheritanceRequired]) -> Type[Any] | None:
+    def _init_external_handler(self, base_class: Type[SingleInheritanceRequiredT]) -> Type[SingleInheritanceRequiredT] | None:
         """Initialize an external handler (middleware registry or graceful shutdown handler).
         
         Args:
@@ -276,12 +279,15 @@ def _init_external_handler(self, base_class: Type[SingleInheritanceRequired]) ->
     def __init_middlewares(self) -> None:
         handler_type = MiddlewareRegistry.__name__
         logger.debug(f"[{handler_type} INIT] Initialize middlewares...")
-        registry_cls = self._init_external_handler(MiddlewareRegistry)
-        if registry_cls is None:
+        middeware_configuration_cls = self._init_external_handler(MiddlewareConfiguration)
+        if middeware_configuration_cls is None:
             return
-
-        registry: MiddlewareRegistry = registry_cls()
+        registry = MiddlewareRegistry()
+        logger.info(f"[{handler_type} INIT] Setup middlewares for registry: {registry.__class__.__name__}")
+        middeware_configuration_cls().configure_middlewares(registry)
+        logger.info(f"[{handler_type} INIT] Middlewares setup for registry: {registry.__class__.__name__} completed")
         middleware_classes: list[Type[Middleware]] = registry.get_middleware_classes()
+        logger.info(f"[{handler_type} INIT] Middleware classes: {', '.join([middleware_class.__name__ for middleware_class in middleware_classes])}")
         for middleware_class in middleware_classes:
             logger.debug(
                 f"[{handler_type} INIT] Inject dependencies for middleware: {middleware_class.__name__}"
@@ -305,7 +311,7 @@ def __init_graceful_shutdown(self) -> None:
         self.shutdown_handler = handler_cls(
             timeout_seconds=shutdown_config.timeout_seconds,
             timeout_enabled=shutdown_config.enabled
-        )
+        ) # type: ignore
         logger.debug(f"[{handler_type} INIT] Graceful shutdown initialized")
 
     def __configure_uvicorn_logging(self):

py_spring_core/core/entities/middlewares/middleware_registry.py

@@ -9,7 +9,7 @@
 )
 
 
-class MiddlewareRegistry(SingleInheritanceRequired["MiddlewareRegistry"], ABC):
+class MiddlewareRegistry:
     """
     Middleware registry for managing all middlewares
 
@@ -31,20 +31,153 @@ class MiddlewareRegistry(SingleInheritanceRequired["MiddlewareRegistry"], ABC):
     Response: route → MiddlewareA → MiddlewareB
     This stacking behavior ensures that middlewares are executed in a predictable and controllable order.
     """
-
-    @abstractmethod
+    
+    def __init__(self):
+        """
+        Initialize the middleware registry.
+        """
+        self._middlewares: list[Type[Middleware]] = []
+    
+    def add_middleware(self, middleware_class: Type[Middleware]) -> None:
+        """
+        Add middleware to the end of the list.
+        
+        Args:
+            middleware_class: The middleware class to add
+            
+        Raises:
+            ValueError: If middleware is already registered
+        """
+        if middleware_class in self._middlewares:
+            raise ValueError(f"Middleware {middleware_class.__name__} is already registered")
+        self._middlewares.append(middleware_class)
+    
+    def add_at_index(self, index: int, middleware_class: Type[Middleware]) -> None:
+        """
+        Insert middleware at a specific index position.
+        
+        Args:
+            index: The position to insert at (0-based)
+            middleware_class: The middleware class to add
+            
+        Raises:
+            ValueError: If middleware is already registered or index is invalid
+        """
+        if middleware_class in self._middlewares:
+            raise ValueError(f"Middleware {middleware_class.__name__} is already registered")
+        if index < 0 or index > len(self._middlewares):
+            raise ValueError(f"Index {index} is out of range (0-{len(self._middlewares)})")
+        self._middlewares.insert(index, middleware_class)
+    
+    def add_before(self, target_middleware: Type[Middleware], middleware_class: Type[Middleware]) -> None:
+        """
+        Insert middleware before the target middleware.
+        
+        Args:
+            target_middleware: The middleware to insert before
+            middleware_class: The middleware class to add
+            
+        Raises:
+            ValueError: If middleware is already registered or target not found
+        """
+        if middleware_class in self._middlewares:
+            raise ValueError(f"Middleware {middleware_class.__name__} is already registered")
+        if target_middleware not in self._middlewares:
+            raise ValueError(f"Target middleware {target_middleware.__name__} not found")
+        index = self._middlewares.index(target_middleware)
+        self._middlewares.insert(index, middleware_class)
+    
+    def add_after(self, target_middleware: Type[Middleware], middleware_class: Type[Middleware]) -> None:
+        """
+        Insert middleware after the target middleware.
+        
+        Args:
+            target_middleware: The middleware to insert after
+            middleware_class: The middleware class to add
+            
+        Raises:
+            ValueError: If middleware is already registered or target not found
+        """
+        if middleware_class in self._middlewares:
+            raise ValueError(f"Middleware {middleware_class.__name__} is already registered")
+        if target_middleware not in self._middlewares:
+            raise ValueError(f"Target middleware {target_middleware.__name__} not found")
+        index = self._middlewares.index(target_middleware)
+        self._middlewares.insert(index + 1, middleware_class)
+    
+    def remove_middleware(self, middleware_class: Type[Middleware]) -> None:
+        """
+        Remove a middleware from the registry.
+        
+        Args:
+            middleware_class: The middleware class to remove
+            
+        Raises:
+            ValueError: If middleware is not found
+        """
+        if middleware_class not in self._middlewares:
+            raise ValueError(f"Middleware {middleware_class.__name__} not found")
+        self._middlewares.remove(middleware_class)
+    
+    def clear_middlewares(self) -> None:
+        """Remove all middlewares from the registry."""
+        self._middlewares.clear()
+    
+    def has_middleware(self, middleware_class: Type[Middleware]) -> bool:
+        """
+        Check if a middleware is registered.
+        
+        Args:
+            middleware_class: The middleware class to check
+            
+        Returns:
+            bool: True if middleware is registered, False otherwise
+        """
+        return middleware_class in self._middlewares
+    
+    def get_middleware_count(self) -> int:
+        """
+        Get the number of registered middlewares.
+        
+        Returns:
+            int: Number of registered middlewares
+        """
+        return len(self._middlewares)
+    
+    def get_middleware_index(self, middleware_class: Type[Middleware]) -> int:
+        """
+        Get the index of a middleware in the registry.
+        
+        Args:
+            middleware_class: The middleware class to find
+            
+        Returns:
+            int: The index of the middleware
+            
+        Raises:
+            ValueError: If middleware is not found
+        """
+        if middleware_class not in self._middlewares:
+            raise ValueError(f"Middleware {middleware_class.__name__} not found")
+        return self._middlewares.index(middleware_class)
+        
+    
+    
     def get_middleware_classes(self) -> list[Type[Middleware]]:
         """
-        Get all registered middleware classes
-
+        Get all registered middleware classes.
+        
         Returns:
-            List[Type[Middleware]]: List of middleware classes
+            List[Type[Middleware]]: List of middleware classes in registration order
         """
-        pass
-
+        return self._middlewares.copy()
+    
     def apply_middlewares(self, app: FastAPI) -> FastAPI:
         """
-        Apply middlewares to FastAPI application
+        Apply middlewares to FastAPI application.
+        
+        Iterates through all registered middlewares and applies them to the FastAPI
+        application instance in the order they were registered.
 
         Args:
             app: FastAPI application instance
@@ -55,3 +188,16 @@ def apply_middlewares(self, app: FastAPI) -> FastAPI:
         for middleware_class in self.get_middleware_classes():
             app.add_middleware(middleware_class)
         return app
+
+
+
+class MiddlewareConfiguration(SingleInheritanceRequired["MiddlewareConfiguration"]):
+    """
+    Middleware configuration for managing middleware registration and execution order.
+    """
+    
+    def configure_middlewares(self, registry: MiddlewareRegistry) -> None:
+        """
+        Setup middlewares for the registry.
+        """
+        pass