BanGUI/backend/app/routers/jails.py

"""Jails router.

Provides CRUD and control operations for fail2ban jails:

* ``GET  /api/jails``                     — list all jails
* ``GET  /api/jails/{name}``              — full detail for one jail
* ``GET  /api/jails/{name}/banned``       — paginated currently-banned IPs for one jail
* ``POST /api/jails/{name}/start``        — start a jail
* ``POST /api/jails/{name}/stop``         — stop a jail
* ``POST /api/jails/{name}/idle``         — toggle idle mode
* ``POST /api/jails/{name}/reload``       — reload a single jail
* ``POST /api/jails/reload-all``          — reload every jail

* ``GET    /api/jails/{name}/ignoreip``   — ignore-list for a jail
* ``POST   /api/jails/{name}/ignoreip``   — add IP to ignore list
* ``DELETE /api/jails/{name}/ignoreip``   — remove IP from ignore list
* ``POST   /api/jails/{name}/ignoreself`` — toggle ignoreself option
"""

from __future__ import annotations

from typing import Annotated

from fastapi import APIRouter, Body, HTTPException, Path, Request, status

from app.dependencies import AuthDep
from app.models.ban import JailBannedIpsResponse
from app.models.jail import (
    IgnoreIpRequest,
    JailCommandResponse,
    JailDetailResponse,
    JailListResponse,
)
from app.services import jail_service
from app.services.jail_service import JailNotFoundError, JailOperationError
from app.utils.fail2ban_client import Fail2BanConnectionError

router: APIRouter = APIRouter(prefix="/api/jails", tags=["Jails"])

# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------

_NamePath = Annotated[str, Path(description="Jail name as configured in fail2ban.")]


def _not_found(name: str) -> HTTPException:
    """Return a 404 response for an unknown jail.

    Args:
        name: Jail name that was not found.

    Returns:
        :class:`fastapi.HTTPException` with status 404.
    """
    return HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail=f"Jail not found: {name!r}",
    )


def _bad_gateway(exc: Exception) -> HTTPException:
    """Return a 502 response when fail2ban is unreachable.

    Args:
        exc: The underlying connection error.

    Returns:
        :class:`fastapi.HTTPException` with status 502.
    """
    return HTTPException(
        status_code=status.HTTP_502_BAD_GATEWAY,
        detail=f"Cannot reach fail2ban: {exc}",
    )


def _conflict(message: str) -> HTTPException:
    """Return a 409 response for invalid jail state transitions.

    Args:
        message: Human-readable description of the conflict.

    Returns:
        :class:`fastapi.HTTPException` with status 409.
    """
    return HTTPException(
        status_code=status.HTTP_409_CONFLICT,
        detail=message,
    )


# ---------------------------------------------------------------------------
# Jail listing & detail
# ---------------------------------------------------------------------------


@router.get(
    "",
    response_model=JailListResponse,
    summary="List all active fail2ban jails",
)
async def get_jails(
    request: Request,
    _auth: AuthDep,
) -> JailListResponse:
    """Return a summary of every active fail2ban jail.

    Includes runtime metrics (currently banned, total bans, failures) and
    key configuration (find time, ban time, max retries, backend, idle state)
    for each jail.

    Args:
        request: Incoming request (used to access ``app.state``).
        _auth: Validated session — enforces authentication.

    Returns:
        :class:`~app.models.jail.JailListResponse` with all active jails.
    """
    socket_path: str = request.app.state.settings.fail2ban_socket
    try:
        return await jail_service.list_jails(socket_path)
    except Fail2BanConnectionError as exc:
        raise _bad_gateway(exc) from exc


@router.get(
    "/{name}",
    response_model=JailDetailResponse,
    summary="Return full detail for a single jail",
)
async def get_jail(
    request: Request,
    _auth: AuthDep,
    name: _NamePath,
) -> JailDetailResponse:
    """Return the complete configuration and runtime state for one jail.

    Includes log paths, fail regex and ignore regex patterns, date pattern,
    log encoding, attached action names, ban-time settings, and runtime
    counters.

    Args:
        request: Incoming request (used to access ``app.state``).
        _auth: Validated session — enforces authentication.
        name: Jail name.

    Returns:
        :class:`~app.models.jail.JailDetailResponse` with the full jail.

    Raises:
        HTTPException: 404 when the jail does not exist.
        HTTPException: 502 when fail2ban is unreachable.
    """
    socket_path: str = request.app.state.settings.fail2ban_socket
    try:
        return await jail_service.get_jail(socket_path, name)
    except JailNotFoundError:
        raise _not_found(name) from None
    except Fail2BanConnectionError as exc:
        raise _bad_gateway(exc) from exc


