fastapi-cachex 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

fastapi_cachex/session/config.py

@@ -0,0 +1,70 @@
+"""Session configuration settings."""
+
+from typing import Literal
+
+from pydantic import BaseModel
+from pydantic import Field
+from pydantic import SecretStr
+
+
+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: SecretStr = 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/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 .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, "__fastapi_cachex_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, "__fastapi_cachex_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/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/session/manager.py

@@ -0,0 +1,389 @@
+"""Session manager for CRUD operations."""
+
+import logging
+from datetime import datetime
+from datetime import timedelta
+from datetime import timezone
+
+from fastapi_cachex.backends.base import BaseCacheBackend
+from fastapi_cachex.types import ETagContent
+
+from .config import SessionConfig
+from .exceptions import SessionExpiredError
+from .exceptions import SessionInvalidError
+from .exceptions import SessionNotFoundError
+from .exceptions import SessionSecurityError
+from .exceptions import SessionTokenError
+from .models import Session
+from .models import SessionStatus
+from .models import SessionToken
+from .models import SessionUser
+from .security import SecurityManager
+
+logger = logging.getLogger(__name__)
+
+
+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
+        secret_value = config.secret_key.get_secret_value()
+        self.security = SecurityManager(secret_value)
+        logger.debug(
+            "SessionManager initialized with backend prefix=%s",
+            config.backend_key_prefix,
+        )
+
+    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)
+        logger.debug(
+            "Session created; id=%s ttl=%s ip=%s ua=%s",
+            session.session_id,
+            self.config.session_ttl,
+            session.ip_address,
+            session.user_agent,
+        )
+
+        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:
+            logger.debug("Session token parse error: %s", e)
+            raise SessionTokenError(str(e)) from e
+
+        if not self.security.verify_signature(token.session_id, token.signature):
+            msg = "Invalid session signature"
+            logger.debug(
+                "Session signature verification failed; id=%s", token.session_id
+            )
+            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"
+            logger.debug("Session not found; id=%s", token.session_id)
+            raise SessionNotFoundError(msg)
+
+        # Validate session
+        if session.status != SessionStatus.ACTIVE:
+            msg = f"Session is {session.status}"
+            logger.debug(
+                "Session not active; id=%s status=%s",
+                session.session_id,
+                session.status,
+            )
+            raise SessionInvalidError(msg)
+
+        if session.is_expired():
+            session.status = SessionStatus.EXPIRED
+            await self._save_session(session)
+            msg = "Session has expired"
+            logger.debug("Session expired; id=%s", session.session_id)
+            raise SessionExpiredError(msg)
+
+        # Security checks
+        if self.config.ip_binding and not self.security.check_ip_match(
+            session,
+            ip_address,
+        ):
+            msg = "IP address mismatch"
+            logger.debug(
+                "IP mismatch; id=%s expected=%s got=%s",
+                session.session_id,
+                session.ip_address,
+                ip_address,
+            )
+            raise SessionSecurityError(msg)
+
+        if self.config.user_agent_binding and not self.security.check_user_agent_match(
+            session,
+            user_agent,
+        ):
+            msg = "User-Agent mismatch"
+            logger.debug(
+                "UA mismatch; id=%s expected=%s got=%s",
+                session.session_id,
+                session.user_agent,
+                user_agent,
+            )
+            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)
+                logger.debug(
+                    "Session renewed (sliding expiration); id=%s ttl=%s",
+                    session.session_id,
+                    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)
+        logger.debug("Session updated; id=%s", session.session_id)
+
+    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)
+        logger.debug("Session deleted; id=%s", session_id)
+
+    async def invalidate_session(self, session: Session) -> None:
+        """Invalidate a session.
+
+        Args:
+            session: Session to invalidate
+        """
+        session.invalidate()
+        await self._save_session(session)
+        logger.debug("Session invalidated; id=%s", session.session_id)
+
+    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
+        old_id = session.session_id
+        session.regenerate_id()
+
+        # Save with new ID
+        await self._save_session(session)
+
+        # Create new token
+        token = self._create_token(session.session_id)
+        logger.debug(
+            "Session ID regenerated; old_id=%s new_id=%s", old_id, 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:  # pragma: no cover
+            # Backend doesn't support get_all_keys, can't delete by user
+            pass
+
+        logger.debug("User sessions deleted; user_id=%s count=%s", user_id, count)
+        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:  # pragma: no cover
+            # Backend doesn't support get_all_keys
+            pass
+
+        logger.debug("Expired sessions cleared; count=%s", count)
+        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)
+        logger.debug("Session saved; id=%s ttl=%s", session.session_id, 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:
+            logger.debug("Session load MISS; key=%s", key)
+            return None
+
+        try:
+            return Session.model_validate_json(cached.content)
+        except (ValueError, TypeError):  # pragma: no cover
+            # Invalid session data
+            logger.debug("Session load DESERIALIZE ERROR; key=%s", key)
+            return None

fastapi_cachex/session/middleware.py

@@ -0,0 +1,149 @@
+"""Session middleware for FastAPI."""
+
+import logging
+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 .config import SessionConfig
+from .exceptions import SessionError
+from .manager import SessionManager
+
+if TYPE_CHECKING:
+    from .models import Session
+
+logger = logging.getLogger(__name__)
+
+
+class SessionMiddleware(BaseHTTPMiddleware):
+    """Middleware to handle session loading and cookie management."""
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        session_manager: SessionManager,
+        config: SessionConfig | None = None,
+    ) -> None:
+        """Initialize session middleware.
+
+        Args:
+            app: ASGI application
+            session_manager: Session manager instance
+            config: Session configuration
+        """
+        super().__init__(app)
+        self.session_manager = session_manager
+
+        if config is None:
+            config = self.session_manager.config
+
+        self.config = config
+
+        logger.debug(
+            "SessionMiddleware initialized; header=%s bearer=%s",
+            config.header_name,
+            config.use_bearer_token,
+        )
+
+    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,
+                )
+                logger.debug("Session loaded in middleware; id=%s", session.session_id)
+            except SessionError:
+                # Session invalid/expired, continue without session
+                session = None
+                logger.debug("Session failed to load; token invalid/expired")
+
+        # Store session in request state
+        setattr(request.state, "__fastapi_cachex_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:
+                    logger.debug("Token extracted from header")
+                    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
+                        token_value = auth_header[bearer_prefix_len:]
+                        logger.debug("Token extracted from bearer auth")
+                        return token_value
+
+        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
+            ip = forwarded_for.split(",")[0].strip()
+            logger.debug("Client IP from X-Forwarded-For: %s", ip)
+            return ip
+
+        # Check X-Real-IP header
+        real_ip = request.headers.get("x-real-ip")
+        if real_ip:
+            logger.debug("Client IP from X-Real-IP: %s", real_ip)
+            return real_ip
+
+        # Fallback to direct client IP
+        if request.client:
+            logger.debug("Client IP from connection: %s", request.client.host)
+            return request.client.host
+
+        return None