Lukas
1c673d600c
This commit standardizes how API responses are wrapped, solving issue #24. Problem: - Inconsistent response envelopes (jails vs items vs bans vs no wrapper) - Frontend required multiple field name variants - Integration bugs from branching logic - No clear pattern for different response types Solution: - Created response.py with base classes: PaginatedListResponse, CollectionResponse, CommandResponse - Standardized all list/collection responses to use 'items' field - Domain-specific field names for detail and aggregation responses - Updated all backends routers and mappers - Updated frontend types and hooks to match Changes: Backend: - backend/app/models/response.py (new): Base response models - backend/app/models/ban.py: Updated responses to inherit from bases - backend/app/models/jail.py: Updated JailListResponse, JailCommandResponse - backend/app/models/config.py: Updated collection responses - backend/app/services/jail_service.py: Updated return statements - backend/app/mappers/ban_mappers.py: Updated 'bans' to 'items' - backend/tests/test_mappers/test_ban_mappers.py: Updated tests Frontend: - frontend/src/types/jail.ts: Updated response interfaces - frontend/src/types/config.ts: Updated response interfaces - frontend/src/hooks/useActiveBans.ts: Updated selector - frontend/src/hooks/useJailList.ts: Updated selector - frontend/src/hooks/useJailConfigs.ts: Updated selector - frontend/src/hooks/useConfigActiveStatus.ts: Updated field access - frontend/src/hooks/useJailAdmin.ts: Updated field access Documentation: - Docs/Backend-Development.md: Added § 4.1 API Response Envelope Policy The policy defines: 1. Paginated lists use PaginatedListResponse (items, total, page, page_size) 2. Non-paginated collections use CollectionResponse (items, total) 3. Detail responses use entity-specific field names (jail, status, settings) 4. Command responses use CommandResponse (message, success, optional target) 5. Aggregations use domain-specific fields (jails, countries, buckets, bans) All responses now follow one of these patterns, reducing frontend complexity. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
98 lines
3.5 KiB
Python
98 lines
3.5 KiB
Python
"""Jail management Pydantic models.
|
|
|
|
Request, response, and domain models used by the jails router and service.
|
|
"""
|
|
|
|
from pydantic import BaseModel, ConfigDict, Field
|
|
|
|
from app.models.config import BantimeEscalation
|
|
from app.models.response import CommandResponse, CollectionResponse
|
|
|
|
|
|
class JailStatus(BaseModel):
|
|
"""Runtime metrics for a single jail."""
|
|
|
|
model_config = ConfigDict(strict=True)
|
|
|
|
currently_banned: int = Field(..., ge=0)
|
|
total_banned: int = Field(..., ge=0)
|
|
currently_failed: int = Field(..., ge=0)
|
|
total_failed: int = Field(..., ge=0)
|
|
|
|
|
|
class Jail(BaseModel):
|
|
"""Domain model for a single fail2ban jail with its full configuration."""
|
|
|
|
model_config = ConfigDict(strict=True)
|
|
|
|
name: str = Field(..., description="Jail name as configured in fail2ban.")
|
|
enabled: bool = Field(..., description="Whether the jail is currently active.")
|
|
running: bool = Field(..., description="Whether the jail backend is running.")
|
|
idle: bool = Field(default=False, description="Whether the jail is in idle mode.")
|
|
backend: str = Field(..., description="Log monitoring backend (e.g. polling, systemd).")
|
|
log_paths: list[str] = Field(default_factory=list, description="Monitored log files.")
|
|
fail_regex: list[str] = Field(default_factory=list, description="Failure detection regex patterns.")
|
|
ignore_regex: list[str] = Field(default_factory=list, description="Regex patterns that bypass the ban logic.")
|
|
ignore_ips: list[str] = Field(default_factory=list, description="IP addresses or CIDRs on the ignore list.")
|
|
date_pattern: str | None = Field(default=None, description="Custom date pattern for log parsing.")
|
|
log_encoding: str = Field(default="UTF-8", description="Log file encoding.")
|
|
find_time: int = Field(..., description="Time window (seconds) for counting failures.")
|
|
ban_time: int = Field(..., description="Duration (seconds) of a ban. -1 means permanent.")
|
|
max_retry: int = Field(..., description="Number of failures before a ban is issued.")
|
|
actions: list[str] = Field(default_factory=list, description="Names of actions attached to this jail.")
|
|
bantime_escalation: BantimeEscalation | None = Field(
|
|
default=None,
|
|
description="Incremental ban-time escalation settings, or None if not configured.",
|
|
)
|
|
status: JailStatus | None = Field(default=None, description="Runtime counters.")
|
|
|
|
|
|
class JailSummary(BaseModel):
|
|
"""Lightweight jail entry for the overview list."""
|
|
|
|
model_config = ConfigDict(strict=True)
|
|
|
|
name: str
|
|
enabled: bool
|
|
running: bool
|
|
idle: bool
|
|
backend: str
|
|
find_time: int
|
|
ban_time: int
|
|
max_retry: int
|
|
status: JailStatus | None = None
|
|
|
|
|
|
class JailListResponse(CollectionResponse[JailSummary]):
|
|
"""Response for ``GET /api/jails``.
|
|
|
|
Returns a non-paginated collection of jail summaries with their current status.
|
|
"""
|
|
|
|
pass
|
|
|
|
|
|
class JailDetailResponse(BaseModel):
|
|
"""Response for ``GET /api/jails/{name}``."""
|
|
|
|
model_config = ConfigDict(strict=True)
|
|
|
|
jail: Jail
|
|
|
|
|
|
class JailCommandResponse(CommandResponse):
|
|
"""Generic response for jail control commands (start, stop, reload, idle).
|
|
|
|
Extends the base CommandResponse with a jail field to identify the target.
|
|
"""
|
|
|
|
jail: str = Field(..., description="Target jail name, or '*' for operations on all jails.")
|
|
|
|
|
|
class IgnoreIpRequest(BaseModel):
|
|
"""Payload for adding an IP or network to a jail's ignore list."""
|
|
|
|
model_config = ConfigDict(strict=True)
|
|
|
|
ip: str = Field(..., description="IP address or CIDR network to ignore.")
|