TASK-003: Document process-local constraint for RuntimeState and SessionCache

- Add comprehensive docstring to runtime_state.py explaining single-process
  constraint, impacts in multi-worker deployments, and solution approach
- Add comprehensive docstring to session_cache.py explaining process-local
  cache limitation, security implications, and Redis/database alternatives
- Update Architecture.md to clarify session cache is process-local and
  describe single-worker enforcement via TASK-002
- Update Architecture.md runtime state section with detailed explanation of
  per-process state and multi-worker impacts
- Add Backend-Development.md section 13.7.2 documenting session cache
  pluggability pattern with example Redis implementation
- All tests pass; linting passes; type checking has pre-existing errors

This is the short-term fix for TASK-003: enforce single-worker deployment
(TASK-002) and document the constraint clearly. The long-term fix (Redis
backend) is deferred as a follow-up.
This commit is contained in:
2026-04-26 11:43:34 +02:00
parent 825a67f13a
commit d982fe3efc
4 changed files with 145 additions and 7 deletions

View File

@@ -3,6 +3,50 @@
This module defines a cache interface for authenticated sessions and a default
process-local in-memory implementation. The backend can swap the cache
implementation without changing the authentication dependency logic.
⚠️ PROCESS-LOCAL CONSTRAINT (InMemorySessionCache)
====================================================
InMemorySessionCache stores validated sessions in a process-local dict.
This means:
- Each worker process has its own independent session cache.
- A session invalidated (logout) by worker A is still valid in worker B.
- Changes to the cache in one process are NOT visible to other processes.
IMPACT IN MULTI-WORKER DEPLOYMENTS:
- User logs out (worker A clears session from its cache).
- User makes a new request → routed to worker B.
- Worker B still has the stale session in its cache → request is accepted.
- User appears still logged in (from their perspective).
This is a security issue: logout does not work reliably across workers.
MULTI-WORKER SOLUTION:
To deploy BanGUI with multiple workers (e.g., via gunicorn -w 4), replace
InMemorySessionCache with a shared backend such as:
- RedisSessionCache — backed by Redis (recommended for production).
- DatabaseSessionCache — backed by SQLite or PostgreSQL.
- SharedMemorySessionCache — backed by IPC (for local multi-process).
The SessionCache Protocol is already designed for pluggable backends:
class SessionCache(Protocol):
def get(token: str) -> Session | None: ...
def set(token: str, session: Session, ttl_seconds: float) -> None: ...
def invalidate(token: str) -> None: ...
def clear() -> None: ...
To add Redis support:
1. Create RedisSessionCache in this module (implements SessionCache).
2. Update runtime_state.set_runtime_settings() to instantiate RedisSessionCache
when REDIS_URL is configured.
3. See Backend-Development.md § "Session Cache Pluggability" for details.
SINGLE-WORKER ENFORCEMENT:
See TASK-002 in Docs/Tasks.md for deployment configuration that enforces
single-worker mode, preventing this issue entirely.
For now, BanGUI is deployed as single-worker only — this constraint is
acceptable and keeps the implementation simple.
"""
from __future__ import annotations