fix: prevent session cleanup from masking original exceptions (#704)

## Summary

- Replace `BaseHTTPMiddleware` with pure ASGI `SessionMiddleware` in Starlette/FastAPI extension — fixes timing issue where `response_status` wasn't set before generator cleanup
- Protect session cleanup (commit/rollback/close) across **all** framework extensions so cleanup failures never mask the original route handler exception
- Each cleanup operation is individually wrapped; when an original exception exists, cleanup errors are logged but suppressed

**Affected extensions:** FastAPI, Starlette, Sanic, Litestar (async + sync)

**Reported issue:** FastAPI validation errors overridden by internal session attribute name `advanced_alchemy_async_session_db_session_response_status` (Close #705)

Author: cofin

advanced_alchemy/extensions/fastapi/providers.py

@@ -8,6 +8,7 @@
 import contextlib
 import datetime
 import inspect
+import logging
 from collections.abc import AsyncGenerator, Generator
 from typing import (
     TYPE_CHECKING,
@@ -53,6 +54,8 @@
 from advanced_alchemy.utils.singleton import SingletonMeta
 from advanced_alchemy.utils.text import camelize
 
+logger = logging.getLogger("advanced_alchemy.extensions.fastapi")
+
 if TYPE_CHECKING:
     from advanced_alchemy.extensions.fastapi import SQLAlchemyAsyncConfig, SQLAlchemySyncConfig
 
@@ -201,7 +204,7 @@ def provide_service(
 ) -> Callable[..., Generator[SyncServiceT_co, None, None]]: ...
 
 
-def provide_service(  # noqa: PLR0915
+def provide_service(  # noqa: C901, PLR0915
     service_class: type[Union["AsyncServiceT_co", "SyncServiceT_co"]],
     /,
     extension: AdvancedAlchemy,
@@ -256,27 +259,41 @@ async def provide_async_service(
                 response_status = getattr(request.state, f"{session_key}_response_status", None)
                 commit_mode = async_config.commit_mode if async_config else "manual"
 
-                try:
-                    should_commit = (
-                        exc_info is None
-                        and response_status is not None
-                        and _should_commit_for_status(response_status, commit_mode)
-                    )
+                should_commit = (
+                    exc_info is None
+                    and response_status is not None
+                    and _should_commit_for_status(response_status, commit_mode)
+                )
 
+                # Each cleanup operation is individually protected so that failures
+                # in one step do not prevent subsequent steps or mask the original exception.
+                try:
                     if should_commit:
                         await db_session.commit()
                     else:
                         await db_session.rollback()
-                finally:
+                except Exception:
+                    if exc_info is not None:
+                        logger.debug("Session commit/rollback failed during cleanup", exc_info=True)
+                    else:
+                        raise
+
+                try:
                     await db_session.close()
-                    # Clean up request state
-                    for attr in [
-                        session_key,
-                        f"{session_key}_generator_managed",
-                        f"{session_key}_response_status",
-                    ]:
-                        with contextlib.suppress(AttributeError):
-                            delattr(request.state, attr)
+                except Exception:
+                    if exc_info is not None:
+                        logger.debug("Session close failed during cleanup", exc_info=True)
+                    else:
+                        raise
+
+                # Clean up request state
+                for attr in [
+                    session_key,
+                    f"{session_key}_generator_managed",
+                    f"{session_key}_response_status",
+                ]:
+                    with contextlib.suppress(Exception):
+                        delattr(request.state, attr)
 
         return provide_async_service
 
@@ -312,27 +329,41 @@ def provide_sync_service(
             response_status = getattr(request.state, f"{session_key}_response_status", None)
             commit_mode = sync_config.commit_mode if sync_config else "manual"
 
-            try:
-                should_commit = (
-                    exc_info is None
-                    and response_status is not None
-                    and _should_commit_for_status(response_status, commit_mode)
-                )
+            should_commit = (
+                exc_info is None
+                and response_status is not None
+                and _should_commit_for_status(response_status, commit_mode)
+            )
 
+            # Each cleanup operation is individually protected so that failures
+            # in one step do not prevent subsequent steps or mask the original exception.
+            try:
                 if should_commit:
                     db_session.commit()
                 else:
                     db_session.rollback()
-            finally:
+            except Exception:
+                if exc_info is not None:
+                    logger.debug("Session commit/rollback failed during cleanup", exc_info=True)
+                else:
+                    raise
+
+            try:
                 db_session.close()
-                # Clean up request state
-                for attr in [
-                    session_key,
-                    f"{session_key}_generator_managed",
-                    f"{session_key}_response_status",
-                ]:
-                    with contextlib.suppress(AttributeError):
-                        delattr(request.state, attr)
+            except Exception:
+                if exc_info is not None:
+                    logger.debug("Session close failed during cleanup", exc_info=True)
+                else:
+                    raise
+
+            # Clean up request state
+            for attr in [
+                session_key,
+                f"{session_key}_generator_managed",
+                f"{session_key}_response_status",
+            ]:
+                with contextlib.suppress(Exception):
+                    delattr(request.state, attr)
 
     return provide_sync_service
 

advanced_alchemy/extensions/litestar/plugins/init/config/asyncio.py

@@ -1,3 +1,4 @@
+import logging
 from collections.abc import AsyncGenerator, Coroutine
 from contextlib import asynccontextmanager
 from dataclasses import dataclass, field
@@ -22,6 +23,8 @@
 from advanced_alchemy.extensions.litestar.plugins.init.config.engine import EngineConfig
 from advanced_alchemy.routing.context import reset_routing_context
 
+logger = logging.getLogger("advanced_alchemy.extensions.litestar")
+
 if TYPE_CHECKING:
     from collections.abc import AsyncGenerator, Coroutine
 
@@ -117,9 +120,14 @@ async def handler(message: "Message", scope: "Scope") -> None:
                     await session.commit()
                 else:
                     await session.rollback()
+        except Exception:  # noqa: BLE001
+            logger.debug("Session commit/rollback failed during cleanup", exc_info=True)
         finally:
             if session and message["type"] in SESSION_TERMINUS_ASGI_EVENTS:
-                await session.close()
+                try:
+                    await session.close()
+                except Exception:  # noqa: BLE001
+                    logger.debug("Session close failed during cleanup", exc_info=True)
                 delete_aa_scope_state(scope, session_scope_key)
 
     return handler

advanced_alchemy/extensions/litestar/plugins/init/config/sync.py

@@ -1,3 +1,4 @@
+import logging
 from contextlib import asynccontextmanager
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Callable, Literal, Optional, Union, cast
@@ -22,6 +23,8 @@
 from advanced_alchemy.extensions.litestar.plugins.init.config.engine import EngineConfig
 from advanced_alchemy.routing.context import reset_routing_context
 
+logger = logging.getLogger("advanced_alchemy.extensions.litestar")
+
 if TYPE_CHECKING:
     from collections.abc import AsyncGenerator
 
@@ -118,9 +121,14 @@ def handler(message: "Message", scope: "Scope") -> None:
                     session.commit()
                 else:
                     session.rollback()
+        except Exception:  # noqa: BLE001
+            logger.debug("Session commit/rollback failed during cleanup", exc_info=True)
         finally:
             if session and message["type"] in SESSION_TERMINUS_ASGI_EVENTS:
-                session.close()
+                try:
+                    session.close()
+                except Exception:  # noqa: BLE001
+                    logger.debug("Session close failed during cleanup", exc_info=True)
                 delete_aa_scope_state(scope, session_scope_key)
 
     return handler

advanced_alchemy/extensions/sanic/config.py

@@ -6,6 +6,7 @@
 
 import asyncio
 import contextlib
+import logging
 from dataclasses import dataclass, field
 from typing import Any, Callable, Optional, cast
 
@@ -35,6 +36,8 @@
 from advanced_alchemy.config.sync import SQLAlchemySyncConfig as _SQLAlchemySyncConfig
 from advanced_alchemy.service import schema_dump
 
+logger = logging.getLogger("advanced_alchemy.extensions.sanic")
+
 
 def _make_unique_context_key(app: "Sanic[Any, Any]", key: str) -> str:  # pragma: no cover
     """Generates a unique context key for the Sanic application.
@@ -246,8 +249,13 @@ async def session_handler(
                 await session.commit()
             else:
                 await session.rollback()
+        except Exception:  # noqa: BLE001
+            logger.debug("Session commit/rollback failed during cleanup", exc_info=True)
         finally:
-            await session.close()
+            try:
+                await session.close()
+            except Exception:  # noqa: BLE001
+                logger.debug("Session close failed during cleanup", exc_info=True)
             with contextlib.suppress(AttributeError, KeyError):
                 delattr(request.ctx, self.session_key)
 
@@ -455,8 +463,13 @@ async def session_handler(
                 await loop.run_in_executor(None, session.commit)
             else:
                 await loop.run_in_executor(None, session.rollback)
+        except Exception:  # noqa: BLE001
+            logger.debug("Session commit/rollback failed during cleanup", exc_info=True)
         finally:
-            await loop.run_in_executor(None, session.close)
+            try:
+                await loop.run_in_executor(None, session.close)
+            except Exception:  # noqa: BLE001
+                logger.debug("Session close failed during cleanup", exc_info=True)
             with contextlib.suppress(AttributeError, KeyError):
                 delattr(request.ctx, self.session_key)