Refactor backend services and utilities

- Update service layer implementations
- Improve configuration handling utilities
- Update documentation tasks

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

backend/app/utils/config_file_utils.py

@@ -22,7 +22,7 @@ from app.models.config import (
     JailValidationIssue,
     JailValidationResult,
 )
-from app.utils.constants import FAIL2BAN_TRUTHY_VALUES
+from app.utils.constants import FAIL2BAN_SOCKET_TIMEOUT, FAIL2BAN_TRUTHY_VALUES
 from app.utils.fail2ban_client import (
     Fail2BanClient,
     Fail2BanConnectionError,
@@ -32,8 +32,6 @@ from app.utils.fail2ban_response import ok, to_dict
 
 log: structlog.stdlib.BoundLogger = structlog.get_logger()
 
-_SOCKET_TIMEOUT: float = 10.0
-
 # Allowlist pattern for jail names used in path construction.
 _SAFE_JAIL_NAME_RE: re.Pattern[str] = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
 
@@ -253,7 +251,7 @@ def _parse_jails_sync(
 async def _get_active_jail_names(socket_path: str) -> set[str]:
     """Fetch the set of currently running jail names from fail2ban."""
     try:
-        client = Fail2BanClient(socket_path=socket_path, timeout=_SOCKET_TIMEOUT)
+        client = Fail2BanClient(socket_path=socket_path, timeout=FAIL2BAN_SOCKET_TIMEOUT)
 
         status_raw = ok(await client.send(["status"]))
         status_dict = to_dict(status_raw)
@@ -272,7 +270,7 @@ async def _get_active_jail_names(socket_path: str) -> set[str]:
 async def _probe_fail2ban_running(socket_path: str) -> bool:
     """Return ``True`` when fail2ban responds successfully to a status request."""
     try:
-        client = Fail2BanClient(socket_path=socket_path, timeout=_SOCKET_TIMEOUT)
+        client = Fail2BanClient(socket_path=socket_path, timeout=FAIL2BAN_SOCKET_TIMEOUT)
         response = await client.send(["status"])
         code, _ = cast("Fail2BanResponse", response)
         return code == 0

backend/app/utils/constants.py

@@ -13,8 +13,11 @@ from typing import Final
 DEFAULT_FAIL2BAN_SOCKET: Final[str] = "/var/run/fail2ban/fail2ban.sock"
 """Default path to the fail2ban Unix domain socket."""
 
-FAIL2BAN_SOCKET_TIMEOUT_SECONDS: Final[float] = 5.0
-"""Maximum seconds to wait for a response from the fail2ban socket."""
+FAIL2BAN_SOCKET_TIMEOUT_FAST: Final[float] = 5.0
+"""Maximum seconds for fast operations (health checks, metadata probes)."""
+
+FAIL2BAN_SOCKET_TIMEOUT: Final[float] = 10.0
+"""Maximum seconds for command operations (config, jail management)."""
 
 FAIL2BAN_TRUTHY_VALUES: Final[frozenset[str]] = frozenset({"true", "yes", "1"})
 """String values treated as boolean true by fail2ban configuration parsers."""