Add GeoIP support for unique IP aggregation

- Introduced GeoIP configuration options in config.example.yaml to enable geolocation lookups for the /api/agg/unique-ips endpoint.
- Updated the aggregate handler to include optional GeoIP data in responses, enriching unique IP information with country and city details, as well as ASN data if available.
- Enhanced documentation in AGGREGATE.md and README.md to reflect the new GeoIP functionality and its usage.
- Added a dependency on the geoip2-golang library in go.mod for GeoIP lookups.
- Modified tests to accommodate the new GeoIP integration in the aggregate handler.

internal/aggregate/handlers.go

@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"github.com/telemt/telemt-api/internal/config"
+	"github.com/telemt/telemt-api/internal/geoip"
 )
 
 const pathPrefix = "/api/agg"
@@ -17,11 +18,13 @@ const pathPrefix = "/api/agg"
 type Handler struct {
 	Parsed *config.Parsed
 	Client *http.Client
+	Geo    *geoip.Service
 }
 
 // NewHandler builds an aggregate handler; client must use a non-nil Transport (e.g. gateway shared transport).
-func NewHandler(p *config.Parsed, client *http.Client) *Handler {
-	return &Handler{Parsed: p, Client: client}
+// Geo may be nil (no GeoLite2 lookups).
+func NewHandler(p *config.Parsed, client *http.Client, geo *geoip.Service) *Handler {
+	return &Handler{Parsed: p, Client: client, Geo: geo}
 }
 
 func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
@@ -154,6 +157,9 @@ func (h *Handler) handleUniqueIPs(w http.ResponseWriter, r *http.Request) {
 	defer cancel()
 	results := FetchStatsUsers(ctx, h.Client, h.Parsed, aliases)
 	data := BuildUniqueIPs(results)
+	if h.Geo != nil && !strings.EqualFold(r.URL.Query().Get("geo"), "false") {
+		EnrichUniqueIPsGeo(data, h.Geo)
+	}
 	writeOK(w, data)
 }