Dropped Starlette BaseHTTPMiddleware and added a FunctionBasedMiddleware

Author: eadwinCode

docs/overview/modules.md

@@ -51,7 +51,7 @@ from ellar.core import ModuleBase
     commands=[],
     base_directory=None, 
     static_folder='static', 
-    template_folder='template'
+    template_folder='templates'
 )
 class BookModule(ModuleBase):
     pass
@@ -134,12 +134,12 @@ from ellar.core.context import IExecutionContext
 @Module()
 class ModuleExceptionSample(ModuleBase):
     @exception_handler(404)
-    def exception_404_handler(cls, ctx: IExecutionContext, exc: Exception) -> Response:
+    def exception_404_handler(cls, context: IExecutionContext, exc: Exception) -> Response:
         return JSONResponse(dict(detail="Resource not found."))
 ```
 `exception_404_handler` will be register to the application at runtime during `ModuleExceptionSample` computation.
 
-### **`Module Templating Filters`**
+### **Module Templating Filters**
 We can also define `Jinja2` templating filters in project Modules or any `@Module()` module.
 The defined filters are be passed down to `Jinja2` **environment** instance alongside the `template_folder` 
 value when creating **TemplateLoader**.
@@ -193,6 +193,48 @@ class DogsModule(ModuleBase):
         pass
 ```
 
