Add GeoIP lookup for request originators

- Add geoip2 dependency for IP geolocation
- Create new geoip module with MaxMind GeoLite2 support
- Add originator_requests Prometheus metric to track requester locations
- Track originator location separately from requested weather locations
- Add tests for GeoIP functionality
- Gracefully handle missing GeoIP database (optional feature)

The new metric 'fingr_originator_requests_total' tracks where requests
come from geographically (based on IP), while 'fingr_location_requests_total'
tracks which locations people are requesting weather for. This allows
visualization of both on a map with different colors.

Author: GitHub Copilot

fingr/geoip.py

@@ -0,0 +1,81 @@
+"""GeoIP lookup for request originator locations."""
+
+from typing import Optional
+
+from .logging import get_logger
+
+logger = get_logger(__name__)
+
+# Global GeoIP reader (initialized in server startup)
+geoip_reader: Optional[object] = None
+
+
+def init_geoip() -> None:
+    """Initialize GeoIP reader with MaxMind database."""
+    global geoip_reader
+    try:
+        import geoip2.database
+
+        # Try to load GeoLite2-City database from common locations
+        database_paths = [
+            "/usr/share/GeoIP/GeoLite2-City.mmdb",
+            "/var/lib/GeoIP/GeoLite2-City.mmdb",
+            "./GeoLite2-City.mmdb",
+            "/etc/fingr/GeoLite2-City.mmdb",
+        ]
+
+        for db_path in database_paths:
+            try:
+                geoip_reader = geoip2.database.Reader(db_path)
+                logger.info("GeoIP database loaded", path=db_path)
+                return
+            except FileNotFoundError:
+                continue
+            except Exception as e:
+                logger.warning("Failed to load GeoIP database", path=db_path, error=str(e))
+
+        logger.warning(
+            "GeoIP database not found. Originator location tracking disabled. "
+            "Install GeoLite2-City.mmdb to enable."
+        )
+    except ImportError:
+        logger.warning("geoip2 library not available. Originator location tracking disabled.")
+
+
+def lookup_ip_location(ip_address: str) -> tuple[Optional[float], Optional[float], str]:
+    """
+    Lookup geographic location for an IP address.
+
+    Returns:
+        Tuple of (latitude, longitude, location_name)
+        Returns (None, None, "unknown") if lookup fails or database not available.
+    """
+    # Skip private/local IPs first (regardless of database availability)
+    if ip_address in ("127.0.0.1", "::1", "localhost") or ip_address.startswith("192.168."):
+        return None, None, "local"
+
+    if geoip_reader is None:
+        return None, None, "unknown"
+
+    try:
+        response = geoip_reader.city(ip_address)  # type: ignore[attr-defined]
+        lat = response.location.latitude
+        lon = response.location.longitude
+
+        # Build location name
+        parts = []
+        if response.city.name:
+            parts.append(response.city.name)
+        if response.country.name:
+            parts.append(response.country.name)
+
+        location_name = ", ".join(parts) if parts else "unknown"
+
+        logger.debug(
+            "GeoIP lookup successful", ip=ip_address, lat=lat, lon=lon, location=location_name
+        )
+        return lat, lon, location_name
+
+    except Exception as e:
+        logger.debug("GeoIP lookup failed", ip=ip_address, error=str(e))
+        return None, None, "unknown"

fingr/metrics.py

@@ -53,6 +53,12 @@
     ["latitude_bucket", "longitude_bucket", "address"],
 )
 
+originator_requests = Counter(
+    "fingr_originator_requests_total",
+    "Requests by originator geographic location",
+    ["latitude_bucket", "longitude_bucket", "location"],
+)
+
 # Processing time breakdown
 location_resolution_duration = Histogram(
     "fingr_location_resolution_duration_seconds",
@@ -101,3 +107,16 @@ def record_location_request(lat: float, lon: float, address: str) -> None:
         longitude_bucket=lon_bucket,
         address=address_short,
     ).inc()