# ---------------------------------------------------------------------------
# Jail control commands
# ---------------------------------------------------------------------------


@router.post(
    "/reload-all",
    response_model=JailCommandResponse,
    summary="Reload all fail2ban jails",
)
async def reload_all_jails(
    request: Request,
    _auth: AuthDep,
) -> JailCommandResponse:
    """Reload every fail2ban jail to apply configuration changes.

    This command instructs fail2ban to re-read its configuration for all
    jails simultaneously.

    Args:
        request: Incoming request (used to access ``app.state``).
        _auth: Validated session — enforces authentication.

    Returns:
        :class:`~app.models.jail.JailCommandResponse` confirming the reload.

    Raises:
        HTTPException: 502 when fail2ban is unreachable.
        HTTPException: 409 when fail2ban reports the operation failed.
    """
    socket_path: str = request.app.state.settings.fail2ban_socket
    try:
        await jail_service.reload_all(socket_path)
        return JailCommandResponse(message="All jails reloaded successfully.", jail="*")
    except JailOperationError as exc:
        raise _conflict(str(exc)) from exc
    except Fail2BanConnectionError as exc:
        raise _bad_gateway(exc) from exc


@router.post(
    "/{name}/start",
    response_model=JailCommandResponse,
    summary="Start a stopped jail",
)
async def start_jail(
    request: Request,
    _auth: AuthDep,
    name: _NamePath,
) -> JailCommandResponse:
    """Start a fail2ban jail that is currently stopped.

    Args:
        request: Incoming request (used to access ``app.state``).
        _auth: Validated session — enforces authentication.
        name: Jail name.

    Returns:
        :class:`~app.models.jail.JailCommandResponse` confirming the start.

    Raises:
        HTTPException: 404 when the jail does not exist.
        HTTPException: 409 when fail2ban reports the operation failed.
        HTTPException: 502 when fail2ban is unreachable.
    """
    socket_path: str = request.app.state.settings.fail2ban_socket
    try:
        await jail_service.start_jail(socket_path, name)
        return JailCommandResponse(message=f"Jail {name!r} started.", jail=name)
    except JailNotFoundError:
        raise _not_found(name) from None
    except JailOperationError as exc:
        raise _conflict(str(exc)) from exc
    except Fail2BanConnectionError as exc:
        raise _bad_gateway(exc) from exc


@router.post(
    "/{name}/stop",
    response_model=JailCommandResponse,
    summary="Stop a running jail",
)
async def stop_jail(
    request: Request,
    _auth: AuthDep,
    name: _NamePath,
) -> JailCommandResponse:
    """Stop a running fail2ban jail.

    The jail will no longer monitor logs or issue new bans.  Existing bans
    may or may not be removed depending on fail2ban configuration.  If the
    jail is already stopped the request succeeds silently (idempotent).

    Args:
        request: Incoming request (used to access ``app.state``).
        _auth: Validated session — enforces authentication.
        name: Jail name.

    Returns:
        :class:`~app.models.jail.JailCommandResponse` confirming the stop.

    Raises:
        HTTPException: 409 when fail2ban reports the operation failed.
        HTTPException: 502 when fail2ban is unreachable.
    """
    socket_path: str = request.app.state.settings.fail2ban_socket
    try:
        await jail_service.stop_jail(socket_path, name)
        return JailCommandResponse(message=f"Jail {name!r} stopped.", jail=name)
    except JailOperationError as exc:
        raise _conflict(str(exc)) from exc
    except Fail2BanConnectionError as exc:
        raise _bad_gateway(exc) from exc


@router.post(
    "/{name}/idle",
    response_model=JailCommandResponse,
    summary="Toggle idle mode for a jail",
)
async def toggle_idle(
    request: Request,
    _auth: AuthDep,
    name: _NamePath,
    on: bool = Body(..., description="``true`` to enable idle, ``false`` to disable."),
) -> JailCommandResponse:
    """Enable or disable idle mode for a fail2ban jail.

    In idle mode the jail suspends log monitoring without fully stopping,
    preserving all existing bans.

    Args:
        request: Incoming request (used to access ``app.state``).
        _auth: Validated session — enforces authentication.
        name: Jail name.
        on: ``true`` to enable idle, ``false`` to disable.

    Returns:
        :class:`~app.models.jail.JailCommandResponse` confirming the change.

    Raises:
        HTTPException: 404 when the jail does not exist.
        HTTPException: 409 when fail2ban reports the operation failed.
        HTTPException: 502 when fail2ban is unreachable.
    """
    socket_path: str = request.app.state.settings.fail2ban_socket
    state_str = "on" if on else "off"
    try:
        await jail_service.set_idle(socket_path, name, on=on)
        return JailCommandResponse(
            message=f"Jail {name!r} idle mode turned {state_str}.",
            jail=name,
        )
    except JailNotFoundError:
        raise _not_found(name) from None
    except JailOperationError as exc:
        raise _conflict(str(exc)) from exc
    except Fail2BanConnectionError as exc:
        raise _bad_gateway(exc) from exc