+## **Module Middleware**
+
+Middlewares functions can be defined at Module level with `@middleware()` function decorator.
+
+For example:
+
+```python
+from ellar.common import Module, middleware
+from ellar.core import ModuleBase
+from ellar.core.context import IExecutionContext
+from starlette.responses import PlainTextResponse
+
+
+@Module()
+class ModuleMiddlewareSample(ModuleBase):
+    @middleware()
+    async def my_middleware_function_1(cls, context: IExecutionContext, call_next):
+        request = context.switch_to_request() # for http response only
+        request.state.my_middleware_function_1 = True
+        await call_next()
+    
+    @middleware()
+    async def my_middleware_function_2(cls, context: IExecutionContext, call_next):
+        connection = context.switch_to_http_connection() # for websocket response only
+        if connection.scope['type'] == 'websocket':
+            websocket = context.switch_to_websocket()
+            websocket.state.my_middleware_function_2 = True
+        await call_next()
+
+    @middleware()
+    async def my_middleware_function_3(cls, context: IExecutionContext, call_next):
+        connection = context.switch_to_http_connection() # for http response only
+        if connection.headers['somekey']:
+            # response = context.get_response() -> use the `response` to add extra definitions to things you want to see on
+            return PlainTextResponse('Header is not allowed.')
+        await call_next()
+```
+Things to note:
+
+- middleware functions must be `async`.
+- middleware functions can return a `response` or modify a `response` returned
+- middleware functions must call `call_next` and `await` its actions as shown above.
 
 ## **Injector Module**
 `EllarInjector` is based on a python library [injector](https://injector.readthedocs.io/en/latest/index.html). Both share similar `Module` features with few distinct features. 

ellar/common/decorators/middleware.py

@@ -1,12 +1,11 @@
 import typing as t
 
-from starlette.middleware.base import BaseHTTPMiddleware
-
 from ellar.constants import MIDDLEWARE_HANDLERS_KEY
+from ellar.core.middleware import FunctionBasedMiddleware
 from ellar.core.middleware.schema import MiddlewareSchema
 
 
-def add_middleware(
+def _add_middleware(
     middleware_class: type, dispatch: t.Callable, **options: t.Any
 ) -> None:
     setattr(
@@ -18,18 +17,16 @@ def add_middleware(
     )
 
 
-def middleware(middleware_type: str) -> t.Callable:
+def middleware() -> t.Callable:
     """
     ========= MODULE DECORATOR ==============
 
     Defines middle functions at module level
-    :param middleware_type: Middleware type
     :return: Function
     """
-    assert middleware_type == "http", 'Currently only middleware("http") is supported.'
 
     def decorator(func: t.Callable) -> t.Callable:
-        add_middleware(BaseHTTPMiddleware, dispatch=func)
+        _add_middleware(FunctionBasedMiddleware, dispatch=func)
         return func
 
     return decorator

ellar/core/middleware/__init__.py

@@ -1,6 +1,5 @@
 from starlette.middleware import Middleware as Middleware
 from starlette.middleware.authentication import AuthenticationMiddleware
-from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.middleware.cors import CORSMiddleware as CORSMiddleware
 from starlette.middleware.errors import ServerErrorMiddleware
 from starlette.middleware.gzip import GZipMiddleware as GZipMiddleware
@@ -14,12 +13,13 @@
 
 from .di import RequestServiceProviderMiddleware
 from .exceptions import ExceptionMiddleware
+from .function import FunctionBasedMiddleware
 from .versioning import RequestVersioningMiddleware
 
 __all__ = [
     "Middleware",
     "AuthenticationMiddleware",
-    "BaseHTTPMiddleware",
+    "FunctionBasedMiddleware",
     "CORSMiddleware",
     "ServerErrorMiddleware",
     "ExceptionMiddleware",

ellar/core/middleware/exceptions.py

@@ -17,7 +17,7 @@ def __init__(
         debug: bool = False,
     ) -> None:
         self.app = app
-        self.debug = debug  # TODO: We ought to handle 404 cases if debug is set.
+        self.debug = debug
         self._exception_middleware_service = exception_middleware_service
 
     async def __call__(self, scope: TScope, receive: TReceive, send: TSend) -> None:

ellar/core/middleware/function.py

@@ -0,0 +1,67 @@
+import typing as t
+
+from starlette.responses import Response
+
+from ellar.core.connection import HTTPConnection
+from ellar.core.context import IExecutionContext
+from ellar.types import ASGIApp, TReceive, TScope, TSend
+
+AwaitableCallable = t.Callable[..., t.Awaitable]
+DispatchFunction = t.Callable[
+    [IExecutionContext, AwaitableCallable], t.Awaitable[t.Optional[Response]]
+]
+T = t.TypeVar("T")
+
+
+class FunctionBasedMiddleware:
+    """
+    Convert ASGI Middleware to a Node-like Middleware.
+
+    Usage: Example 1
+    @middleware()
+    def my_middleware(context: IExecution, call_next):
+        print("Called my_middleware")
+        request = context.switch_to_request()
+        request.state.my_middleware = True
+        await call_next()
+
+    Usage: Example 2
+    @middleware()
+    def my_middleware(context: IExecution, call_next):
+        print("Called my_middleware")
+        response = context.get_response()
+        response.content = "Some Content"
+        response.status_code = 200
+        return response
+    """
+
+    def __init__(
+        self, app: ASGIApp, dispatch: t.Optional[DispatchFunction] = None
+    ) -> None:
+        self.app = app
+        self.dispatch_function = dispatch or self.dispatch
+
+    async def dispatch(
+        self, context: IExecutionContext, call_next: AwaitableCallable
+    ) -> Response:
+        raise NotImplementedError()  # pragma: no cover
+
+    async def __call__(self, scope: TScope, receive: TReceive, send: TSend) -> None:
+        if scope["type"] not in ("http", "websocket"):
+            await self.app(scope, receive, send)
+            return
+
+        connection = HTTPConnection(scope, receive)
+
+        if not connection.service_provider:  # pragma: no cover
+            raise Exception("Service Provider is required")
+
+        context = connection.service_provider.get(IExecutionContext)  # type: ignore
+
+        async def call_next() -> None:
+            await self.app(scope, receive, send)
+
+        response = await self.dispatch_function(context, call_next)
+
+        if response and isinstance(response, Response):
+            await response(scope, receive, send)

ellar/core/middleware/schema.py

@@ -1,13 +1,14 @@
 import typing as t
 
 from starlette.middleware import Middleware
-from starlette.middleware.base import BaseHTTPMiddleware
 
 from ellar.core.schema import Schema
 
+from .function import FunctionBasedMiddleware
+
 
 class MiddlewareSchema(Schema):
-    middleware_class: t.Type[BaseHTTPMiddleware]
+    middleware_class: t.Type[FunctionBasedMiddleware]
     dispatch: t.Callable[[t.Any, t.Callable], t.Any]
     options: t.Dict
 

tests/test_common/test_decorators/test_middleware.py

@@ -1,11 +1,10 @@
-from starlette.middleware.base import BaseHTTPMiddleware
-
 from ellar.common import middleware
 from ellar.constants import MIDDLEWARE_HANDLERS_KEY
+from ellar.core.middleware import FunctionBasedMiddleware
 from ellar.core.middleware.schema import MiddlewareSchema
 
 
-@middleware("http")
+@middleware()
 def middleware_function_test():
     pass
 
@@ -15,5 +14,5 @@ def test_middleware_decorator_works():
     middleware_detail: MiddlewareSchema = getattr(
         middleware_function_test, MIDDLEWARE_HANDLERS_KEY
     )
-    assert middleware_detail.middleware_class is BaseHTTPMiddleware
+    assert middleware_detail.middleware_class is FunctionBasedMiddleware
     assert middleware_detail.dispatch is middleware_function_test

tests/test_modules/test_module_ref.py

@@ -195,10 +195,9 @@ async def exception_404(cls, ctx, exc):
 def test_module_template_ref_scan_middle_ware():
     @Module()
     class ModuleMiddlewareExample(ModuleBase):
-        @middleware("http")
-        async def middleware(cls, request, call_next):
-            response = await call_next(request)
-            return response
+        @middleware()
+        async def middleware_func(cls, context, call_next):
+            await call_next()
 
     config = Config(**{MIDDLEWARE_HANDLERS_KEY: ()})
     container = EllarInjector(auto_bind=False).container
@@ -207,10 +206,10 @@ async def middleware(cls, request, call_next):
     create_module_ref_factor(
         ModuleMiddlewareExample, config=config, container=container
     )
-    middleware = config[MIDDLEWARE_HANDLERS_KEY]
+    config_middleware = config[MIDDLEWARE_HANDLERS_KEY]
 
-    assert isinstance(middleware, list)
-    assert "middleware" == get_name(middleware[0].options["dispatch"])
+    assert isinstance(config_middleware, list)
+    assert "middleware_func" == get_name(config_middleware[0].options["dispatch"])
 
 
 def test_module_template_ref_get_all_routers():

tests/test_response/test_response_file.py

@@ -83,9 +83,9 @@ def test_file_response_for_module_router_and_controller(path):
         response.headers["content-disposition"]
         == 'attachment; filename="file-test-css.css"'
     )
-    assert response.headers["content-length"] == "22"
+    assert response.headers["content-length"] == "23"
     assert response.headers["etag"]
-    assert response.text == ".div {background: red}"
+    assert response.text == ".div {background: red}\n"
 
 
 @pytest.mark.parametrize(