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,169 @@
+// 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 used to download databases.
+// This must be set to a valid license key obtained from MaxMind.
+var LicenseKey = ""
+
+// EditionIDs is a comma-separated list of MaxMind database editions to download.
+// Examples: "GeoLite2-City,GeoLite2-Country" or "GeoIP2-ISP".
+var EditionIDs = ""
+
+// EditionFiles contains the list of database files that have been downloaded.
+// This slice is populated by DownloadGeoLite2DB after successful downloads.
+var EditionFiles []string
+
+// Path specifies the directory where MaxMind databases should be stored.
+// If empty, a default system path will be used.
+var Path string
+
+const (
+	dbExtension = ".mmdb"
+	maxmindURL  = "https://download.maxmind.com/app/geoip_download?license_key=%v&edition_id=%v&suffix=tar.gz"
+)
+
+// GeoLite2DBExists checks if all required MaxMind databases exist in the filesystem.
+// It verifies that all databases specified in EditionIDs are present in the Path directory.
+// Returns true only if all specified databases are found.
+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.
+// It requires a valid LicenseKey and updates EditionFiles with successfully downloaded files.
+// Returns an error if any download fails.
+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 a single MaxMind database by name.
+// It fetches the database archive from MaxMind, extracts the .mmdb file,
+// and saves it to the specified Path directory.
+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.
+// It checks each edition in EditionIDs against a list of known MaxMind database editions.
+// Returns an error if any unknown edition names are found.
+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 checks if a file exists at the given path and is not a directory.
+// It returns true only if the path points to an existing regular file.
+func fileExists(filePath string) bool {
+	info, err := os.Stat(filePath)
+	if os.IsNotExist(err) {
+		return false
+	}
+
+	return !info.IsDir()
+}