BanGUI/Docs/Tasks.md

BanGUI — Task List

This document breaks the entire BanGUI project into development stages, ordered so that each stage builds on the previous one. Every task is described in prose with enough detail for a developer to begin work. References point to the relevant documentation.

Reference: Docs/Refactoring.md for full analysis of each issue.

---

Open Issues

1. Fix setup persistence

• Where found: backend/app/config.py, backend/app/startup.py, backend/app/services/setup_service.py, backend/app/routers/setup.py
• Goal: runtime configuration should use the values persisted during setup for database_path, fail2ban_socket, timezone, and session_duration_minutes rather than only environment defaults.
• Status: completed
• Possible traps and issues:
  • Setup may appear successful but later use a different DB/socket on restart.
  • A partially persisted setup run must not leave the app in a broken or half-configured state.
  • Using both env vars and persisted settings requires a clear precedence model.

2. Remove or use session_secret

• Where found: backend/app/config.py
• Goal: either eliminate the unused BANGUI_SESSION_SECRET requirement or use it for session token generation / signing so the setting has purpose.
• Status: completed
• Possible traps and issues:
  • Keeping it required without use is misleading and burdens deployments.
  • Introducing a new crypto dependency for session tokens must preserve backward compatibility with existing sessions.
  • If switched to signed tokens, ensure token revocation / logout still works correctly.

3. Harden session cookie security

• Where found: backend/app/routers/auth.py
• Goal: auth cookies should be set with secure=True in HTTPS production deployments and SameSite/HttpOnly behavior should be explicit and configurable.
• Possible traps and issues:
  • Hardcoding secure=False makes production deployment insecure.
  • Switching to secure=True can break local development unless there is an explicit dev override.
  • The frontend API may need matching CORS and same-site handling when served from a different origin.
• Status: completed — implemented configurable session cookie flags and secure mode support.

4. Address session cache invalidation semantics

• Where found: backend/app/dependencies.py
• Goal: make session caching safe or remove it, and document that cache invalidation is not cluster-safe if the app is run with multiple workers.
• Status: completed — session validation cache is now disabled by default and can be enabled explicitly in single-process deployments.
• Possible traps and issues:
  • Process-local cache can keep revoked sessions alive in other worker processes.
  • Implementing a shared cache is a larger architectural change; a safer short-term fix is to disable caching by default.
  • Need to ensure logout() and session expiry remain consistent across requests.

5. Improve external HTTP client resilience

• Where found: backend/app/startup.py
• Goal: create aiohttp.ClientSession() with sensible global timeouts, connection limit settings, and optional retry policy for geo/blocklist API calls.
• Status: completed — configured shared aiohttp session with sensible timeouts, connection limits, and retry support for transient blocklist/geo failures.
• Possible traps and issues:
  • Without timeouts, external lookups can hang request handling or background tasks.
  • Connection limits must be chosen carefully to avoid underutilization or overload.
  • A retry policy should avoid retry storms and should respect API rate limits.

6. Update async socket handling

• Where found: backend/app/utils/fail2ban_client.py, backend/app/startup.py
• Goal: use modern asyncio APIs (get_running_loop()), avoid blocking operations on the event loop, and ensure startup resources are cleaned up if initialization fails.
• Status: completed — switched fail2ban socket I/O to asyncio.to_thread and added startup cleanup for failed resource initialization.
• Possible traps and issues:
  • asyncio.get_event_loop() behavior changed in newer Python versions; this can cause runtime warnings or errors.
  • Resource leaks can occur if startup_shared_resources() fails before the lifespan shutdown path is reached.
  • The fail2ban socket client should still handle transient errors and not hide protocol failures behind generic exceptions.