Add Middleware Support to PySpring Framework

[NFUChen]

Add Middleware Support to PySpring Framework

Overview

This PR introduces comprehensive middleware support to the PySpring framework, allowing developers to easily add custom request/response processing logic to their FastAPI applications. The implementation provides a clean, Spring-inspired middleware architecture with dependency injection support.

🚀 New Features

1. Middleware Base Class (Middleware)

• Location: py_spring_core/core/entities/middlewares/middleware.py
• Purpose: Provides a simplified base class for creating custom middlewares
• Key Features:
  • Inherits from FastAPI's BaseHTTPMiddleware
  • Abstract process_request method for custom logic
  • Automatic request/response flow management
  • Support for early response returns

2. Middleware Registry (MiddlewareRegistry)

• Location: py_spring_core/core/entities/middlewares/middleware_registry.py
• Purpose: Centralized middleware management with single inheritance pattern
• Key Features:
  • Abstract base class for middleware registration
  • Single inheritance enforcement via SingleInheritanceRequired
  • Automatic middleware application to FastAPI app
  • Dependency injection support for middleware classes

3. Single Inheritance Interface (SingleInheritanceRequired)

• Location: py_spring_core/core/interfaces/single_inheritance_required.py
• Purpose: Enforces single inheritance pattern for registry classes
• Key Features:
  • Generic type support
  • Subclass validation
  • Automatic subclass retrieval

🔧 Core Framework Updates

PySpring Application Updates

• File: py_spring_core/core/application/py_spring_application.py
• Changes:
  • Replaced controller-level middleware registration with centralized approach
  • Added __init_middlewares() method for automatic middleware initialization
  • Enhanced logging for middleware initialization process
  • Automatic dependency injection for middleware classes and registry

RestController Simplification

• File: py_spring_core/core/entities/controllers/rest_controller.py
• Changes:
  • Removed register_middlewares() method (no longer needed)
  • Updated documentation to reflect new middleware approach
  • Cleaner controller implementation

📦 Package Updates

Version Bump

• From: 0.0.18 → 0.0.19
• Reason: New middleware functionality addition

Dependencies

• Added: pytest-asyncio>=1.1.0 for async test support

Public API Exports

• Added: Middleware and MiddlewareRegistry to __all__ list

🧪 Comprehensive Test Suite

Test Coverage

• File: tests/test_middleware.py (389 lines)
• Coverage Areas:
  • Middleware base class functionality
  • Middleware registry operations
  • Integration testing with FastAPI
  • Single inheritance enforcement
  • Type hint validation
  • Async middleware execution
  • Request/response flow testing

Test Categories

1. Unit Tests: Individual component testing
2. Integration Tests: FastAPI application integration
3. Async Tests: Proper async/await handling
4. Type Tests: Type hint and inheritance validation

💡 Usage Example

from py_spring_core import Middleware, MiddlewareRegistry
from fastapi import Request, Response

# Define custom middleware
class AuthMiddleware(Middleware):
    async def process_request(self, request: Request) -> Response | None:
        if not request.headers.get("Authorization"):
            return Response(content="Unauthorized", status_code=401)
        return None

# Create middleware registry
class AppMiddlewareRegistry(MiddlewareRegistry):
    def get_middleware_classes(self) -> list[type[Middleware]]:
        return [AuthMiddleware]

# PySpring automatically discovers and applies middlewares

🔄 Breaking Changes

For Existing Users

• Removed: register_middlewares() method from RestController
• Migration: Middleware registration now happens through MiddlewareRegistry subclass
• Impact: Low - existing controllers without custom middleware remain unaffected

🎯 Benefits

1. Simplified Development: Clean, Spring-inspired middleware API
2. Dependency Injection: Automatic DI support for middleware classes
3. Type Safety: Comprehensive type hints and validation
4. Testability: Extensive test coverage with async support
5. Flexibility: Support for early returns and complex middleware chains
6. Maintainability: Centralized middleware management

📋 Checklist

• ✅ New middleware base class implementation
• ✅ Middleware registry with single inheritance
• ✅ Application context integration
• ✅ Automatic middleware discovery and application
• ✅ Comprehensive test suite (389 lines)
• ✅ Type hints and documentation
• ✅ Version bump and dependency updates
• ✅ Public API exports
• ✅ Breaking changes documented

🔍 Testing

Run the test suite to verify all functionality:

pytest tests/test_middleware.py -v

All tests should pass, including async middleware execution and integration tests.

---

Note: This PR maintains backward compatibility while introducing powerful new middleware capabilities that align with Spring Framework patterns.