fix(testing): handle uvicorn SystemExit in EllarUvicornServer startup

After upgrading uvicorn, the test server was failing because uvicorn
now calls sys.exit(1) when encountering port binding errors. This
caused the entire test process to terminate instead of handling
errors gracefully.

Changes:
- Override startup() method to catch SystemExit exceptions
- Convert SystemExit to RuntimeError with descriptive message
- Ensure proper cleanup via lifespan.shutdown() on errors
- Remove setup_event_loop() call that interfered with running loop
- Fix _startup_done event synchronization

This allows tests to handle server startup failures properly without
terminating the test process.

Fixes socket_io test failures in TestGatewayWithGuards and related
test classes.

Author: eadwinCode

docs/overview/modules.md

@@ -289,10 +289,23 @@ class ApplicationModule(ModuleBase):
 The `JWTModule` provides `JWTService` which is injected into `CustomModule`. By declaring `ForwardRefModule(JWTModule)` in `CustomModule`, the `JWTService` will be properly resolved during instantiation of `CustomModule`, regardless of the order in which the modules are configured in the application.
 
 This pattern is particularly useful when:
+
 - You want to avoid direct module instantiation
 - You need to configure a module differently in different parts of your application
 - You want to maintain loose coupling between modules
 
+### When not to use `ForwardRefModule`
+If the @Module class is registered in the application module, ApplicationModule, there is no need to use `ForwardRefModule`. Services/Providers exported from the module will be available in the application module. And all other modules will be able to resolve the dependencies from the application module.
+
+```python
+from ellar.common import Module
+from ellar.core.modules import ForwardRefModule, ModuleBase
+
+@Module(modules=[ModuleA])
+class ApplicationModule(ModuleBase):
+    pass
+```
+
 ### Forward Reference by Class
 
 In the following example, we have two modules, `ModuleA` and `ModuleB`. `ModuleB` 
@@ -321,6 +334,7 @@ class ApplicationModule(ModuleBase):
 ```
 
 In this example:
+
 - `ModuleB` references `ModuleA` using `ForwardRefModule`, meaning `ModuleB` knows about `ModuleA` but doesn't instantiate it.
 - When `ApplicationModule` is built, both `ModuleA` and `ModuleB` are instantiated. During this build process, `ModuleB` can reference the instance of `ModuleA`, ensuring that all dependencies are resolved properly.
 
@@ -352,6 +366,7 @@ class ApplicationModule(ModuleBase):
 ```
 
 In this second example:
+
 - `ModuleB` references `ModuleA` by its name, `"moduleA"`. 
 - During the build process of `ApplicationModule`, the name reference is resolved, ensuring that `ModuleA` is instantiated and injected into `ModuleB` correctly.
 

ellar/app/main.py

@@ -1,7 +1,7 @@
 import json
 import logging
-import logging.config
 import typing as t