@router.post(
    "/{name}/reload",
    response_model=JailCommandResponse,
    summary="Reload a single jail",
)
async def reload_jail(
    request: Request,
    _auth: AuthDep,
    name: _NamePath,
) -> JailCommandResponse:
    """Reload a single fail2ban jail to pick up configuration changes.

    Args:
        request: Incoming request (used to access ``app.state``).
        _auth: Validated session — enforces authentication.
        name: Jail name.

    Returns:
        :class:`~app.models.jail.JailCommandResponse` confirming the reload.

    Raises:
        HTTPException: 404 when the jail does not exist.
        HTTPException: 409 when fail2ban reports the operation failed.
        HTTPException: 502 when fail2ban is unreachable.
    """
    socket_path: str = request.app.state.settings.fail2ban_socket
    try:
        await jail_service.reload_jail(socket_path, name)
        return JailCommandResponse(message=f"Jail {name!r} reloaded.", jail=name)
    except JailNotFoundError:
        raise _not_found(name) from None
    except JailOperationError as exc:
        raise _conflict(str(exc)) from exc
    except Fail2BanConnectionError as exc:
        raise _bad_gateway(exc) from exc


# ---------------------------------------------------------------------------
# Ignore list (IP whitelist)
# ---------------------------------------------------------------------------


class _IgnoreSelfRequest(IgnoreIpRequest):
    """Request body for the ignoreself toggle endpoint.

    Inherits from :class:`~app.models.jail.IgnoreIpRequest` but overrides
    the ``ip`` field with a boolean ``on`` field.
    """


@router.get(
    "/{name}/ignoreip",
    response_model=list[str],
    summary="List the ignore IPs for a jail",
)
async def get_ignore_list(
    request: Request,
    _auth: AuthDep,
    name: _NamePath,
) -> list[str]:
    """Return the current ignore list (IP whitelist) for a fail2ban jail.

    Args:
        request: Incoming request (used to access ``app.state``).
        _auth: Validated session — enforces authentication.
        name: Jail name.

    Returns:
        List of IP addresses and CIDR networks on the ignore list.

    Raises:
        HTTPException: 404 when the jail does not exist.
        HTTPException: 502 when fail2ban is unreachable.
    """
    socket_path: str = request.app.state.settings.fail2ban_socket
    try:
        return await jail_service.get_ignore_list(socket_path, name)
    except JailNotFoundError:
        raise _not_found(name) from None
    except Fail2BanConnectionError as exc:
        raise _bad_gateway(exc) from exc


@router.post(
    "/{name}/ignoreip",
    status_code=status.HTTP_201_CREATED,
    response_model=JailCommandResponse,
    summary="Add an IP or network to the ignore list",
)
async def add_ignore_ip(
    request: Request,
    _auth: AuthDep,
    name: _NamePath,
    body: IgnoreIpRequest,
) -> JailCommandResponse:
    """Add an IP address or CIDR network to a jail's ignore list.

    IPs on the ignore list are never banned by that jail, even if they
    trigger the configured fail regex.

    Args:
        request: Incoming request (used to access ``app.state``).
        _auth: Validated session — enforces authentication.
        name: Jail name.
        body: Payload containing the IP or CIDR to add.

    Returns:
        :class:`~app.models.jail.JailCommandResponse` confirming the addition.

    Raises:
        HTTPException: 400 when the IP address or network is invalid.
        HTTPException: 404 when the jail does not exist.
        HTTPException: 409 when fail2ban reports the operation failed.
        HTTPException: 502 when fail2ban is unreachable.
    """
    socket_path: str = request.app.state.settings.fail2ban_socket
    try:
        await jail_service.add_ignore_ip(socket_path, name, body.ip)
        return JailCommandResponse(
            message=f"IP {body.ip!r} added to ignore list of jail {name!r}.",
            jail=name,
        )
    except ValueError as exc:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail=str(exc),
        ) from exc
    except JailNotFoundError:
        raise _not_found(name) from None
    except JailOperationError as exc:
        raise _conflict(str(exc)) from exc
    except Fail2BanConnectionError as exc:
        raise _bad_gateway(exc) from exc


