Buckets:

download
raw
16.4 kB
"""Session manager for CRUD operations."""
import logging
from collections.abc import AsyncIterator
from datetime import datetime
from datetime import timedelta
from datetime import timezone
from fastapi_cachex.backends.base import BaseCacheBackend
from fastapi_cachex.types import CacheEntry
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
from .token_serializers import JWTTokenSerializer
from .token_serializers import SimpleTokenSerializer
from .token_serializers import TokenSerializer
logger = logging.getLogger(__name__)
def _now() -> datetime:
return datetime.now(timezone.utc)
class SessionManager:
"""Manages session lifecycle and storage."""
def __init__(
self,
backend: BaseCacheBackend,
config: SessionConfig,
token_serializer: TokenSerializer | None = None,
) -> None:
"""Initialize session manager.
Args:
backend: Cache backend for session storage
config: Session configuration
token_serializer: Optional custom token serializer. If provided,
overrides the built-in selection (simple/jwt).
"""
self.backend = backend
self.config = config
secret_value = config.secret_key.get_secret_value()
self.security = SecurityManager(secret_value)
# Select token serializer strategy (allow DI override)
if token_serializer is not None:
self._serializer = token_serializer
elif config.token_format == "jwt":
self._serializer = JWTTokenSerializer(config)
else:
self._serializer = SimpleTokenSerializer()
logger.debug("Token serializer: %s", type(self._serializer).__name__)
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,
ip_address: str | None = None,
user_agent: str | None = None,
**extra_data: object,
) -> tuple[Session, str]:
"""Create a new session for an authenticated user.
Args:
user: Authenticated 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)
"""
return await self._create_session(
user=user,
ip_address=ip_address,
user_agent=user_agent,
**extra_data,
)
async def create_anonymous_session(
self,
ip_address: str | None = None,
user_agent: str | None = None,
**extra_data: object,
) -> tuple[Session, str]:
"""Create a new session without user information."""
return await self._create_session(
user=None,
ip_address=ip_address,
user_agent=user_agent,
**extra_data,
)
async def _create_session(
self,
user: SessionUser | None,
ip_address: str | None = None,
user_agent: str | None = None,
**extra_data: object,
) -> tuple[Session, str]:
"""Internal helper to create and persist a session."""
session = Session(
user=user,
data=extra_data,
)
# Set expiry
if self.config.session_ttl:
session.expires_at = _now() + timedelta(seconds=self.config.session_ttl)
# Bind IP and User-Agent if configured
if self.config.ip_binding:
if ip_address:
session.ip_address = ip_address
else:
logger.warning(
"ip_binding is enabled but no IP address available; "
"session created without IP binding"
)
if self.config.user_agent_binding:
if user_agent:
session.user_agent = user_agent
else:
logger.warning(
"user_agent_binding is enabled but no User-Agent available; "
"session created without UA binding"
)
# Store in backend
await self._save_session(session)
# Generate signed token (pass expires_at so JWT exp reflects sliding expiration)
token = self._create_token(session.session_id, expires_at=session.expires_at)
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, self._serializer.to_string(token)
async def get_session(
self,
token_string: str,
ip_address: str | None = None,
user_agent: str | None = None,
) -> tuple[Session, str | None]:
"""Retrieve and validate a session.
Args:
token_string: Session token string
ip_address: Current request IP address
user_agent: Current request User-Agent
Returns:
Tuple of (session, new_token_string). new_token_string is non-None
when sliding expiration triggered a renewal; the caller should
propagate it to the client (e.g. via a response header).
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 = self._serializer.from_string(token_string)
except ValueError as e:
logger.debug("Session token parse error: %s", e)
raise SessionTokenError(str(e)) from e
# For simple format, verify signature explicitly
if self.config.token_format == "simple" and 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():
logger.debug("Session expired; id=%s", session.session_id)
await self._expire(session, "Session has expired")
# Check absolute timeout (hard cap regardless of sliding expiration)
if self.config.absolute_timeout is not None and _now() >= (
session.created_at + timedelta(seconds=self.config.absolute_timeout)
):
logger.debug(
"Session absolute timeout exceeded; id=%s created_at=%s",
session.session_id,
session.created_at,
)
await self._expire(session, "Session has exceeded absolute timeout")
# 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()
renewed_token: str | None = None
if self.config.sliding_expiration and session.expires_at:
time_remaining = (session.expires_at - _now()).total_seconds()
threshold = self.config.session_ttl * self.config.sliding_threshold
if time_remaining < threshold:
session.renew(self.config.session_ttl)
token = self._create_token(
session.session_id, expires_at=session.expires_at
)
renewed_token = self._serializer.to_string(token)
logger.debug(
"Session renewed (sliding expiration); id=%s ttl=%s",
session.session_id,
self.config.session_ttl,
)
await self._save_session(session)
return session, renewed_token
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 (pass expires_at so JWT exp reflects current expiry)
token = self._create_token(session.session_id, expires_at=session.expires_at)
logger.debug(
"Session ID regenerated; old_id=%s new_id=%s", old_id, session.session_id
)
return session, self._serializer.to_string(token)
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
"""
count = 0
async for key, session in self._iter_sessions():
if session.user and session.user.user_id == user_id:
await self.backend.delete(key)
count += 1
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
async for key, session in self._iter_sessions():
if session.is_expired():
await self.backend.delete(key)
count += 1
logger.debug("Expired sessions cleared; count=%s", count)
return count
async def _iter_sessions(self) -> AsyncIterator[tuple[str, Session]]:
"""Yield every readable session under this manager's prefix with its key.
Backends without key enumeration (which raise NotImplementedError)
simply yield nothing.
"""
try:
all_keys = await self.backend.get_all_keys()
except NotImplementedError: # pragma: no cover
return
for key in all_keys:
if not key.startswith(self.config.backend_key_prefix):
continue
session = await self._load_session_by_key(key)
if session is not None:
yield key, session
async def _expire(self, session: Session, reason: str) -> None:
"""Persist ``session`` as expired and raise SessionExpiredError."""
session.status = SessionStatus.EXPIRED
await self._save_session(session)
raise SessionExpiredError(reason)
def _create_token(
self,
session_id: str,
expires_at: datetime | None = None,
) -> SessionToken:
"""Create a signed session token.
Args:
session_id: Session ID to sign
expires_at: Session expiry time, forwarded to JWT serializers
Returns:
SessionToken object
"""
# For 'simple' format, include HMAC signature in the token model.
# For 'jwt' format, signature will be embedded in the JWT string; we can
# leave the signature field empty as it won't be used downstream.
signature = (
self.security.sign_session_id(session_id)
if self.config.token_format == "simple"
else ""
)
return SessionToken(
session_id=session_id, signature=signature, expires_at=expires_at
)
async def _save_session(self, session: Session) -> None:
"""Save session to backend.
Args:
session: Session to save
"""
payload = session.model_dump_json()
# Calculate TTL
ttl = None
if session.expires_at:
ttl = int((session.expires_at - _now()).total_seconds())
ttl = max(ttl, 1) # Ensure at least 1 second
entry = CacheEntry(
fingerprint=self.security.hash_data(payload),
content=payload.encode("utf-8"),
)
await self.backend.set(
self._get_backend_key(session.session_id), entry, 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
"""
return await self._load_session_by_key(self._get_backend_key(session_id))
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):
logger.debug("Session load DESERIALIZE ERROR; key=%s", key)
return None

Xet Storage Details

Size:
16.4 kB
·
Xet hash:
2e2ce5030e381e0c7db24da4d143b7ae38b71509ca51c0807fa78e5191fc5fc6

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.