refactor(backend): clean up jail service, add error handling service

- Extract jail status/processing to helper functions
- Add error_handling.py service for centralized error handling
- Update config.py with validation and defaults
- Update .env.example with all config options
- Remove obsolete Tasks.md, add Service-Development.md
- Minor fixes across routers and services

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

backend/app/services/jail_service.py

@@ -24,12 +24,11 @@ import structlog
 
 from app.exceptions import JailNotFoundError, JailOperationError
 from app.models.ban_domain import DomainActiveBan
-from app.models.config import BantimeEscalation
 from app.models.geo import GeoDetail, IpLookupResponse
 from app.models.jail_domain import (
-    DomainJailBannedIps,
     DomainBantimeEscalation,
     DomainJail,
+    DomainJailBannedIps,
     DomainJailDetail,
     DomainJailList,
     DomainJailStatus,
@@ -50,7 +49,6 @@ from app.utils.fail2ban_response import (
     to_dict,
 )
 from app.utils.jail_socket import reload_all
-from app.utils.pagination import create_pagination_metadata
 from app.utils.runtime_state import JailServiceState  # noqa: TC001
 
 if TYPE_CHECKING:
@@ -190,9 +188,8 @@ async def list_jails(socket_path: str, state: JailServiceState) -> DomainJailLis
     Returns:
         :class:`~app.models.jail_domain.DomainJailList` with all active jails.
 
-    Raises:
-        ~app.utils.fail2ban_client.Fail2BanConnectionError: If the socket
-            cannot be reached.
+    Error contract: ABORT_ON_ERROR. Raises Fail2BanConnectionError on socket
+    unreachable. Empty jail list is not an error — returns empty DomainJailList.
     """
     client = Fail2BanClient(socket_path=socket_path, timeout=FAIL2BAN_SOCKET_TIMEOUT)
 
@@ -344,10 +341,8 @@ async def get_jail(socket_path: str, name: str) -> DomainJailDetail:
     Returns:
         :class:`~app.models.jail_domain.DomainJailDetail` with the full jail.
 
-    Raises:
-        JailNotFoundError: If *name* is not a known jail.
-        ~app.utils.fail2ban_client.Fail2BanConnectionError: If the socket
-            cannot be reached.
+    Error contract: ABORT_ON_ERROR. Raises JailNotFoundError (404),
+    Fail2BanConnectionError (503).
     """
     client = Fail2BanClient(socket_path=socket_path, timeout=FAIL2BAN_SOCKET_TIMEOUT)
 
@@ -460,11 +455,8 @@ async def start_jail(socket_path: str, name: str) -> None:
         socket_path: Path to the fail2ban Unix domain socket.
         name: Jail name to start.
 
-    Raises:
-        JailNotFoundError: If *name* is not a known jail.
-        JailOperationError: If fail2ban reports the operation failed.
-        ~app.utils.fail2ban_client.Fail2BanConnectionError: If the socket
-            cannot be reached.
+    Error contract: ABORT_ON_ERROR. Raises JailNotFoundError (404),
+    JailOperationError (409), Fail2BanConnectionError (502).
     """
     client = Fail2BanClient(socket_path=socket_path, timeout=FAIL2BAN_SOCKET_TIMEOUT)
     try:
@@ -486,10 +478,8 @@ async def stop_jail(socket_path: str, name: str) -> None:
         socket_path: Path to the fail2ban Unix domain socket.
         name: Jail name to stop.
 
-    Raises:
-        JailOperationError: If fail2ban reports the operation failed.
-        ~app.utils.fail2ban_client.Fail2BanConnectionError: If the socket
-            cannot be reached.
+    Error contract: ABORT_ON_ERROR. Raises JailNotFoundError (404),
+    JailOperationError (409), Fail2BanConnectionError (502).
     """
     client = Fail2BanClient(socket_path=socket_path, timeout=FAIL2BAN_SOCKET_TIMEOUT)
     try:
@@ -514,11 +504,8 @@ async def set_idle(socket_path: str, name: str, *, on: bool) -> None:
         name: Jail name.
         on: Pass ``True`` to enable idle, ``False`` to disable it.
 
-    Raises:
-        JailNotFoundError: If *name* is not a known jail.
-        JailOperationError: If fail2ban reports the operation failed.
-        ~app.utils.fail2ban_client.Fail2BanConnectionError: If the socket
-            cannot be reached.
+    Error contract: ABORT_ON_ERROR. Raises JailNotFoundError (404),
+    JailOperationError (409), Fail2BanConnectionError (502).
     """
     state = "on" if on else "off"
     client = Fail2BanClient(socket_path=socket_path, timeout=FAIL2BAN_SOCKET_TIMEOUT)
@@ -545,11 +532,8 @@ async def reload_jail(socket_path: str, name: str) -> None:
         socket_path: Path to the fail2ban Unix domain socket.
         name: Jail name to reload.
 
-    Raises:
-        JailNotFoundError: If *name* is not a known jail.
-        JailOperationError: If fail2ban reports the operation failed.
-        ~app.utils.fail2ban_client.Fail2BanConnectionError: If the socket
-            cannot be reached.
+    Error contract: ABORT_ON_ERROR. Raises JailNotFoundError (404),
+    JailOperationError (409), Fail2BanConnectionError (502).
     """
     client = Fail2BanClient(socket_path=socket_path, timeout=FAIL2BAN_SOCKET_TIMEOUT)
     try:
@@ -879,10 +863,8 @@ async def get_ignore_list(socket_path: str, name: str) -> list[str]:
     Returns:
         List of IP addresses and CIDR networks on the jail's ignore list.
 
-    Raises:
-        JailNotFoundError: If *name* is not a known jail.
-        ~app.utils.fail2ban_client.Fail2BanConnectionError: If the socket
-            cannot be reached.
+    Error contract: ABORT_ON_ERROR. Raises JailNotFoundError (404),
+    Fail2BanConnectionError (503).
     """
     client = Fail2BanClient(socket_path=socket_path, timeout=FAIL2BAN_SOCKET_TIMEOUT)
     try:
@@ -932,11 +914,8 @@ async def del_ignore_ip(socket_path: str, name: str, ip: str) -> None:
         name: Jail name.
         ip: IP address or CIDR network to remove.
 
-    Raises:
-        JailNotFoundError: If *name* is not a known jail.
-        JailOperationError: If fail2ban reports the operation failed.
-        ~app.utils.fail2ban_client.Fail2BanConnectionError: If the socket
-            cannot be reached.
+    Error contract: ABORT_ON_ERROR. Raises JailNotFoundError (404),
+    JailOperationError (409), Fail2BanConnectionError (503).
     """
     client = Fail2BanClient(socket_path=socket_path, timeout=FAIL2BAN_SOCKET_TIMEOUT)
     try:
@@ -958,10 +937,8 @@ async def get_ignore_self(socket_path: str, name: str) -> bool:
     Returns:
         ``True`` when ``ignoreself`` is enabled for the jail.
 
-    Raises:
-        JailNotFoundError: If *name* is not a known jail.
-        ~app.utils.fail2ban_client.Fail2BanConnectionError: If the socket
-            cannot be reached.
+    Error contract: ABORT_ON_ERROR. Raises JailNotFoundError (404),
+    Fail2BanConnectionError (503).
     """
     client = Fail2BanClient(socket_path=socket_path, timeout=FAIL2BAN_SOCKET_TIMEOUT)
     try:
@@ -981,11 +958,8 @@ async def set_ignore_self(socket_path: str, name: str, *, on: bool) -> None:
         name: Jail name.
         on: ``True`` to enable ignoreself, ``False`` to disable.
 
-    Raises:
-        JailNotFoundError: If *name* is not a known jail.
-        JailOperationError: If fail2ban reports the operation failed.
-        ~app.utils.fail2ban_client.Fail2BanConnectionError: If the socket
-            cannot be reached.
+    Error contract: ABORT_ON_ERROR. Raises JailNotFoundError (404),
+    JailOperationError (409), Fail2BanConnectionError (503).
     """
     value = "true" if on else "false"
     client = Fail2BanClient(socket_path=socket_path, timeout=FAIL2BAN_SOCKET_TIMEOUT)