"""Opaque Bearer sessions: PostgreSQL is the source of truth, Valkey is a cache. Design (see REPORT.md): * ``sessions`` in PostgreSQL owns identity, expiry and revocation. * Valkey stores the same session under ``session:`` for at most ``CACHE_TTL_SECONDS`` and never longer than the session's remaining lifetime. * Revocation writes a tombstone instead of relying on ``DEL`` alone, so a stale cache entry cannot authenticate after logout. * When Valkey is unavailable every request falls back to PostgreSQL. A cache error is never treated as "authenticated", and a cache hit is only trusted because it came from a session row that PostgreSQL confirmed at login time. """ from __future__ import annotations import hashlib import json import logging import secrets import time import uuid from datetime import datetime, timezone from typing import Any import redis.asyncio as redis from psycopg_pool import AsyncConnectionPool from redis.backoff import NoBackoff from redis.retry import Retry from . import store from .config import DEFAULT_IDEMPOTENCY_TTL_SECONDS as IDEMPOTENCY_TTL_SECONDS from .errors import ApiProblem from .pagination import format_timestamp logger = logging.getLogger("messenger.sessions") TOKEN_BYTES = 48 # 384 bits of entropy, well above the required 256. CACHE_PREFIX = "session:" REVOKED = "revoked" # After a cache error, skip Valkey for a few seconds instead of paying the # connect timeout on every request (lookup and remember would cost two each). FAILURE_COOLDOWN_SECONDS = 5.0 # Bound on revocations remembered while the cache cannot accept a tombstone. MAX_PENDING_REVOCATIONS = 4096 HIT = "hit" MISS = "miss" TOMBSTONE = "revoked" ERROR = "error" def token_hash(token: str) -> str: return hashlib.sha256(token.encode("utf-8")).hexdigest() class SessionCache: """Small, failure-tolerant Valkey client used only for session lookups.""" def __init__(self, url: str | None, *, timeout_seconds: float, ttl_cap: int) -> None: self.ttl_cap = max(1, ttl_cap) self.timeout_seconds = timeout_seconds # hashed token -> epoch at which the session would be expired anyway. # PostgreSQL already holds the authoritative revocation; this only keeps # logout immediate for this process while the cache is unreachable. self._pending: dict[str, float] = {} self._disabled_until = 0.0 self._degraded = False self.client: redis.Redis | None = None if url: self.client = redis.Redis.from_url( url, socket_timeout=timeout_seconds, socket_connect_timeout=timeout_seconds, decode_responses=True, health_check_interval=30, # A cache must fail fast: one attempt, no retry loop, so a dead # Valkey costs at most one timeout before PostgreSQL answers. retry=Retry(NoBackoff(), 0), retry_on_error=[], ) @property def enabled(self) -> bool: return self.client is not None def _ready(self) -> bool: """True when a cache call is worth attempting right now.""" return self.client is not None and time.monotonic() >= self._disabled_until def _unavailable(self, operation: str, exc: BaseException) -> None: self._disabled_until = time.monotonic() + FAILURE_COOLDOWN_SECONDS # One warning per outage, not one per request. if not self._degraded: self._degraded = True logger.warning( "cache_unavailable operation=%s error=%s cooldown_seconds=%s", operation, type(exc).__name__, FAILURE_COOLDOWN_SECONDS, ) def _ok(self) -> None: self._degraded = False def remember_revocation(self, hashed: str, remaining: float) -> None: """Ask this process to reject a token even if the cache cannot store it.""" if len(self._pending) >= MAX_PENDING_REVOCATIONS: # Drop the entries closest to expiry: they are the least useful. keep = len(self._pending) // 4 for key, _ in sorted(self._pending.items(), key=lambda item: item[1])[:keep]: self._pending.pop(key, None) self._pending[hashed] = time.time() + max(1.0, remaining) def is_locally_revoked(self, hashed: str) -> bool: deadline = self._pending.get(hashed) if deadline is None: return False if deadline <= time.time(): self._pending.pop(hashed, None) return False return True async def _flush_revocations(self) -> None: """Re-apply tombstones that could not be written during an outage.""" for hashed, deadline in list(self._pending.items()): remaining = deadline - time.time() if remaining <= 0: self._pending.pop(hashed, None) continue try: await self.client.set(self._key(hashed), REVOKED, ex=self._ttl(remaining)) except Exception as exc: # noqa: BLE001 - still revoked in PostgreSQL self._unavailable("flush_revocation", exc) return self._pending.pop(hashed, None) async def ping(self) -> bool: if self.client is None: return False try: alive = bool(await self.client.ping()) except Exception as exc: # noqa: BLE001 - any client error means "no cache" logger.warning("cache_ping_failed error=%s", type(exc).__name__) return False self._disabled_until = 0.0 self._ok() return alive async def close(self) -> None: if self.client is None: return try: await self.client.aclose() except Exception as exc: # noqa: BLE001 - shutdown must not fail on cache logger.warning("cache_close_failed error=%s", type(exc).__name__) def _key(self, hashed: str) -> str: return CACHE_PREFIX + hashed def _ttl(self, seconds: float) -> int: return max(1, min(int(seconds), self.ttl_cap)) async def lookup(self, hashed: str) -> tuple[str, dict[str, Any] | None]: """Return (state, payload); every cache failure degrades to a DB read.""" if not self._ready(): return MISS, None if self._pending: await self._flush_revocations() if not self._ready(): return MISS, None try: raw = await self.client.get(self._key(hashed)) self._ok() except Exception as exc: # noqa: BLE001 - cache must never break auth self._unavailable("lookup", exc) return ERROR, None if raw is None: return MISS, None if raw == REVOKED: return TOMBSTONE, None try: payload = json.loads(raw) user = payload["user"] user["id"] = str(uuid.UUID(user["id"])) payload["expires_epoch"] = float(payload["expires_epoch"]) payload["user"] = user except (ValueError, KeyError, TypeError, json.JSONDecodeError): logger.warning("cache_payload_invalid") return MISS, None return HIT, payload async def remember(self, hashed: str, user: dict[str, Any], expires_at: datetime) -> None: if not self._ready(): return remaining = (expires_at - datetime.now(timezone.utc)).total_seconds() if remaining <= 0: return # Cache the immutable public user snapshot, so a hit needs no SQL at all. # Users cannot be renamed or deleted in the mandatory API of lab 2. payload = { "user": user, "expires_epoch": expires_at.timestamp(), } try: await self.client.set( self._key(hashed), json.dumps(payload, ensure_ascii=False), ex=self._ttl(remaining), ) self._ok() except Exception as exc: # noqa: BLE001 - a missed cache write is not fatal self._unavailable("remember", exc) async def revoke(self, hashed: str, expires_at: datetime | None) -> None: """Write a tombstone so a stale entry cannot authenticate after logout.""" remaining = 60.0 if expires_at is not None: remaining = max(1.0, (expires_at - datetime.now(timezone.utc)).total_seconds()) # PostgreSQL already revoked the session; this keeps the fast path honest # even if the tombstone cannot be written right now. self.remember_revocation(hashed, remaining) if not self._ready(): return try: await self.client.set(self._key(hashed), REVOKED, ex=self._ttl(remaining)) self._pending.pop(hashed, None) self._ok() except Exception as exc: # noqa: BLE001 - PostgreSQL already revoked the session self._unavailable("revoke", exc) def _user_payload(row: dict[str, Any]) -> dict[str, Any]: return { "id": str(row["id"]), "username": row["username"], "display_name": row["display_name"], "created_at": format_timestamp(row["created_at"]), } async def create_session( pool: AsyncConnectionPool, cache: SessionCache, *, user_id: uuid.UUID, ttl_seconds: int, ) -> tuple[str, datetime]: token = secrets.token_urlsafe(TOKEN_BYTES) hashed = token_hash(token) async with pool.connection() as connection: async with connection.cursor() as cursor: expires_at = await store.insert_session( cursor, user_id=user_id, token_hash=hashed, ttl_seconds=ttl_seconds ) user = await store.user_by_id(cursor, user_id) if user is not None: await cache.remember(hashed, _user_payload(user), expires_at) return token, expires_at async def resolve_session( pool: AsyncConnectionPool, cache: SessionCache, token: str ) -> tuple[uuid.UUID, dict[str, Any]]: """Return the authenticated user or raise 401 with a Bearer challenge.""" hashed = token_hash(token) if cache.is_locally_revoked(hashed): raise ApiProblem( 401, "unauthorized", "Session token is expired or revoked", {"WWW-Authenticate": 'Bearer realm="messenger"'}, ) state, _payload = await cache.lookup(hashed) if state == TOMBSTONE: raise ApiProblem( 401, "unauthorized", "Session token is expired or revoked", {"WWW-Authenticate": 'Bearer realm="messenger"'}, ) # PostgreSQL is the authoritative revocation store. A cache value can only # accelerate the immutable user snapshot; it must never be enough to grant # access on its own. This makes logout durable across API replicas and # Valkey outages/restores, where a tombstone may not reach shared cache. async with pool.connection() as connection: async with connection.cursor() as cursor: row = await store.session_user(cursor, hashed) if row is None: await cache.revoke(hashed, None) raise ApiProblem( 401, "unauthorized", "Session token is expired or revoked", {"WWW-Authenticate": 'Bearer realm="messenger"'}, ) user = _user_payload(row) # Refresh an old cache hit after PostgreSQL has confirmed it is still live. await cache.remember(hashed, user, row["expires_at"]) return uuid.UUID(user["id"]), user async def revoke_session( pool: AsyncConnectionPool, cache: SessionCache, token: str ) -> None: hashed = token_hash(token) async with pool.connection() as connection: async with connection.cursor() as cursor: expires_at = await store.revoke_session(cursor, hashed) if expires_at is None: raise ApiProblem( 401, "unauthorized", "Session token is expired or revoked", {"WWW-Authenticate": 'Bearer realm="messenger"'}, ) await cache.revoke(hashed, expires_at) async def purge_expired(pool: AsyncConnectionPool) -> int: async with pool.connection() as connection: async with connection.cursor() as cursor: return await store.purge_expired_sessions(cursor) async def purge_expired_idempotency(pool: AsyncConnectionPool) -> int: async with pool.connection() as connection: async with connection.cursor() as cursor: await cursor.execute( """ DELETE FROM idempotency_keys WHERE created_at < now() - (%s || ' seconds')::interval """, (str(IDEMPOTENCY_TTL_SECONDS),), ) return cursor.rowcount