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,22 @@ import (
 	"go.ntppool.org/common/version"
 )
 
+// geoType represents the type of MaxMind GeoIP database being accessed.
+// Each type corresponds to different levels of geographical detail.
 type geoType uint8
 
 const (
-	countryDB geoType = iota
-	cityDB
-	asnDB
+	countryDB geoType = iota // Country-level database (GeoIP2-Country, GeoLite2-Country)
+	cityDB                   // City-level database with detailed location data (GeoIP2-City, GeoLite2-City)
+	asnDB                    // ASN/ISP database for network provider information (GeoIP2-ISP)
 )
 
+// dbFiles maps each geoType to the possible MaxMind database filenames.
+// The system searches for these files in order of preference.
 var dbFiles map[geoType][]string
 
+// init initializes the mapping between database types and their corresponding
+// MaxMind database filenames, supporting both commercial and free editions.
 func init() {
 	dbFiles = map[geoType][]string{
 		countryDB: {"GeoIP2-Country.mmdb", "GeoLite2-Country.mmdb"},
@@ -42,6 +56,14 @@ func init() {
 	}
 }
 
+// main is the entry point for the GeoIP API service.
+//
+// When run without arguments, it starts an HTTP server on port 8009 that provides
+// GeoIP lookup endpoints. When run with IP addresses as arguments, it operates
+// in CLI mode and outputs country codes for each provided IP.
+//
+// The service automatically sets up OpenTelemetry tracing and searches for
+// MaxMind databases in standard system locations.
 func main() {
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, os.Kill, syscall.SIGTERM)
 	defer cancel()
@@ -82,6 +104,15 @@ func main() {
 	}
 }
 
+// setupHTTP configures and starts the HTTP server with all routes and middleware.
+//
+// The server listens on port 8009 and provides three endpoints:
+//   - /api/country?ip=X.X.X.X - returns ISO country code
+//   - /api/json?ip=X.X.X.X - returns full GeoIP data as JSON
+//   - /healthz - health check with actual database lookup
+//
+// The server includes OpenTelemetry tracing (excluding health checks),
+// version headers, and graceful shutdown support.
 func setupHTTP(ctx context.Context) error {
 	mux := http.NewServeMux()
 	mux.HandleFunc("/api/country", handleCountry)
@@ -128,6 +159,12 @@ func setupHTTP(ctx context.Context) error {
 	return srv.Shutdown(context.Background())
 }
 
+// getCityIP retrieves comprehensive GeoIP city data for the given IP address.
+//
+// This function opens a MaxMind city database and performs a lookup to get
+// detailed location information including country, city, coordinates, and
+// administrative divisions. It logs warnings for lookup failures but returns
+// a generic error message to avoid exposing internal details.
 func getCityIP(ctx context.Context, ip net.IP) (*geoip2.City, error) {
 	rdr, err := open(cityDB)
 	if err != nil {
@@ -141,6 +178,11 @@ func getCityIP(ctx context.Context, ip net.IP) (*geoip2.City, error) {
 	return city, nil
 }
 
+// getCity extracts an IP address from an HTTP request and retrieves its GeoIP data.
+//
+// It parses the 'ip' query parameter, validates it as a valid IP address,
+// and adds tracing attributes before delegating to getCityIP for the database lookup.
+// Returns an error if the IP parameter is missing or invalid.
 func getCity(req *http.Request) (*geoip2.City, error) {
 	ctx := req.Context()
 	span := trace.SpanFromContext(ctx)
@@ -154,6 +196,12 @@ func getCity(req *http.Request) (*geoip2.City, error) {
 	return getCityIP(ctx, ip)
 }
 
+// handleJSON handles the /api/json endpoint, returning comprehensive GeoIP data as JSON.
+//
+// This endpoint provides the complete geoip2.City structure with all available
+// location information including country, subdivisions, city, postal code,
+// coordinates, and timezone data. The response is the raw MaxMind data structure
+// serialized to JSON.
 func handleJSON(w http.ResponseWriter, req *http.Request) {
 	ctx := req.Context()
 	span := trace.SpanFromContext(ctx)
@@ -175,6 +223,11 @@ func handleJSON(w http.ResponseWriter, req *http.Request) {
 	w.Write(b)
 }
 
+// handleCountry handles the /api/country endpoint, returning only the ISO country code.
+//
+// This endpoint provides a lightweight response containing just the two-letter
+// ISO 3166-1 alpha-2 country code in lowercase format (e.g., "us", "gb", "ca").
+// This is ideal for applications that only need basic country-level geolocation.
 func handleCountry(w http.ResponseWriter, req *http.Request) {
 	ctx := req.Context()
 	span := trace.SpanFromContext(ctx)
@@ -191,6 +244,12 @@ func handleCountry(w http.ResponseWriter, req *http.Request) {
 	w.Write([]byte(strings.ToLower(city.Country.IsoCode)))
 }
 
+// handleHealth handles the /healthz endpoint for Kubernetes-style health checks.
+//
+// Unlike a simple "OK" response, this endpoint performs an actual GeoIP lookup
+// against a known IP address (199.43.0.43) to verify that the MaxMind database
+// is accessible and functional. This provides a more meaningful health check
+// that can detect database corruption or missing files.
 func handleHealth(w http.ResponseWriter, req *http.Request) {
 	ctx := req.Context()
 	span := trace.SpanFromContext(ctx)
@@ -209,6 +268,11 @@ 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 and returns a reader.
+//
+// It searches through the standard system database directories and looks for
+// the appropriate database files based on the geoType. Returns an error if
+// no suitable database file is found in any of the searched locations.
 func open(t geoType) (*geoip2.Reader, error) {
 	dir := findDB()
 
@@ -231,6 +295,15 @@ func open(t geoType) (*geoip2.Reader, error) {
 	return rdr, err
 }
 
+// findDB searches for MaxMind database directories in standard system locations.
+//
+// It checks common installation paths used by package managers and manual installs:
+//   - /usr/share/GeoIP/ (Linux distributions)
+//   - /usr/local/share/GeoIP/ (FreeBSD, source installs)
+//   - /opt/local/share/GeoIP/ (MacPorts)
+//   - /opt/homebrew/var/GeoIP/ (Homebrew on Apple Silicon)
+//
+// Returns the first existing directory found, or empty string if none exist.
 func findDB() string {
 	dirs := []string{
 		"/usr/share/GeoIP/",        // Linux default