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

---

Backend Architecture

• Replace the single shared SQLite connection. ✅

  • Current startup code opens one aiosqlite.Connection and reuses it for every request.
  • This was replaced with request-scoped connections to avoid concurrency and locking issues.
  • Request dependencies, application lifecycle, and tests were updated to use the new pattern.

• Refactor dependency wiring and shared resource management.

  • Remove hidden module-level import coupling between routers, services, and shared utilities.
  • Introduce explicit factories or providers for shared resources such as DB, HTTP client session, scheduler, and settings.
  • Ensure routers depend on injected providers rather than global state or dynamic imports.

• Harden fail2ban integration.

  • Remove the sys.path hack that locates fail2ban-master at runtime.
  • Replace it with a deterministic packaging or configuration model so the backend does not depend on repository layout.
  • Refactor Fail2BanClient so concurrency control is instance-based and not backed by hidden module globals.

• Improve startup / setup guard behavior.

  • Convert SetupRedirectMiddleware from an on-demand DB check into a startup/initialisation guard where possible.
  • Cache setup completion in a safe way and provide an explicit invalidation path if the application state changes.
  • Reduce middleware responsibility and avoid DB access during normal request dispatch.

• Make deployment configuration explicit.

  • Move hard-coded environment assumptions such as CORS origins into settings.
  • Ensure fail2ban_socket, fail2ban_config_dir, and startup commands are fully configurable via Settings.
  • Document production-ready defaults separately from development defaults.

Reliability and Resilience

• Add backend lifecycle tests for resource cleanup.

  • Verify startup opens and initialises DB, HTTP session, scheduler, and geo cache correctly.
  • Verify shutdown closes those resources cleanly.

• Add concurrency/regression coverage for DB and fail2ban socket use.

  • Add tests that simulate multiple concurrent requests using the same DB dependency.
  • Add tests around fail2ban socket retries, protocol errors, and rate limiting.

• Improve state caching and invalidation.

  • Add tests for session cache invalidation on logout.
  • Add tests for setup completion caching so stale state is never served.

Backend Feature Work

• Document and implement backend-safe environment-driven CORS.

  • Add support for production and local development origins through configuration.
  • Avoid a hardcoded Vite origin in the core app factory.

• Centralise scheduler job registration.

  • Refactor APScheduler registration so background tasks are registered through a common lifecycle helper.
  • Ensure jobs can be discovered, replaced, and tested without requiring implicit app.state side effects.

• Strengthen fail2ban error handling and reporting.

  • Standardise 502 responses for connection/protocol failures across all endpoints.
  • Add structured logging for retries and fatal socket failures.
  • Ensure the UI can distinguish offline fail2ban from internal backend failures.

• Improve documentation of backend responsibilities.

  • Keep Docs/Tasks.md aligned with the backend architecture review.
  • Add references to the backend modules, resource lifecycle, and dependency model in the documentation.

Priority Execution Plan

1. Fix the global SQLite connection pattern and tests.
2. Refactor dependency injection / explicit shared resources.
3. Harden fail2ban client concurrency and packaging.
4. Convert setup guard to a safer startup-driven model.
5. Add deployment-safe configuration and production-ready CORS.
6. Add lifecycle and concurrency regression tests.