fastapi-cachex 0.2.1__tar.gz → 0.2.2__tar.gz

{fastapi_cachex-0.2.1 → fastapi_cachex-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-cachex
-Version: 0.2.1
+Version: 0.2.2
 Summary: A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends.
 Keywords: fastapi,cache,etag,cache-control,redis,memcached,in-memory
 Author: Allen
@@ -47,10 +47,11 @@ Description-Content-Type: text/markdown
 
 [English](README.md) | [繁體中文](docs/README.zh-TW.md)
 
-A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support.
+A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support and optional session management.
 
 ## Features
 
+### HTTP Caching
 - Support for HTTP caching headers
     - `Cache-Control`
     - `ETag`
@@ -62,6 +63,15 @@ A high-performance caching extension for FastAPI, providing comprehensive HTTP c
 - Complete Cache-Control directive implementation
 - Easy-to-use `@cache` decorator
 
+### Session Management (Optional Extension)
+- Secure session management with HMAC-SHA256 token signing
+- IP address and User-Agent binding (optional security features)
+- Header and bearer token support (API-first architecture)
+- Automatic session renewal (sliding expiration)
+- Flash messages for cross-request communication
+- Multiple backend support (Redis, Memcached, In-Memory)
+- Complete session lifecycle management (create, validate, refresh, invalidate)
+
 ### Cache-Control Directives
 
 | Directive                | Supported          | Description                                                                                             |
@@ -236,6 +246,7 @@ async def expensive_operation():
 - [Cache Flow Explanation](docs/CACHE_FLOW.md)
 - [Development Guide](docs/DEVELOPMENT.md)
 - [Contributing Guidelines](docs/CONTRIBUTING.md)
+- [Session Management Guide](docs/SESSION.md) - Complete guide for session features
 
 ## License
 

{fastapi_cachex-0.2.1 → fastapi_cachex-0.2.2}/README.md

@@ -14,10 +14,11 @@
 
 [English](README.md) | [繁體中文](docs/README.zh-TW.md)
 
-A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support.
+A high-performance caching extension for FastAPI, providing comprehensive HTTP caching support and optional session management.
 
 ## Features
 
+### HTTP Caching
 - Support for HTTP caching headers
     - `Cache-Control`
     - `ETag`
@@ -29,6 +30,15 @@ A high-performance caching extension for FastAPI, providing comprehensive HTTP c
 - Complete Cache-Control directive implementation
 - Easy-to-use `@cache` decorator
 
+### Session Management (Optional Extension)
+- Secure session management with HMAC-SHA256 token signing
+- IP address and User-Agent binding (optional security features)
+- Header and bearer token support (API-first architecture)
+- Automatic session renewal (sliding expiration)
+- Flash messages for cross-request communication
+- Multiple backend support (Redis, Memcached, In-Memory)
+- Complete session lifecycle management (create, validate, refresh, invalidate)
+
 ### Cache-Control Directives
 
 | Directive                | Supported          | Description                                                                                             |
@@ -203,6 +213,7 @@ async def expensive_operation():
 - [Cache Flow Explanation](docs/CACHE_FLOW.md)
 - [Development Guide](docs/DEVELOPMENT.md)
 - [Contributing Guidelines](docs/CONTRIBUTING.md)
+- [Session Management Guide](docs/SESSION.md) - Complete guide for session features
 
 ## License
 

{fastapi_cachex-0.2.1 → fastapi_cachex-0.2.2}/fastapi_cachex/__init__.py

@@ -1,7 +1,20 @@
 """FastAPI-CacheX: A powerful and flexible caching extension for FastAPI."""
 
 from .cache import cache as cache
+from .cache import default_key_builder as default_key_builder
 from .dependencies import CacheBackend as CacheBackend
 from .dependencies import get_cache_backend as get_cache_backend
 from .proxy import BackendProxy as BackendProxy
 from .routes import add_routes as add_routes
+from .types import CacheKeyBuilder as CacheKeyBuilder
+
+# Session management (optional feature)
+__all__ = [
+    "BackendProxy",
+    "CacheBackend",
+    "CacheKeyBuilder",
+    "add_routes",
+    "cache",
+    "default_key_builder",
+    "get_cache_backend",
+]

{fastapi_cachex-0.2.1 → fastapi_cachex-0.2.2}/fastapi_cachex/backends/memory.py

@@ -5,12 +5,13 @@ import contextlib
 import fnmatch
 import time
 
+from fastapi_cachex.types import CACHE_KEY_SEPARATOR
 from fastapi_cachex.types import CacheItem
 from fastapi_cachex.types import ETagContent
 
 from .base import BaseCacheBackend
 
-# Cache keys are formatted as: method:host:path:query_params
+# Cache keys are formatted as: method|||host|||path|||query_params
 # Minimum parts required to extract path component
 _MIN_KEY_PARTS = 3
 # Maximum parts to split (method, host, path, query_params)
@@ -115,8 +116,8 @@ class MemoryBackend(BaseCacheBackend):
         async with self.lock:
             keys_to_delete = []
             for key in self.cache:
-                # Keys are formatted as: method:host:path:query_params
-                parts = key.split(":", _MAX_KEY_PARTS)
+                # Keys are formatted as: method|||host|||path|||query_params
+                parts = key.split(CACHE_KEY_SEPARATOR, _MAX_KEY_PARTS)
                 if len(parts) >= _MIN_KEY_PARTS:
                     cache_path = parts[2]
                     has_params = len(parts) > _MIN_KEY_PARTS
@@ -145,8 +146,8 @@ class MemoryBackend(BaseCacheBackend):
         async with self.lock:
             keys_to_delete = []
             for key in self.cache:
-                # Extract path component (method:host:path:query_params)
-                parts = key.split(":", _MAX_KEY_PARTS)
+                # Extract path component (method|||host|||path|||query_params)
+                parts = key.split(CACHE_KEY_SEPARATOR, _MAX_KEY_PARTS)
                 if len(parts) >= _MIN_KEY_PARTS:
                     cache_path = parts[2]
                     if fnmatch.fnmatch(cache_path, pattern):

{fastapi_cachex-0.2.1 → fastapi_cachex-0.2.2}/fastapi_cachex/backends/redis.py

@@ -6,6 +6,7 @@ from typing import Literal
 
 from fastapi_cachex.backends.base import BaseCacheBackend
 from fastapi_cachex.exceptions import CacheXError
+from fastapi_cachex.types import CACHE_KEY_SEPARATOR
 from fastapi_cachex.types import ETagContent
 
 if TYPE_CHECKING:
@@ -175,11 +176,13 @@ class AsyncRedisCacheBackend(BaseCacheBackend):
         """
         # Pattern includes the HTTP method, host, and path components
         if include_params:
-            # Clear all variations: *:path:*
-            pattern = f"{self.key_prefix}*:{path}:*"
+            # Clear all variations: *|||path|||*
+            pattern = (
+                f"{self.key_prefix}*{CACHE_KEY_SEPARATOR}{path}{CACHE_KEY_SEPARATOR}*"
+            )
         else:
-            # Clear only exact path (no query params): *:path
-            pattern = f"{self.key_prefix}*:{path}"
+            # Clear only exact path (no query params): *|||path
+            pattern = f"{self.key_prefix}*{CACHE_KEY_SEPARATOR}{path}"
 
         cursor = 0
         batch_size = 100

{fastapi_cachex-0.2.1 → fastapi_cachex-0.2.2}/fastapi_cachex/cache.py

@@ -25,6 +25,8 @@ from fastapi_cachex.exceptions import BackendNotFoundError
 from fastapi_cachex.exceptions import CacheXError
 from fastapi_cachex.exceptions import RequestNotFoundError
 from fastapi_cachex.proxy import BackendProxy
+from fastapi_cachex.types import CACHE_KEY_SEPARATOR
+from fastapi_cachex.types import CacheKeyBuilder
 from fastapi_cachex.types import ETagContent
 
 if TYPE_CHECKING:
@@ -36,6 +38,20 @@ SyncCallable = Callable[..., T]
 AnyCallable = Union[AsyncCallable[T], SyncCallable[T]]  # noqa: UP007
 
 
+def default_key_builder(request: Request) -> str:
+    """Default cache key builder function.
+
+    Generates cache key in format: method|||host|||path|||query_params
+
+    Args:
+        request: The FastAPI Request object
+
+    Returns:
+        Generated cache key string
+    """
+    return f"{request.method}{CACHE_KEY_SEPARATOR}{request.headers.get('host', 'unknown')}{CACHE_KEY_SEPARATOR}{request.url.path}{CACHE_KEY_SEPARATOR}{request.query_params}"
+
+
 class CacheControl:
     """Manages Cache-Control header directives."""
 
@@ -103,6 +119,7 @@ def cache(  # noqa: C901
     private: bool = False,
     immutable: bool = False,
     must_revalidate: bool = False,
+    cache_key_builder: CacheKeyBuilder | None = None,
 ) -> Callable[[AnyCallable[Response]], AsyncCallable[Response]]:
     """Cache decorator for FastAPI route handlers.
 
@@ -116,6 +133,7 @@ def cache(  # noqa: C901
         private: Whether responses are for single user only
         immutable: Whether cached responses never change
         must_revalidate: Whether to force revalidation when stale
+        cache_key_builder: Custom function to build cache keys. If None, uses default_cache_key_builder
 
     Returns:
         Decorator function that wraps route handlers with caching logic
@@ -207,9 +225,9 @@ def cache(  # noqa: C901
             if req.method != "GET":
                 return await get_response(func, req, *args, **kwargs)
 
-            # Generate cache key: method:host:path:query_params[:vary]
-            # Include host to avoid cross-host cache pollution
-            cache_key = f"{req.method}:{req.headers.get('host', 'unknown')}:{req.url.path}:{req.query_params}"
+            # Generate cache key using custom builder or default
+            key_builder = cache_key_builder or default_key_builder
+            cache_key = key_builder(req)
             client_etag = req.headers.get("if-none-match")
             cache_control = await get_cache_control(CacheControl())
 

{fastapi_cachex-0.2.1 → fastapi_cachex-0.2.2}/fastapi_cachex/routes.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING
 from fastapi_cachex.backends import BaseCacheBackend
 from fastapi_cachex.exceptions import BackendNotFoundError
 from fastapi_cachex.proxy import BackendProxy
+from fastapi_cachex.types import CACHE_KEY_SEPARATOR
 
 if TYPE_CHECKING:
     from fastapi import FastAPI
@@ -93,12 +94,12 @@ def _parse_cache_key(cache_key: str) -> tuple[str, str, str, str]:
     """Parse cache key into components.
 
     Args:
-        cache_key: Cache key in format method:host:path:query_params
+        cache_key: Cache key in format method|||host|||path|||query_params
 
     Returns:
         Tuple of (method, host, path, query_params)
     """
-    key_parts = cache_key.split(":", CACHE_KEY_MAX_PARTS)
+    key_parts = cache_key.split(CACHE_KEY_SEPARATOR, CACHE_KEY_MAX_PARTS)
     if len(key_parts) >= CACHE_KEY_MIN_PARTS:
         method, host, path = key_parts[0], key_parts[1], key_parts[2]
         query_params = key_parts[3] if len(key_parts) > CACHE_KEY_MIN_PARTS else ""

fastapi_cachex-0.2.2/fastapi_cachex/session/__init__.py

@@ -0,0 +1,21 @@
+"""Session management extension for FastAPI-CacheX."""
+
+from fastapi_cachex.session.config import SessionConfig
+from fastapi_cachex.session.dependencies import get_optional_session
+from fastapi_cachex.session.dependencies import get_session
+from fastapi_cachex.session.dependencies import require_session
+from fastapi_cachex.session.manager import SessionManager
+from fastapi_cachex.session.middleware import SessionMiddleware
+from fastapi_cachex.session.models import Session
+from fastapi_cachex.session.models import SessionUser
+
+__all__ = [
+    "Session",
+    "SessionConfig",
+    "SessionManager",
+    "SessionMiddleware",
+    "SessionUser",
+    "get_optional_session",
+    "get_session",
+    "require_session",
+]

fastapi_cachex-0.2.2/fastapi_cachex/session/config.py

@@ -0,0 +1,69 @@
+"""Session configuration settings."""
+
+from typing import Literal
+
+from pydantic import BaseModel
+from pydantic import Field
+
+
+class SessionConfig(BaseModel):
+    """Session configuration settings."""
+
+    # Session lifetime
+    session_ttl: int = Field(
+        default=3600,
+        description="Session time-to-live in seconds (default: 1 hour)",
+    )
+    absolute_timeout: int | None = Field(
+        default=None,
+        description="Absolute session timeout in seconds (None = no absolute timeout)",
+    )
+    sliding_expiration: bool = Field(
+        default=True,
+        description="Whether to refresh session expiry on each access",
+    )
+    sliding_threshold: float = Field(
+        default=0.5,
+        ge=0.0,
+        le=1.0,
+        description="Fraction of TTL that must pass before sliding refresh (0.5 = refresh after half TTL)",
+    )
+
+    # Token settings
+    header_name: str = Field(
+        default="X-Session-Token",
+        description="Custom header name for session token",
+    )
+    use_bearer_token: bool = Field(
+        default=True,
+        description="Whether to accept Authorization Bearer tokens",
+    )
+    token_source_priority: list[Literal["header", "bearer"]] = Field(
+        default=["header", "bearer"],
+        description="Priority order for token sources",
+    )
+
+    # Security settings
+    secret_key: str = Field(
+        ...,
+        min_length=32,
+        description="Secret key for signing session tokens (min 32 characters)",
+    )
+    ip_binding: bool = Field(
+        default=False,
+        description="Whether to bind session to client IP address",
+    )
+    user_agent_binding: bool = Field(
+        default=False,
+        description="Whether to bind session to User-Agent",
+    )
+    regenerate_on_login: bool = Field(
+        default=True,
+        description="Whether to regenerate session ID on login",
+    )
+
+    # Backend settings
+    backend_key_prefix: str = Field(
+        default="session:",
+        description="Prefix for session keys in backend storage",
+    )

fastapi_cachex-0.2.2/fastapi_cachex/session/dependencies.py

@@ -0,0 +1,65 @@
+"""FastAPI dependency injection utilities for session management."""
+
+from typing import Annotated
+
+from fastapi import Depends
+from fastapi import HTTPException
+from fastapi import Request
+from fastapi import status
+
+from fastapi_cachex.session.models import Session
+
+
+def get_optional_session(request: Request) -> Session | None:
+    """Get session from request state (optional).
+
+    Args:
+        request: FastAPI request object
+
+    Returns:
+        Session object or None if not authenticated
+    """
+    return getattr(request.state, "session", None)
+
+
+def get_session(request: Request) -> Session:
+    """Get session from request state (required).
+
+    Args:
+        request: FastAPI request object
+
+    Returns:
+        Session object
+
+    Raises:
+        HTTPException: 401 if session not found
+    """
+    session: Session | None = getattr(request.state, "session", None)
+    if session is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return session
+
+
+def require_session(request: Request) -> Session:
+    """Require authenticated session (alias for get_session).
+
+    Args:
+        request: FastAPI request object
+
+    Returns:
+        Session object
+
+    Raises:
+        HTTPException: 401 if session not found
+    """
+    return get_session(request)
+
+
+# Type annotations for dependency injection
+OptionalSession = Annotated[Session | None, Depends(get_optional_session)]
+RequiredSession = Annotated[Session, Depends(get_session)]
+SessionDep = Annotated[Session, Depends(require_session)]

fastapi_cachex-0.2.2/fastapi_cachex/session/exceptions.py

@@ -0,0 +1,25 @@
+"""Session-related exceptions."""
+
+
+class SessionError(Exception):
+    """Base exception for session errors."""
+
+
+class SessionNotFoundError(SessionError):
+    """Raised when a session is not found."""
+
+
+class SessionExpiredError(SessionError):
+    """Raised when a session has expired."""
+
+
+class SessionInvalidError(SessionError):
+    """Raised when a session is invalid."""
+
+
+class SessionSecurityError(SessionError):
+    """Raised when a session fails security checks."""
+
+
+class SessionTokenError(SessionError):
+    """Raised when there's an issue with session token."""

fastapi_cachex-0.2.2/fastapi_cachex/session/manager.py

@@ -0,0 +1,333 @@
+"""Session manager for CRUD operations."""
+
+from datetime import datetime
+from datetime import timedelta
+from datetime import timezone
+
+from fastapi_cachex.backends.base import BaseCacheBackend
+from fastapi_cachex.session.config import SessionConfig
+from fastapi_cachex.session.exceptions import SessionExpiredError
+from fastapi_cachex.session.exceptions import SessionInvalidError
+from fastapi_cachex.session.exceptions import SessionNotFoundError
+from fastapi_cachex.session.exceptions import SessionSecurityError
+from fastapi_cachex.session.exceptions import SessionTokenError
+from fastapi_cachex.session.models import Session
+from fastapi_cachex.session.models import SessionStatus
+from fastapi_cachex.session.models import SessionToken
+from fastapi_cachex.session.models import SessionUser
+from fastapi_cachex.session.security import SecurityManager
+from fastapi_cachex.types import ETagContent
+
+
+class SessionManager:
+    """Manages session lifecycle and storage."""
+
+    def __init__(self, backend: BaseCacheBackend, config: SessionConfig) -> None:
+        """Initialize session manager.
+
+        Args:
+            backend: Cache backend for session storage
+            config: Session configuration
+        """
+        self.backend = backend
+        self.config = config
+        self.security = SecurityManager(config.secret_key)
+
+    def _get_backend_key(self, session_id: str) -> str:
+        """Get backend storage key for a session.
+
+        Args:
+            session_id: The session ID
+
+        Returns:
+            Backend storage key
+        """
+        return f"{self.config.backend_key_prefix}{session_id}"
+
+    async def create_session(
+        self,
+        user: SessionUser | None = None,
+        ip_address: str | None = None,
+        user_agent: str | None = None,
+        **extra_data: dict[str, object],
+    ) -> tuple[Session, str]:
+        """Create a new session.
+
+        Args:
+            user: Optional user data
+            ip_address: Client IP address (if IP binding enabled)
+            user_agent: Client User-Agent (if UA binding enabled)
+            **extra_data: Additional session data
+
+        Returns:
+            Tuple of (Session, token_string)
+        """
+        # Create session
+        session = Session(
+            user=user,
+            data=extra_data,
+        )
+
+        # Set expiry
+        if self.config.session_ttl:
+            session.expires_at = datetime.now(timezone.utc) + timedelta(
+                seconds=self.config.session_ttl,
+            )
+
+        # Bind IP and User-Agent if configured
+        if self.config.ip_binding and ip_address:
+            session.ip_address = ip_address
+        if self.config.user_agent_binding and user_agent:
+            session.user_agent = user_agent
+
+        # Store in backend
+        await self._save_session(session)
+
+        # Generate signed token
+        token = self._create_token(session.session_id)
+
+        return session, token.to_string()
+
+    async def get_session(
+        self,
+        token_string: str,
+        ip_address: str | None = None,
+        user_agent: str | None = None,
+    ) -> Session:
+        """Retrieve and validate a session.
+
+        Args:
+            token_string: Session token string
+            ip_address: Current request IP address
+            user_agent: Current request User-Agent
+
+        Returns:
+            Session object
+
+        Raises:
+            SessionTokenError: If token is invalid
+            SessionNotFoundError: If session not found
+            SessionExpiredError: If session has expired
+            SessionInvalidError: If session is not active
+            SessionSecurityError: If security checks fail
+        """
+        # Parse and verify token
+        try:
+            token = SessionToken.from_string(token_string)
+        except ValueError as e:
+            raise SessionTokenError(str(e)) from e
+
+        if not self.security.verify_signature(token.session_id, token.signature):
+            msg = "Invalid session signature"
+            raise SessionSecurityError(msg)
+
+        # Load session from backend
+        session = await self._load_session(token.session_id)
+        if not session:
+            msg = f"Session {token.session_id} not found"
+            raise SessionNotFoundError(msg)
+
+        # Validate session
+        if session.status != SessionStatus.ACTIVE:
+            msg = f"Session is {session.status}"
+            raise SessionInvalidError(msg)
+
+        if session.is_expired():
+            session.status = SessionStatus.EXPIRED
+            await self._save_session(session)
+            msg = "Session has expired"
+            raise SessionExpiredError(msg)
+
+        # Security checks
+        if self.config.ip_binding and not self.security.check_ip_match(
+            session,
+            ip_address,
+        ):
+            msg = "IP address mismatch"
+            raise SessionSecurityError(msg)
+
+        if self.config.user_agent_binding and not self.security.check_user_agent_match(
+            session,
+            user_agent,
+        ):
+            msg = "User-Agent mismatch"
+            raise SessionSecurityError(msg)
+
+        # Update last accessed and handle sliding expiration
+        session.update_last_accessed()
+
+        if self.config.sliding_expiration and session.expires_at:
+            time_remaining = (
+                session.expires_at - datetime.now(timezone.utc)
+            ).total_seconds()
+            threshold = self.config.session_ttl * self.config.sliding_threshold
+
+            if time_remaining < threshold:
+                session.renew(self.config.session_ttl)
+
+        await self._save_session(session)
+
+        return session
+
+    async def update_session(self, session: Session) -> None:
+        """Update an existing session.
+
+        Args:
+            session: Session to update
+        """
+        session.update_last_accessed()
+        await self._save_session(session)
+
+    async def delete_session(self, session_id: str) -> None:
+        """Delete a session.
+
+        Args:
+            session_id: Session ID to delete
+        """
+        key = self._get_backend_key(session_id)
+        await self.backend.delete(key)
+
+    async def invalidate_session(self, session: Session) -> None:
+        """Invalidate a session.
+
+        Args:
+            session: Session to invalidate
+        """
+        session.invalidate()
+        await self._save_session(session)
+
+    async def regenerate_session_id(
+        self,
+        session: Session,
+    ) -> tuple[Session, str]:
+        """Regenerate session ID (after login for security).
+
+        Args:
+            session: Session to regenerate
+
+        Returns:
+            Tuple of (updated session, new token string)
+        """
+        # Delete old session
+        await self.delete_session(session.session_id)
+
+        # Generate new ID
+        session.regenerate_id()
+
+        # Save with new ID
+        await self._save_session(session)
+
+        # Create new token
+        token = self._create_token(session.session_id)
+
+        return session, token.to_string()
+
+    async def delete_user_sessions(self, user_id: str) -> int:
+        """Delete all sessions for a user.
+
+        Args:
+            user_id: User ID
+
+        Returns:
+            Number of sessions deleted
+        """
+        # This requires scanning all session keys
+        count = 0
+
+        try:
+            all_keys = await self.backend.get_all_keys()
+            for key in all_keys:
+                if key.startswith(self.config.backend_key_prefix):
+                    session = await self._load_session_by_key(key)
+                    if session and session.user and session.user.user_id == user_id:
+                        await self.backend.delete(key)
+                        count += 1
+        except NotImplementedError:
+            # Backend doesn't support get_all_keys, can't delete by user
+            pass
+
+        return count
+
+    async def clear_expired_sessions(self) -> int:
+        """Clear all expired sessions.
+
+        Returns:
+            Number of sessions cleared
+        """
+        count = 0
+
+        try:
+            all_keys = await self.backend.get_all_keys()
+            for key in all_keys:
+                if key.startswith(self.config.backend_key_prefix):
+                    session = await self._load_session_by_key(key)
+                    if session and session.is_expired():
+                        await self.backend.delete(key)
+                        count += 1
+        except NotImplementedError:
+            # Backend doesn't support get_all_keys
+            pass
+
+        return count
+
+    def _create_token(self, session_id: str) -> SessionToken:
+        """Create a signed session token.
+
+        Args:
+            session_id: Session ID to sign
+
+        Returns:
+            SessionToken object
+        """
+        signature = self.security.sign_session_id(session_id)
+        return SessionToken(session_id=session_id, signature=signature)
+
+    async def _save_session(self, session: Session) -> None:
+        """Save session to backend.
+
+        Args:
+            session: Session to save
+        """
+        key = self._get_backend_key(session.session_id)
+        value = session.model_dump_json().encode("utf-8")
+
+        # Calculate TTL
+        ttl = None
+        if session.expires_at:
+            ttl = int((session.expires_at - datetime.now(timezone.utc)).total_seconds())
+            ttl = max(ttl, 1)  # Ensure at least 1 second
+
+        # Store as bytes in cache backend (wrapped in ETagContent for compatibility)
+        etag = self.security.hash_data(value.decode("utf-8"))
+        await self.backend.set(key, ETagContent(etag=etag, content=value), ttl=ttl)
+
+    async def _load_session(self, session_id: str) -> Session | None:
+        """Load session from backend.
+
+        Args:
+            session_id: Session ID to load
+
+        Returns:
+            Session object or None if not found
+        """
+        key = self._get_backend_key(session_id)
+        return await self._load_session_by_key(key)
+
+    async def _load_session_by_key(self, key: str) -> Session | None:
+        """Load session from backend by key.
+
+        Args:
+            key: Backend key
+
+        Returns:
+            Session object or None if not found
+        """
+        cached = await self.backend.get(key)
+        if not cached:
+            return None
+
+        try:
+            return Session.model_validate_json(cached.content)
+        except (ValueError, TypeError):
+            # Invalid session data
+            return None

fastapi_cachex-0.2.2/fastapi_cachex/session/middleware.py

@@ -0,0 +1,127 @@
+"""Session middleware for FastAPI."""
+
+from typing import TYPE_CHECKING
+
+from fastapi import Request
+from fastapi import Response
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.middleware.base import RequestResponseEndpoint
+from starlette.types import ASGIApp
+
+from fastapi_cachex.session.config import SessionConfig
+from fastapi_cachex.session.exceptions import SessionError
+from fastapi_cachex.session.manager import SessionManager
+
+if TYPE_CHECKING:
+    from fastapi_cachex.session.models import Session
+
+
+class SessionMiddleware(BaseHTTPMiddleware):
+    """Middleware to handle session loading and cookie management."""
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        session_manager: SessionManager,
+        config: SessionConfig,
+    ) -> None:
+        """Initialize session middleware.
+
+        Args:
+            app: ASGI application
+            session_manager: Session manager instance
+            config: Session configuration
+        """
+        super().__init__(app)
+        self.session_manager = session_manager
+        self.config = config
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: RequestResponseEndpoint,
+    ) -> Response:
+        """Process request and handle session.
+
+        Args:
+            request: Incoming request
+            call_next: Next handler in chain
+
+        Returns:
+            Response
+        """
+        # Extract session token from request
+        token = self._extract_token(request)
+
+        # Try to load session
+        session: Session | None = None
+        if token:
+            try:
+                ip_address = self._get_client_ip(request)
+                user_agent = request.headers.get("user-agent")
+                session = await self.session_manager.get_session(
+                    token,
+                    ip_address=ip_address,
+                    user_agent=user_agent,
+                )
+            except SessionError:
+                # Session invalid/expired, continue without session
+                session = None
+
+        # Store session in request state
+        request.state.session = session
+
+        # Process request
+        response: Response = await call_next(request)
+
+        return response
+
+    def _extract_token(self, request: Request) -> str | None:
+        """Extract session token from request.
+
+        Args:
+            request: Incoming request
+
+        Returns:
+            Session token or None
+        """
+        for source in self.config.token_source_priority:
+            if source == "header":
+                token = request.headers.get(self.config.header_name)
+                if token:
+                    return token
+
+            elif source == "bearer":
+                if self.config.use_bearer_token:
+                    auth_header = request.headers.get("authorization")
+                    if auth_header and auth_header.startswith("Bearer "):
+                        bearer_prefix_len = 7
+                        return auth_header[bearer_prefix_len:]
+
+        return None
+
+    def _get_client_ip(self, request: Request) -> str | None:
+        """Get client IP address from request.
+
+        Args:
+            request: Incoming request
+
+        Returns:
+            Client IP address or None
+        """
+        # Check X-Forwarded-For header (for proxied requests)
+        forwarded_for = request.headers.get("x-forwarded-for")
+        if forwarded_for:
+            # Get first IP from comma-separated list
+            return forwarded_for.split(",")[0].strip()
+
+        # Check X-Real-IP header
+        real_ip = request.headers.get("x-real-ip")
+        if real_ip:
+            return real_ip
+
+        # Fallback to direct client IP
+        if request.client:
+            return request.client.host
+
+        return None

fastapi_cachex-0.2.2/fastapi_cachex/session/models.py

@@ -0,0 +1,166 @@
+"""Session data models and user structures."""
+
+from datetime import datetime
+from datetime import timedelta
+from datetime import timezone
+from enum import Enum
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel
+from pydantic import Field
+
+# Token format constant
+TOKEN_PARTS_COUNT = 3
+
+
+class SessionStatus(str, Enum):
+    """Session status enumeration."""
+
+    ACTIVE = "active"
+    EXPIRED = "expired"
+    INVALIDATED = "invalidated"
+
+
+class SessionUser(BaseModel):
+    """Base session user model.
+
+    This can be extended by application-specific user models.
+    """
+
+    user_id: str
+    username: str | None = None
+    email: str | None = None
+    roles: list[str] = Field(default_factory=list)
+    permissions: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {"extra": "allow"}
+
+
+class Session(BaseModel):
+    """Core session model containing all session data."""
+
+    session_id: str = Field(default_factory=lambda: str(uuid4()))
+    user: SessionUser | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    last_accessed: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    expires_at: datetime | None = None
+    status: SessionStatus = SessionStatus.ACTIVE
+    ip_address: str | None = None
+    user_agent: str | None = None
+    data: dict[str, Any] = Field(default_factory=dict)
+    flash_messages: list[dict[str, Any]] = Field(default_factory=list)
+
+    model_config = {"use_enum_values": True}
+
+    def is_valid(self) -> bool:
+        """Check if session is valid (active and not expired)."""
+        if self.status != SessionStatus.ACTIVE:
+            return False
+
+        return not (self.expires_at and datetime.now(timezone.utc) > self.expires_at)
+
+    def is_expired(self) -> bool:
+        """Check if session has expired."""
+        if self.expires_at is None:
+            return False
+        return datetime.now(timezone.utc) > self.expires_at
+
+    def update_last_accessed(self) -> None:
+        """Update the last accessed timestamp."""
+        self.last_accessed = datetime.now(timezone.utc)
+
+    def renew(self, ttl: int) -> None:
+        """Renew session expiry time.
+
+        Args:
+            ttl: Time-to-live in seconds
+        """
+        self.expires_at = datetime.now(timezone.utc) + timedelta(seconds=ttl)
+        self.update_last_accessed()
+
+    def invalidate(self) -> None:
+        """Mark session as invalidated."""
+        self.status = SessionStatus.INVALIDATED
+
+    def regenerate_id(self) -> str:
+        """Regenerate session ID (for security after login).
+
+        Returns:
+            The new session ID
+        """
+        self.session_id = str(uuid4())
+        return self.session_id
+
+    def add_flash_message(self, message: str, category: str = "info") -> None:
+        """Add a flash message.
+
+        Args:
+            message: The message content
+            category: Message category (info, success, warning, error)
+        """
+        self.flash_messages.append(
+            {
+                "message": message,
+                "category": category,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            }
+        )
+
+    def get_flash_messages(self, clear: bool = True) -> list[dict[str, Any]]:
+        """Get and optionally clear flash messages.
+
+        Args:
+            clear: Whether to clear messages after retrieving
+
+        Returns:
+            List of flash messages
+        """
+        messages = self.flash_messages.copy()
+        if clear:
+            self.flash_messages.clear()
+        return messages
+
+
+class SessionToken(BaseModel):
+    """Session token containing signed data."""
+
+    session_id: str
+    signature: str
+    issued_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    def to_string(self) -> str:
+        """Convert token to string format.
+
+        Format: {session_id}.{signature}.{timestamp}
+        """
+        timestamp = int(self.issued_at.timestamp())
+        return f"{self.session_id}.{self.signature}.{timestamp}"
+
+    @classmethod
+    def from_string(cls, token_str: str) -> "SessionToken":
+        """Parse token from string format.
+
+        Args:
+            token_str: Token string in format {session_id}.{signature}.{timestamp}
+
+        Returns:
+            SessionToken instance
+
+        Raises:
+            ValueError: If token format is invalid
+        """
+        parts = token_str.split(".")
+        if len(parts) != TOKEN_PARTS_COUNT:
+            msg = "Invalid token format"
+            raise ValueError(msg)
+
+        session_id, signature, timestamp = parts
+        try:
+            issued_at = datetime.fromtimestamp(int(timestamp), tz=timezone.utc)
+        except (ValueError, OSError) as e:
+            msg = f"Invalid timestamp in token: {e}"
+            raise ValueError(msg) from e
+
+        return cls(session_id=session_id, signature=signature, issued_at=issued_at)

fastapi_cachex-0.2.2/fastapi_cachex/session/security.py

@@ -0,0 +1,97 @@
+"""Security utilities for session management."""
+
+import hashlib
+import hmac
+
+from fastapi_cachex.session.models import Session
+
+
+class SecurityManager:
+    """Handles session security operations."""
+
+    def __init__(self, secret_key: str) -> None:
+        """Initialize security manager.
+
+        Args:
+            secret_key: Secret key for signing tokens
+        """
+        if len(secret_key) < 32:  # noqa: PLR2004
+            msg = "Secret key must be at least 32 characters"
+            raise ValueError(msg)
+        self.secret_key = secret_key.encode("utf-8")
+
+    def sign_session_id(self, session_id: str) -> str:
+        """Sign a session ID using HMAC-SHA256.
+
+        Args:
+            session_id: The session ID to sign
+
+        Returns:
+            The signature as a hex string
+        """
+        return hmac.new(
+            self.secret_key,
+            session_id.encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+
+    def verify_signature(self, session_id: str, signature: str) -> bool:
+        """Verify a session signature.
+
+        Args:
+            session_id: The session ID
+            signature: The signature to verify
+
+        Returns:
+            True if signature is valid, False otherwise
+        """
+        expected_signature = self.sign_session_id(session_id)
+        # Use constant-time comparison to prevent timing attacks
+        return hmac.compare_digest(expected_signature, signature)
+
+    def check_ip_match(self, session: Session, current_ip: str | None) -> bool:
+        """Check if session IP matches current request IP.
+
+        Args:
+            session: The session to check
+            current_ip: Current request IP address
+
+        Returns:
+            True if IPs match or session has no IP binding
+        """
+        if session.ip_address is None:
+            return True
+        if current_ip is None:
+            return False
+        return session.ip_address == current_ip
+
+    def check_user_agent_match(
+        self,
+        session: Session,
+        current_user_agent: str | None,
+    ) -> bool:
+        """Check if session User-Agent matches current request.
+
+        Args:
+            session: The session to check
+            current_user_agent: Current request User-Agent
+
+        Returns:
+            True if User-Agents match or session has no UA binding
+        """
+        if session.user_agent is None:
+            return True
+        if current_user_agent is None:
+            return False
+        return session.user_agent == current_user_agent
+
+    def hash_data(self, data: str) -> str:
+        """Hash data using SHA-256.
+
+        Args:
+            data: Data to hash
+
+        Returns:
+            Hex digest of the hash
+        """
+        return hashlib.sha256(data.encode("utf-8")).hexdigest()

{fastapi_cachex-0.2.1 → fastapi_cachex-0.2.2}/fastapi_cachex/types.py

@@ -1,8 +1,17 @@
 """Type definitions and type aliases for FastAPI-CacheX."""
 
+from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Any
 
+from fastapi import Request
+
+# Cache key separator - using ||| to avoid conflicts with port numbers in host (e.g., 127.0.0.1:8000)
+CACHE_KEY_SEPARATOR = "|||"
+
+# Type for custom cache key builder function
+CacheKeyBuilder = Callable[[Request], str]
+
 
 @dataclass
 class ETagContent:

{fastapi_cachex-0.2.1 → fastapi_cachex-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-cachex"
-version = "0.2.1"
+version = "0.2.2"
 description = "A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends."
 readme = "README.md"
 requires-python = ">=3.10"