Refactor services and update documentation

- Refactor ban_service.py with improved error handling
- Refactor blocklist_service.py for better code organization
- Update geo_cache.py with performance improvements
- Update backend development guide and task documentation
- Update runner.csx script

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

backend/app/services/blocklist_service.py

@@ -21,7 +21,7 @@ from typing import TYPE_CHECKING
 import aiohttp
 import structlog
 
-from app.exceptions import JailNotFoundError
+from app.exceptions import JailNotFoundError, JailOperationError
 from app.models.blocklist import (
     BlocklistSource,
     ImportLogEntry,
@@ -39,7 +39,6 @@ from app.utils.ip_utils import is_valid_ip, is_valid_network
 if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable
 
-    import aiohttp
     import aiosqlite
     from apscheduler.schedulers.asyncio import AsyncIOScheduler
 
@@ -92,7 +91,7 @@ async def _download_text_with_retries(
                     await asyncio.sleep(backoff)
                     continue
                 return resp.status, text
-        except Exception as exc:  # noqa: BLE001
+        except (TimeoutError, aiohttp.ClientError) as exc:
             last_exception = exc
             if attempt >= _BLOCKLIST_HTTP_RETRY_ATTEMPTS:
                 raise
@@ -105,6 +104,20 @@ async def _download_text_with_retries(
                 backoff=backoff,
             )
             await asyncio.sleep(backoff)
+        except Exception as exc:
+            last_exception = exc
+            if attempt >= _BLOCKLIST_HTTP_RETRY_ATTEMPTS:
+                raise
+            backoff = _BLOCKLIST_HTTP_BACKOFF_BASE_SECONDS * (2 ** (attempt - 1))
+            log.warning(
+                "blocklist_download_retry_error",
+                url=url,
+                attempt=attempt,
+                error=repr(exc),
+                error_type="unexpected",
+                backoff=backoff,
+            )
+            await asyncio.sleep(backoff)
 
     assert last_exception is not None
     raise last_exception
@@ -281,8 +294,8 @@ async def preview_source(
         )
         if status != 200:
             raise ValueError(f"HTTP {status} from {url}")
-    except Exception as exc:
-        log.warning("blocklist_preview_failed", url=url, error=str(exc))
+    except (TimeoutError, aiohttp.ClientError, ValueError) as exc:
+        log.warning("blocklist_preview_failed", url=url, error=type(exc).__name__)
         raise ValueError(str(exc)) from exc
 
     lines = raw.splitlines()
@@ -363,7 +376,7 @@ async def import_source(
                 ips_skipped=0,
                 error=error_msg,
             )
-    except Exception as exc:
+    except (TimeoutError, aiohttp.ClientError) as exc:
         error_msg = str(exc)
         await _log_result(db, source, 0, 0, error_msg)
         log.warning("blocklist_import_download_error", url=source.url, error=error_msg)
@@ -407,7 +420,7 @@ async def import_source(
                 error=str(exc),
             )
             break
-        except Exception as exc:
+        except JailOperationError as exc:
             skipped += 1
             if ban_error is None:
                 ban_error = str(exc)
@@ -444,11 +457,10 @@ async def import_source(
                     source_id=source.id,
                     count=len(uncached_ips),
                 )
-            except Exception as exc:  # noqa: BLE001
+            except (TimeoutError, aiohttp.ClientError, OSError):
                 log.warning(
                     "blocklist_geo_prewarm_failed",
                     source_id=source.id,
-                    error=str(exc),
                 )
 
     return ImportSourceResult(
@@ -606,8 +618,8 @@ async def get_schedule(db: aiosqlite.Connection) -> ScheduleConfig:
     try:
         data = json.loads(raw)
         return ScheduleConfig.model_validate(data)
-    except Exception:
-        log.warning("blocklist_schedule_invalid", raw=raw)
+    except (json.JSONDecodeError, ValueError) as exc:
+        log.warning("blocklist_schedule_invalid", raw=raw, error=type(exc).__name__)
         return _DEFAULT_SCHEDULE