Improve built-in sessions. Fix #542 (#587)

Author: RobertoPrevato

CHANGELOG.md

@@ -5,8 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [2.3.3] - 2025-06-??
+## [2.4.0] - 2025-06-??
 
+- **SOME BREAKING CHANGES**. Modify the built-in sessions to support any kind
+  of storage for the session information. It still defaults to storing sessions
+  in cookies, but allows defining a custom `SessionStore` to store information
+  where desired.
 - Remove `charset-normalizer` dependency. This library was used only when a
   `UnicodeDecodeError` exception occurred when parsing the body of a web
   request. This can happen in two circumstances: when the client sends a

blacksheep/__init__.py

@@ -4,7 +4,7 @@
 """
 
 __author__ = "Roberto Prevato <[email protected]>"
-__version__ = "2.3.3"
+__version__ = "2.4.0"
 
 from .contents import Content as Content
 from .contents import FormContent as FormContent

blacksheep/server/application.py

@@ -70,6 +70,7 @@
 )
 from blacksheep.server.websocket import WebSocket, format_reason
 from blacksheep.sessions import SessionMiddleware, SessionSerializer
+from blacksheep.sessions.abc import SessionStore
 from blacksheep.settings.di import di_settings
 from blacksheep.utils import join_fragments
 from blacksheep.utils.meta import get_parent_file, import_child_modules
@@ -310,20 +311,49 @@ async def handle_child_app_stop(_):
 
     def use_sessions(
         self,
-        secret_key: str,
+        store: Union[str, SessionStore],
         *,
         session_cookie: str = "session",
         serializer: Optional[SessionSerializer] = None,
         signer: Optional[Serializer] = None,
         session_max_age: Optional[int] = None,
     ) -> None:
-        self._session_middleware = SessionMiddleware(
-            secret_key=secret_key,
-            session_cookie=session_cookie,
-            serializer=serializer,
-            signer=signer,
-            session_max_age=session_max_age,
-        )
+        """
+        Configures session support for the application.
+
+        This method enables session management by adding a SessionMiddleware to the
+        application.
+        It can be used with either a secret key (to use cookie-based sessions) or a
+        custom SessionStore.
+
+        Args:
+            store (Union[str, SessionStore]): A secret key for cookie-based sessions,
+                or an instance of SessionStore for custom session storage.
+            session_cookie (str, optional): Name of the session cookie. Defaults to
+                session".
+            serializer (SessionSerializer, optional): Serializer for session data.
+            signer (Serializer, optional): Serializer used for signing session data.
+            session_max_age (int, optional): Maximum age of the session in seconds.
+
+        Usage:
+            app.use_sessions("my-secret-key")
+            # or
+            app.use_sessions(MyCustomSessionStore())
+        """
+        if isinstance(store, str):
+            from blacksheep.sessions.cookies import CookieSessionStore
+
+            self._session_middleware = SessionMiddleware(
+                CookieSessionStore(
+                    store,
+                    session_cookie=session_cookie,
+                    serializer=serializer,
+                    signer=signer,
+                    session_max_age=session_max_age,
+                )
+            )
+        elif isinstance(store, SessionStore):
+            self._session_middleware = SessionMiddleware(store)
 
     def use_cors(
         self,

blacksheep/sessions/__init__.py

@@ -1,160 +1,40 @@
-import base64
-import logging
-from abc import ABC, abstractmethod
-from typing import Any, Awaitable, Callable, Dict, Mapping, Optional
+from typing import Awaitable, Callable
 
-from itsdangerous import Serializer, URLSafeTimedSerializer  # noqa
-from itsdangerous.exc import BadSignature, SignatureExpired
-
-from blacksheep.cookies import Cookie
 from blacksheep.messages import Request, Response
-from blacksheep.settings.json import json_settings
-from blacksheep.utils import ensure_str
-
-
-def get_logger():
-    logger = logging.getLogger("blacksheep.sessions")
-    logger.setLevel(logging.INFO)
-    return logger
-
-
-class Session:
-    def __init__(self, values: Optional[Mapping[str, Any]] = None) -> None:
-        if values is None:
-            values = {}
-        self._modified = False
-        self._values = dict(values)
-
-    @property
-    def modified(self) -> bool:
-        return self._modified
-
-    def get(self, name: str, default: Any = None) -> Any:
-        return self._values.get(name, default)
-
-    def set(self, name: str, value: Any) -> None:
-        self._modified = True
-        self._values[name] = value
-
-    def update(self, values: Mapping[str, Any]) -> None:
-        self._modified = True
-        self._values.update(values)
-
-    def __getitem__(self, name: str) -> Any:
-        return self._values[name]
-
-    def __setitem__(self, name: str, value: Any) -> None:
-        self._modified = True
-        self._values[name] = value
-
-    def __delitem__(self, name: str) -> None:
-        self._modified = True
-        del self._values[name]
+from blacksheep.sessions.abc import Session, SessionSerializer, SessionStore
 
-    def __contains__(self, name: str) -> bool:
-        return name in self._values
-
-    def __len__(self) -> int:
-        return len(self._values)
-
-    def __eq__(self, o: object) -> bool:
-        if self is o:
-            return True
-        if isinstance(o, Session):
-            return self._values == o._values
-        return self._values == o
-
-    def clear(self) -> None:
-        self._modified = True
-        self._values.clear()
-
-    def to_dict(self) -> Dict[str, Any]:
-        return self._values.copy()
-
-
-class SessionSerializer(ABC):
-    @abstractmethod
-    def read(self, value: str) -> Session:
-        """Creates an instance of Session from a string representation."""
-
-    @abstractmethod
-    def write(self, session: Session) -> str:
-        """Creates the string representation of a session."""
-
-
-class JSONSerializer(SessionSerializer):
-    def read(self, value: str) -> Session:
-        return Session(json_settings.loads(value))
-
-    def write(self, session: Session) -> str:
-        return json_settings.dumps(session.to_dict())
+__all__ = [
+    "Session",
+    "SessionMiddleware",
+    "SessionStore",
+    "SessionSerializer",
+]
 
 
 class SessionMiddleware:
-    def __init__(
-        self,
-        secret_key: str,
-        *,
-        session_cookie: str = "session",
-        serializer: Optional[SessionSerializer] = None,
-        signer: Optional[Serializer] = None,
-        session_max_age: Optional[int] = None,
-    ) -> None:
-        self._signer = signer or URLSafeTimedSerializer(secret_key)
-        self._serializer = serializer or JSONSerializer()
-        self._session_cookie = session_cookie
-        self._logger = get_logger()
-        if session_max_age is not None and session_max_age < 1:
-            raise ValueError("session_max_age must be a positive number greater than 0")
-        self.session_max_age = session_max_age
+    """
+    Middleware for managing user sessions in a BlackSheep application.
 