+
+
+def record_originator_request(lat: float, lon: float, location: str) -> None:
+    """Record an originator request with bucketed coordinates."""
+    lat_bucket = bucket_coordinate(lat)
+    lon_bucket = bucket_coordinate(lon)
+    # Truncate location to avoid cardinality explosion
+    location_short = location[:50] if len(location) > 50 else location
+    originator_requests.labels(
+        latitude_bucket=lat_bucket,
+        longitude_bucket=lon_bucket,
+        location=location_short,
+    ).inc()

fingr/server.py

@@ -12,11 +12,13 @@
 
 from .config import load_deny_list, load_motd_list, load_user_agent, random_message
 from .formatting import format_meteogram, format_oneliner
+from .geoip import init_geoip, lookup_ip_location
 from .location import RedisClient, get_timezone, resolve_location
 from .logging import get_logger
 from .metrics import (
     formatting_duration,
     record_location_request,
+    record_originator_request,
     request_duration,
     requests_total,
     track_time,
@@ -100,6 +102,18 @@ async def handle_request(reader: asyncio.StreamReader, writer: asyncio.StreamWri
 
             logger.debug("Request received", ip=addr[0], input=user_input)
 
+            # Lookup originator location from IP
+            orig_lat, orig_lon, orig_location = lookup_ip_location(addr[0])
+            if orig_lat is not None and orig_lon is not None:
+                record_originator_request(orig_lat, orig_lon, orig_location)
+                logger.debug(
+                    "Originator location tracked",
+                    ip=addr[0],
+                    location=orig_location,
+                    lat=orig_lat,
+                    lon=orig_lon,
+                )
+
             # Deny list
             if addr[0] in denylist:
                 logger.info("Request from blacklisted IP", ip=addr[0], input=user_input)
@@ -225,6 +239,9 @@ async def start_server(args: argparse.Namespace) -> None:
     user_agent = load_user_agent()
     geolocator = Nominatim(user_agent=user_agent, timeout=3)
 
+    # Initialize GeoIP
+    init_geoip()
+
     # Connect to Redis with retry
     logger.info("Connecting to Redis", host=args.redis_host, port=args.redis_port)
     r = redis.Redis(host=args.redis_host, port=args.redis_port)

fingr_test.py

@@ -11,6 +11,7 @@
 
 from fingr.config import random_message
 from fingr.formatting import sun_up
+from fingr.geoip import lookup_ip_location
 from fingr.location import get_timezone, resolve_location
 from fingr.utils import clean_input, wind_direction
 
@@ -79,6 +80,28 @@ def test_sun_up(self):
         test = sun_up(latitude=59, longitude=11, date=dt)
         self.assertFalse(test)
 
+    def test_geoip_lookup_local(self):
+        """Test GeoIP lookup for local addresses"""
+        lat, lon, location = lookup_ip_location("127.0.0.1")
+        self.assertIsNone(lat)
+        self.assertIsNone(lon)
+        self.assertEqual(location, "local")
+
+    def test_geoip_lookup_private(self):
+        """Test GeoIP lookup for private addresses"""
+        lat, lon, location = lookup_ip_location("192.168.1.1")
+        self.assertIsNone(lat)
+        self.assertIsNone(lon)
+        self.assertEqual(location, "local")
+
+    def test_geoip_lookup_unknown(self):
+        """Test GeoIP lookup without database (returns unknown)"""
+        # When no database is loaded, should return unknown
+        lat, lon, location = lookup_ip_location("8.8.8.8")
+        # Will be None/unknown if database not available
+        # If database is available, will return actual location
+        self.assertTrue(location in ["unknown", "local"] or isinstance(location, str))
+
 
 if __name__ == "__main__":
     unittest.main()

pyproject.toml

@@ -33,6 +33,7 @@ dependencies = [
     "pytz==2024.2",
     "structlog>=24.1.0",
     "prometheus-client~=0.21.0",
+    "geoip2~=4.8.0",
 ]
 
 [project.optional-dependencies]