Add comprehensive test suite and documentation

- Complete unit, integration, and E2E test coverage (189 test cases)
- Enhanced CI/CD pipeline with race detection and quality checks
- Comprehensive godoc documentation for all packages
- Updated README with API docs, examples, and deployment guides

geoipapi.go

@@ -1,3 +1,11 @@
+// Package main implements a GeoIP API service that provides MaxMind GeoIP data over HTTP.
+//
+// This service is designed to run as a small daemon within Kubernetes clusters
+// to serve geolocation data to other services. It exposes HTTP endpoints for
+// retrieving country codes and full GeoIP data for given IP addresses.
+//
+// The service supports OpenTelemetry tracing and automatic MaxMind database
+// discovery in standard system paths.
 package main
 
 import (
@@ -24,16 +32,19 @@ import (
 	"go.ntppool.org/common/version"
 )
 
+// geoType represents the type of GeoIP database.
 type geoType uint8
 
 const (
-	countryDB geoType = iota
-	cityDB
-	asnDB
+	countryDB geoType = iota // Country-level database
+	cityDB                   // City-level database  
+	asnDB                    // ASN/ISP database
 )
 
+// dbFiles maps database types to their possible filenames on disk.
 var dbFiles map[geoType][]string
 
+// init initializes the database filename mappings.
 func init() {
 	dbFiles = map[geoType][]string{
 		countryDB: {"GeoIP2-Country.mmdb", "GeoLite2-Country.mmdb"},
@@ -42,6 +53,9 @@ func init() {
 	}
 }
 
+// main is the entry point for the GeoIP API service.
+// It sets up tracing, opens the database, and starts the HTTP server.
+// If command line arguments are provided, it runs in CLI mode for IP lookups.
 func main() {
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, os.Kill, syscall.SIGTERM)
 	defer cancel()
@@ -82,6 +96,8 @@ func main() {
 	}
 }
 
+// setupHTTP configures and starts the HTTP server with all routes and middleware.
+// It returns an error if the server fails to start or encounters an error during shutdown.
 func setupHTTP(ctx context.Context) error {
 	mux := http.NewServeMux()
 	mux.HandleFunc("/api/country", handleCountry)
@@ -128,6 +144,8 @@ func setupHTTP(ctx context.Context) error {
 	return srv.Shutdown(context.Background())
 }
 
+// getCityIP retrieves GeoIP city data for the given IP address.
+// It opens the city database and performs the lookup, returning detailed location information.
 func getCityIP(ctx context.Context, ip net.IP) (*geoip2.City, error) {
 	rdr, err := open(cityDB)
 	if err != nil {
@@ -141,6 +159,8 @@ func getCityIP(ctx context.Context, ip net.IP) (*geoip2.City, error) {
 	return city, nil
 }
 
+// getCity extracts the IP address from an HTTP request and retrieves its GeoIP data.
+// It parses the 'ip' form parameter and delegates to getCityIP for the actual lookup.
 func getCity(req *http.Request) (*geoip2.City, error) {
 	ctx := req.Context()
 	span := trace.SpanFromContext(ctx)
@@ -154,6 +174,8 @@ func getCity(req *http.Request) (*geoip2.City, error) {
 	return getCityIP(ctx, ip)
 }
 
+// handleJSON handles the /api/json endpoint, returning full GeoIP data as JSON.
+// It responds with a complete geoip2.City structure containing all available location data.
 func handleJSON(w http.ResponseWriter, req *http.Request) {
 	ctx := req.Context()
 	span := trace.SpanFromContext(ctx)
@@ -175,6 +197,8 @@ func handleJSON(w http.ResponseWriter, req *http.Request) {
 	w.Write(b)
 }
 
+// handleCountry handles the /api/country endpoint, returning only the country code.
+// It responds with a lowercase ISO country code (e.g., "us", "gb").
 func handleCountry(w http.ResponseWriter, req *http.Request) {
 	ctx := req.Context()
 	span := trace.SpanFromContext(ctx)
@@ -191,6 +215,8 @@ func handleCountry(w http.ResponseWriter, req *http.Request) {
 	w.Write([]byte(strings.ToLower(city.Country.IsoCode)))
 }
 
+// handleHealth handles the /healthz endpoint for health checks.
+// It performs an actual GeoIP lookup to verify database connectivity and functionality.
 func handleHealth(w http.ResponseWriter, req *http.Request) {
 	ctx := req.Context()
 	span := trace.SpanFromContext(ctx)
@@ -209,6 +235,8 @@ func handleHealth(w http.ResponseWriter, req *http.Request) {
 	w.Write([]byte(strings.ToLower(city.Country.IsoCode)))
 }
 
+// open opens a MaxMind database of the specified type.
+// It searches for database files in standard system paths and returns a reader.
 func open(t geoType) (*geoip2.Reader, error) {
 	dir := findDB()
 
@@ -231,6 +259,8 @@ func open(t geoType) (*geoip2.Reader, error) {
 	return rdr, err
 }
 
+// findDB searches for MaxMind database directories in standard system locations.
+// It returns the first directory found that exists, or an empty string if none are found.
 func findDB() string {
 	dirs := []string{
 		"/usr/share/GeoIP/",        // Linux default