-    def try_read_session(self, raw_value: str) -> Session:
-        try:
-            if self.session_max_age:
-                assert isinstance(self._signer, URLSafeTimedSerializer), (
-                    "To use a session_max_age, the configured signer must be of "
-                    + " TimestampSigner type"
-                )
-                unsigned_value = self._signer.loads(
-                    raw_value, max_age=self.session_max_age
-                )
-            else:
-                unsigned_value = self._signer.loads(raw_value)
-        except SignatureExpired:
-            self._logger.info("The session signature has expired.")
-            return Session()
-        except BadSignature:
-            # the client might be sending forged tokens
-            self._logger.info("The session signature verification failed.")
-            return Session()
+    This middleware loads the session from the provided session store at the beginning
+    of the request, attaches it to the request object, and saves the session back to
+    the store if it was modified during request processing.
 
-        # in this case, we don't try because if the signature verification worked,
-        # we expect the value to be valid - if reading fails here it's a bug in
-        # in the serializer class
-        return self._serializer.read(base64.b64decode(unsigned_value).decode("utf8"))
+    Args:
+        store (SessionStore): The session store used to load and save session data.
 
-    def write_session(self, session: Session) -> str:
-        payload = base64.b64encode(
-            self._serializer.write(session).encode("utf8")
-        ).decode()
-        return ensure_str(self._signer.dumps(payload))  # type: ignore
+    Usage:
+        Add this middleware to your application to enable session support.
+    """
 
-    def prepare_cookie(self, value: str) -> Cookie:
-        return Cookie(self._session_cookie, value, path="/", http_only=True)
+    def __init__(self, store: SessionStore) -> None:
+        self._store = store
 
     async def __call__(
         self, request: Request, handler: Callable[[Request], Awaitable[Response]]
     ) -> Response:
-        session: Optional[Session] = None
-        current_session_value = request.cookies.get(self._session_cookie, None)
-        if current_session_value:
-            session = self.try_read_session(current_session_value)
-        else:
-            session = Session()
+        session = await self._store.load(request)
         request.session = session
-
         response = await handler(request)
-
         if session.modified:
-            response.set_cookie(self.prepare_cookie(self.write_session(session)))
+            await self._store.save(request, response, session)
         return response

blacksheep/sessions/abc.py

@@ -0,0 +1,117 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Mapping, Optional
+
+from blacksheep.messages import Request, Response
+
+
+class Session:
+    """
+    Represents a session for storing and managing user-specific data across requests.
+
+    The Session class provides a dictionary-like interface for storing key-value pairs
+    associated with a user's session. It tracks modifications to its contents and
+    supports standard dictionary operations such as getting, setting, deleting, and
+    updating items. The session data can be converted to a dictionary using `to_dict()`.
+
+    Attributes:
+        modified (bool): Indicates whether the session data has been modified.
+
+    Methods:
+        get(name, default=None): Retrieves a value by key, returning default if not
+            found.
+        set(name, value): Sets a value for a given key and marks the session as
+            modified.
+        update(values): Updates the session with multiple key-value pairs.
+        clear(): Removes all items from the session and marks it as modified.
+        to_dict(): Returns a shallow copy of the session data as a dictionary.
+    """
+
+    def __init__(self, values: Optional[Mapping[str, Any]] = None) -> None:
+        if values is None:
+            values = {}
+        self._modified = False
+        self._values = dict(values)
+
+    @property
+    def modified(self) -> bool:
+        return self._modified
+
+    def get(self, name: str, default: Any = None) -> Any:
+        return self._values.get(name, default)
+
+    def set(self, name: str, value: Any) -> None:
+        self._modified = True
+        self._values[name] = value
+
+    def update(self, values: Mapping[str, Any]) -> None:
+        self._modified = True
+        self._values.update(values)
+
+    def __getitem__(self, name: str) -> Any:
+        return self._values[name]
+
+    def __setitem__(self, name: str, value: Any) -> None:
+        self._modified = True
+        self._values[name] = value
+
+    def __delitem__(self, name: str) -> None:
+        self._modified = True
+        del self._values[name]
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._values
+
+    def __len__(self) -> int:
+        return len(self._values)
+
+    def __eq__(self, o: object) -> bool:
+        if self is o:
+            return True
+        if isinstance(o, Session):
+            return self._values == o._values
+        return self._values == o
+
+    def clear(self) -> None:
+        self._modified = True
+        self._values.clear()
+
+    def to_dict(self) -> Dict[str, Any]:
+        return self._values.copy()
+
+
+class SessionSerializer(ABC):
+    """
+    Abstract base class for session serialization and deserialization.
+
+    Implementations of this class provide methods to convert Session objects
+    to and from their string representations, enabling storage and retrieval
+    of session data in various formats (e.g., JSON, base64, etc.).
+    """
+
+    @abstractmethod
+    def read(self, value: str) -> Session:
+        """Creates an instance of Session from a string representation."""
+
+    @abstractmethod
+    def write(self, session: Session) -> str:
+        """Creates the string representation of a session."""
+
+
+class SessionStore(ABC):
+    """
+    Abstract base class for session storage backends.
+
+    Implementations of this class define how sessions are loaded from and saved to
+    a storage medium (such as cookies, databases, or distributed caches) during the
+    request-response cycle.
+    """
+
+    @abstractmethod
+    async def load(self, request: Request) -> Session:
+        """Load the session for the given request."""
+
+    @abstractmethod
+    async def save(
+        self, request: Request, response: Response, session: Session
+    ) -> None:
+        """Save the session related to the given request-response cycle."""