+from contextlib import _AsyncGeneratorContextManager
 
 from ellar.auth.handlers import AuthenticationHandlerType
 from ellar.common import (
@@ -185,7 +185,7 @@ def request_context(
         )
 
     @t.no_type_check
-    def with_injector_context(self) -> t.AsyncGenerator[EllarInjector, t.Any]:
+    def with_injector_context(self) -> _AsyncGeneratorContextManager[t.Any]:
         return injector_context(self.injector)
 
     @t.no_type_check

ellar/auth/session/__init__.py

@@ -23,12 +23,15 @@ def session_cookie_options(self) -> SessionCookieOption:  # pragma: no cover
         return SessionCookieOption()
 
     def deserialize_session(
-        self, session_data: t.Optional[str]
+        self,
+        session_data: t.Optional[str],
+        config: t.Optional[SessionCookieOption] = None,
     ) -> SessionCookieObject:  # pragma: no cover
         return SessionCookieObject()
 
     def serialize_session(
         self,
         session: t.Union[str, SessionCookieObject],
+        config: t.Optional[SessionCookieOption] = None,
     ) -> str:  # pragma: no cover
         return ""

ellar/auth/session/base.py

@@ -17,37 +17,48 @@ def session_cookie_options(self) -> SessionCookieOption:
     def serialize_session(
         self,
         session: t.Union[str, SessionCookieObject],
+        config: t.Optional[SessionCookieOption] = None,
     ) -> str:
         """
         :param session: Collection ExtraEndpointArg
+        :param config: SessionCookieOption
         :return: string
         """
 
     @abstractmethod
-    def deserialize_session(self, session_data: t.Optional[str]) -> SessionCookieObject:
+    def deserialize_session(
+        self,
+        session_data: t.Optional[str],
+        config: t.Optional[SessionCookieOption] = None,
+    ) -> SessionCookieObject:
         """
         :param session_data:
         :return: SessionCookieObject
+        :param config: SessionCookieOption
         """
 
-    def get_cookie_header_value(self, data: t.Any, delete: bool = False) -> str:
-        security_flags = "httponly; samesite=" + self.session_cookie_options.SAME_SITE
-        if self.session_cookie_options.SECURE:
+    def get_cookie_header_value(
+        self,
+        data: t.Any,
+        delete: bool = False,
+        config: t.Optional[SessionCookieOption] = None,
+    ) -> str:
+        session_config = config or self.session_cookie_options
+        security_flags = "httponly; samesite=" + session_config.SAME_SITE
+        if session_config.SECURE:
             security_flags += "; secure"
 
         if not delete:
             max_age = (
-                f"Max-Age={self.session_cookie_options.MAX_AGE}; "
-                if self.session_cookie_options.MAX_AGE
-                else ""
+                f"Max-Age={session_config.MAX_AGE}; " if session_config.MAX_AGE else ""
             )
         else:
             max_age = "Max-Age=0; "
 
         header_value = "{session_cookie}={data}; path={path}; {max_age}{security_flags}".format(  # E501
-            session_cookie=self.session_cookie_options.NAME,
+            session_cookie=session_config.NAME,
             data=data,
-            path=self.session_cookie_options.PATH,
+            path=session_config.PATH,
             max_age=max_age,
             security_flags=security_flags,
         )

ellar/auth/session/strategy.py

@@ -40,22 +40,29 @@ def session_cookie_options(self) -> SessionCookieOption:
     def serialize_session(
         self,
         session: t.Union[str, SessionCookieObject],
+        config: t.Optional[SessionCookieOption] = None,
     ) -> str:
+        session_config = config or self._session_config
         if isinstance(session, SessionCookieObject):
             data = b64encode(json.dumps(dict(session)).encode("utf-8"))
             data = self._signer.sign(data)
 
-            return self.get_cookie_header_value(data.decode("utf-8"))
+            return self.get_cookie_header_value(
+                data.decode("utf-8"), config=session_config
+            )
 
-        return self.get_cookie_header_value(session, delete=True)
+        return self.get_cookie_header_value(session, delete=True, config=session_config)
 
-    def deserialize_session(self, session_data: t.Optional[str]) -> SessionCookieObject:
+    def deserialize_session(
+        self,
+        session_data: t.Optional[str],
+        config: t.Optional[SessionCookieOption] = None,
+    ) -> SessionCookieObject:
+        session_config = config or self._session_config
         if session_data:
             data = session_data.encode("utf-8")
             try:
-                data = self._signer.unsign(
-                    data, max_age=self.session_cookie_options.MAX_AGE
-                )
+                data = self._signer.unsign(data, max_age=session_config.MAX_AGE)
                 return SessionCookieObject(json.loads(b64decode(data)))
             except BadSignature:
                 pass

ellar/testing/uvicorn_server.py

@@ -25,10 +25,17 @@ def __init__(self, app: ASGIApp, host: str = "127.0.0.1", port: int = 8000):
         super().__init__(config=uvicorn.Config(app, host=host, port=port))
 
     async def startup(self, sockets: t.Optional[t.List[t.Any]] = None) -> None:
-        """Override uvicorn startup"""
-        await super().startup(sockets)
-        self.config.setup_event_loop()
-        self._startup_done.set()
+        """Override uvicorn startup to prevent sys.exit on errors"""
+        try:
+            await super().startup(sockets)
+            self._startup_done.set()
+        except SystemExit as exc:
+            # Convert sys.exit() calls into RuntimeError for testing
+            # This happens when uvicorn fails to bind to a port
+            await self.lifespan.shutdown()
+            raise RuntimeError(
+                f"Server failed to start on {self.config.host}:{self.config.port}"
+            ) from exc
 
     async def run_server(self) -> None:
         """Start up server asynchronously"""