Lukas
bd6170722a
- Add _hits/_misses counters to GeoCache for cache hit/miss ratio tracking - Reset counters on clear() - Count hits before misses in lookup_batch() to avoid interleaving - Add synchronous prewarm() using asyncio.create_task for fire-and-forget - Add hits/misses fields to GeoCacheStatsResponse model - Add TestCacheMetrics (5 tests), TestPrewarm (3 tests), TestLargeBanList (2 tests) - Fix _make_async_db() mock: db.execute is not async, returns ctx manager - Move collections.abc to TYPE_CHECKING block (TC003) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
126 lines
4.0 KiB
Python
126 lines
4.0 KiB
Python
"""Geo and IP lookup Pydantic models.
|
|
|
|
Response models for the ``GET /api/geo/lookup/{ip}`` endpoint.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from collections.abc import Awaitable, Callable
|
|
from dataclasses import dataclass
|
|
from typing import TYPE_CHECKING
|
|
|
|
from pydantic import Field
|
|
|
|
from app.models.response import BanGuiBaseModel
|
|
|
|
if TYPE_CHECKING:
|
|
import aiohttp
|
|
import aiosqlite
|
|
|
|
class GeoDetail(BanGuiBaseModel):
|
|
"""Enriched geolocation data for an IP address.
|
|
|
|
Populated from the ip-api.com free API.
|
|
"""
|
|
|
|
country_code: str | None = Field(
|
|
default=None,
|
|
description="ISO 3166-1 alpha-2 country code.",
|
|
)
|
|
country_name: str | None = Field(
|
|
default=None,
|
|
description="Human-readable country name.",
|
|
)
|
|
asn: str | None = Field(
|
|
default=None,
|
|
description="Autonomous System Number (e.g. ``'AS3320'``).",
|
|
)
|
|
org: str | None = Field(
|
|
default=None,
|
|
description="Organisation associated with the ASN.",
|
|
)
|
|
|
|
class GeoCacheEntry(BanGuiBaseModel):
|
|
"""A single cached geolocation entry for an IP address.
|
|
|
|
Represents a row from the ``geo_cache`` table in the application database.
|
|
"""
|
|
|
|
ip: str = Field(..., description="IP address (IPv4 or IPv6).")
|
|
country_code: str | None = Field(
|
|
default=None,
|
|
description="ISO 3166-1 alpha-2 country code.",
|
|
)
|
|
country_name: str | None = Field(
|
|
default=None,
|
|
description="Human-readable country name.",
|
|
)
|
|
asn: str | None = Field(
|
|
default=None,
|
|
description="Autonomous System Number (e.g. ``'AS3320'``).",
|
|
)
|
|
org: str | None = Field(
|
|
default=None,
|
|
description="Organisation associated with the ASN.",
|
|
)
|
|
|
|
class GeoCacheStatsResponse(BanGuiBaseModel):
|
|
"""Response for ``GET /api/geo/stats``.
|
|
|
|
Exposes diagnostic counters of the geo cache subsystem so operators
|
|
can assess resolution health from the UI or CLI.
|
|
"""
|
|
|
|
cache_size: int = Field(..., description="Number of positive entries in the in-memory cache.")
|
|
unresolved: int = Field(..., description="Number of geo_cache rows with country_code IS NULL.")
|
|
neg_cache_size: int = Field(..., description="Number of entries in the in-memory negative cache.")
|
|
dirty_size: int = Field(..., description="Number of newly resolved entries not yet flushed to disk.")
|
|
hits: int = Field(default=0, description="Number of cache hits since last clear.")
|
|
misses: int = Field(default=0, description="Number of cache misses since last clear.")
|
|
|
|
class GeoReResolveResponse(BanGuiBaseModel):
|
|
"""Response for ``POST /api/geo/re-resolve``.
|
|
|
|
Reports how many previously unresolved IPs were retried and how many
|
|
gained a resolved country code after the re-resolve operation.
|
|
"""
|
|
|
|
resolved: int = Field(..., description="Number of IPs successfully resolved.")
|
|
total: int = Field(..., description="Number of IPs retried.")
|
|
|
|
class IpLookupResponse(BanGuiBaseModel):
|
|
"""Response for ``GET /api/geo/lookup/{ip}``.
|
|
|
|
Aggregates current ban status and geographical information for an IP.
|
|
"""
|
|
|
|
ip: str = Field(..., description="The queried IP address.")
|
|
currently_banned_in: list[str] = Field(
|
|
default_factory=list,
|
|
description="Names of jails where this IP is currently banned.",
|
|
)
|
|
geo: GeoDetail | None = Field(
|
|
default=None,
|
|
description="Enriched geographical and network information.",
|
|
)
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# shared service types
|
|
# ---------------------------------------------------------------------------
|
|
|
|
@dataclass
|
|
class GeoInfo:
|
|
"""Geo resolution result used throughout backend services."""
|
|
|
|
country_code: str | None
|
|
country_name: str | None
|
|
asn: str | None
|
|
org: str | None
|
|
|
|
GeoEnricher = Callable[[str], Awaitable[GeoInfo | None]]
|
|
GeoBatchLookup = Callable[
|
|
[list[str], "aiohttp.ClientSession", "aiosqlite.Connection | None"],
|
|
Awaitable[dict[str, GeoInfo]],
|
|
]
|
|
GeoCacheLookup = Callable[[list[str]], tuple[dict[str, GeoInfo], list[str]]]
|