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

maxmind/maxmind.go

@@ -0,0 +1,186 @@
+// Package maxmind provides utilities for downloading and managing MaxMind GeoIP databases.
+//
+// This package handles downloading GeoIP databases from MaxMind's servers,
+// extracting them from compressed archives, and validating database editions.
+// It supports both commercial GeoIP2 and free GeoLite2 database editions.
+//
+// The implementation is based on the approach used in the Kubernetes ingress-nginx project.
+// See: https://github.com/kubernetes/ingress-nginx/pull/4896/files
+package maxmind
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path"
+	"strings"
+)
+
+// LicenseKey is the MaxMind license key required for downloading databases.
+// This must be set to a valid license key obtained from your MaxMind account
+// at https://www.maxmind.com/en/accounts/current/license-key
+var LicenseKey = ""
+
+// EditionIDs specifies which MaxMind database editions to download.
+// This should be a comma-separated list of valid edition names.
+// Examples: "GeoLite2-City,GeoLite2-Country" or "GeoIP2-ISP,GeoIP2-City"
+var EditionIDs = ""
+
+// EditionFiles contains the filenames of successfully downloaded database files.
+// This slice is automatically populated by DownloadGeoLite2DB and can be used
+// to verify which databases are available after download completion.
+var EditionFiles []string
+
+// Path specifies the target directory for storing downloaded MaxMind databases.
+// This should be set to a writable directory path. If empty, the current
+// working directory will be used as the default location.
+var Path string
+
+const (
+	dbExtension = ".mmdb"
+	maxmindURL  = "https://download.maxmind.com/app/geoip_download?license_key=%v&edition_id=%v&suffix=tar.gz"
+)
+
+// GeoLite2DBExists verifies that all required MaxMind databases exist on disk.
+//
+// It checks for the presence of each database specified in EditionIDs within
+// the Path directory. Returns true only if every specified database file is
+// found and accessible. This is useful for determining if downloads are needed.
+func GeoLite2DBExists() bool {
+	for _, dbName := range strings.Split(EditionIDs, ",") {
+		if !fileExists(path.Join(Path, dbName+dbExtension)) {
+			return false
+		}
+	}
+
+	return true
+}
+
+// DownloadGeoLite2DB downloads all databases specified in EditionIDs from MaxMind's servers.
+//
+// This function requires a valid LicenseKey to be set and will download each database
+// edition listed in EditionIDs. Successfully downloaded files are added to EditionFiles.
+// If any download fails, the function returns an error and stops processing remaining databases.
+func DownloadGeoLite2DB() error {
+	for _, dbName := range strings.Split(EditionIDs, ",") {
+		err := downloadDatabase(dbName)
+		if err != nil {
+			return err
+		}
+		EditionFiles = append(EditionFiles, dbName+dbExtension)
+	}
+	return nil
+}
+
+// downloadDatabase downloads and extracts a single MaxMind database by edition name.
+//
+// This function handles the complete download process: fetching the gzipped tar archive
+// from MaxMind's download API, extracting the .mmdb database file from the archive,
+// and saving it to the configured Path directory. The download URL includes the
+// license key for authentication.
+func downloadDatabase(dbName string) error {
+	url := fmt.Sprintf(maxmindURL, LicenseKey, dbName)
+	req, err := http.NewRequest(http.MethodGet, url, nil)
+	if err != nil {
+		return err
+	}
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return err
+	}
+
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("HTTP status %v", resp.Status)
+	}
+
+	archive, err := gzip.NewReader(resp.Body)
+	if err != nil {
+		return err
+	}
+	defer archive.Close()
+
+	mmdbFile := dbName + dbExtension
+
+	tarReader := tar.NewReader(archive)
+	for true {
+		header, err := tarReader.Next()
+		if err == io.EOF {
+			break
+		}
+
+		if err != nil {
+			return err
+		}
+
+		switch header.Typeflag {
+		case tar.TypeReg:
+			if !strings.HasSuffix(header.Name, mmdbFile) {
+				continue
+			}
+
+			outFile, err := os.Create(path.Join(Path, mmdbFile))
+			if err != nil {
+				return err
+			}
+
+			defer outFile.Close()
+
+			if _, err := io.Copy(outFile, tarReader); err != nil {
+				return err
+			}
+
+			return nil
+		}
+	}
+
+	return fmt.Errorf("the URL %v does not contains the database %v",
+		fmt.Sprintf(maxmindURL, "XXXXXXX", dbName), mmdbFile)
+}
+
+// ValidateGeoLite2DBEditions validates that all specified database editions are recognized.
+//
+// This function checks each edition name in EditionIDs against the list of known
+// MaxMind database editions, including both commercial GeoIP2 and free GeoLite2 variants.
+// Returns an error if any edition name is not recognized, helping catch typos
+// or outdated edition names before attempting downloads.
+func ValidateGeoLite2DBEditions() error {
+	allowedEditions := map[string]bool{
+		"GeoIP2-Anonymous-IP":    true,
+		"GeoIP2-Country":         true,
+		"GeoIP2-City":            true,
+		"GeoIP2-Connection-Type": true,
+		"GeoIP2-Domain":          true,
+		"GeoIP2-ISP":             true,
+		"GeoIP2-ASN":             true,
+		"GeoLite2-ASN":           true,
+		"GeoLite2-Country":       true,
+		"GeoLite2-City":          true,
+	}
+
+	for _, edition := range strings.Split(EditionIDs, ",") {
+		if !allowedEditions[edition] {
+			return fmt.Errorf("unknown Maxmind GeoIP2 edition name: '%s'", edition)
+		}
+	}
+	return nil
+}
+
+// fileExists is a utility function that checks if a regular file exists at the given path.
+//
+// Unlike a simple os.Stat check, this function specifically verifies that the path
+// points to a regular file (not a directory or other file type). Returns false
+// if the path doesn't exist, points to a directory, or encounters an error.
+func fileExists(filePath string) bool {
+	info, err := os.Stat(filePath)
+	if os.IsNotExist(err) {
+		return false
+	}
+
+	return !info.IsDir()
+}