@router.delete(
    "/{name}/ignoreip",
    response_model=JailCommandResponse,
    summary="Remove an IP or network from the ignore list",
)
async def del_ignore_ip(
    request: Request,
    _auth: AuthDep,
    name: _NamePath,
    body: IgnoreIpRequest,
) -> JailCommandResponse:
    """Remove an IP address or CIDR network from a jail's ignore list.

    Args:
        request: Incoming request (used to access ``app.state``).
        _auth: Validated session — enforces authentication.
        name: Jail name.
        body: Payload containing the IP or CIDR to remove.

    Returns:
        :class:`~app.models.jail.JailCommandResponse` confirming the removal.

    Raises:
        HTTPException: 404 when the jail does not exist.
        HTTPException: 409 when fail2ban reports the operation failed.
        HTTPException: 502 when fail2ban is unreachable.
    """
    socket_path: str = request.app.state.settings.fail2ban_socket
    try:
        await jail_service.del_ignore_ip(socket_path, name, body.ip)
        return JailCommandResponse(
            message=f"IP {body.ip!r} removed from ignore list of jail {name!r}.",
            jail=name,
        )
    except JailNotFoundError:
        raise _not_found(name) from None
    except JailOperationError as exc:
        raise _conflict(str(exc)) from exc
    except Fail2BanConnectionError as exc:
        raise _bad_gateway(exc) from exc


@router.post(
    "/{name}/ignoreself",
    response_model=JailCommandResponse,
    summary="Toggle the ignoreself option for a jail",
)
async def toggle_ignore_self(
    request: Request,
    _auth: AuthDep,
    name: _NamePath,
    on: bool = Body(..., description="``true`` to enable ignoreself, ``false`` to disable."),
) -> JailCommandResponse:
    """Toggle the ``ignoreself`` flag for a fail2ban jail.

    When ``ignoreself`` is enabled fail2ban automatically adds the server's
    own IP addresses to the ignore list so the host can never ban itself.

    Args:
        request: Incoming request (used to access ``app.state``).
        _auth: Validated session — enforces authentication.
        name: Jail name.
        on: ``true`` to enable, ``false`` to disable.

    Returns:
        :class:`~app.models.jail.JailCommandResponse` confirming the change.

    Raises:
        HTTPException: 404 when the jail does not exist.
        HTTPException: 409 when fail2ban reports the operation failed.
        HTTPException: 502 when fail2ban is unreachable.
    """
    socket_path: str = request.app.state.settings.fail2ban_socket
    state_str = "enabled" if on else "disabled"
    try:
        await jail_service.set_ignore_self(socket_path, name, on=on)
        return JailCommandResponse(
            message=f"ignoreself {state_str} for jail {name!r}.",
            jail=name,
        )
    except JailNotFoundError:
        raise _not_found(name) from None
    except JailOperationError as exc:
        raise _conflict(str(exc)) from exc
    except Fail2BanConnectionError as exc:
        raise _bad_gateway(exc) from exc


# ---------------------------------------------------------------------------
# Currently banned IPs (paginated)
# ---------------------------------------------------------------------------


@router.get(
    "/{name}/banned",
    response_model=JailBannedIpsResponse,
    summary="Return paginated currently-banned IPs for a single jail",
)
async def get_jail_banned_ips(
    request: Request,
    _auth: AuthDep,
    name: _NamePath,
    page: int = 1,
    page_size: int = 25,
    search: str | None = None,
) -> JailBannedIpsResponse:
    """Return a paginated list of IPs currently banned by a specific jail.

    The full ban list is fetched from the fail2ban socket, filtered by the
    optional *search* substring, sliced to the requested page, and then
    geo-enriched exclusively for that page slice.

    Args:
        request: Incoming request (used to access ``app.state``).
        _auth: Validated session — enforces authentication.
        name: Jail name.
        page: 1-based page number (default 1, min 1).
        page_size: Items per page (default 25, max 100).
        search: Optional case-insensitive substring filter on the IP address.

    Returns:
        :class:`~app.models.ban.JailBannedIpsResponse` with the paginated bans.

    Raises:
        HTTPException: 400 when *page* or *page_size* are out of range.
        HTTPException: 404 when the jail does not exist.
        HTTPException: 502 when fail2ban is unreachable.
    """
    if page < 1:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="page must be >= 1.",
        )
    if not (1 <= page_size <= 100):
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="page_size must be between 1 and 100.",
        )

    socket_path: str = request.app.state.settings.fail2ban_socket
    http_session = getattr(request.app.state, "http_session", None)
    app_db = getattr(request.app.state, "db", None)

    try:
        return await jail_service.get_jail_banned_ips(
            socket_path=socket_path,
            jail_name=name,
            page=page,
            page_size=page_size,
            search=search,
            http_session=http_session,
            app_db=app_db,
        )
    except JailNotFoundError:
        raise _not_found(name) from None
    except Fail2BanConnectionError as exc:
        raise _bad_gateway(exc) from exc