Add documentation for geoip2 functions

abh · Feb 13, 2018 · 1756034 · 1756034
1 parent 4a7a819
commit 1756034
Showing 1 changed file with 23 additions and 11 deletions.
diff --git a/targeting/geoip2/geoip2.go b/targeting/geoip2/geoip2.go
@@ -24,7 +24,9 @@ const (
 
 var dbFiles map[geoType][]string
 
-type g2 struct {
+// GeoIP2 contains the geoip implementation of the GeoDNS geo
+// targeting interface
+type GeoIP2 struct {
  dir string
 
  country *geoip2.Reader
@@ -41,6 +43,7 @@ func init() {
  }
 }
 
+// FindDB returns a guess at a directory path for GeoIP data files
 func FindDB() string {
  dirs := []string{
  "/usr/share/GeoIP/", // Linux default
@@ -60,7 +63,7 @@ func FindDB() string {
  return ""
 }
 
-func (g *g2) open(t geoType, db string) (*geoip2.Reader, error) {
+func (g *GeoIP2) open(t geoType, db string) (*geoip2.Reader, error) {
 
  fileName := filepath.Join(g.dir, db)
 
@@ -96,7 +99,7 @@ func (g *g2) open(t geoType, db string) (*geoip2.Reader, error) {
  return n, nil
 }
 
-func (g *g2) get(t geoType, db string) (*geoip2.Reader, error) {
+func (g *GeoIP2) get(t geoType, db string) (*geoip2.Reader, error) {
  g.mu.RLock()
 
  var r *geoip2.Reader
@@ -120,8 +123,9 @@ func (g *g2) get(t geoType, db string) (*geoip2.Reader, error) {
  return g.open(t, db)
 }
 
-func New(dir string) (*g2, error) {
- g := &g2{
+// New returns a new GeoIP2 provider
+func New(dir string) (*GeoIP2, error) {
+ g := &GeoIP2{
  dir: dir,
  }
  _, err := g.open(countryDB, "GeoIP2-Country.mmdb")
@@ -132,15 +136,18 @@ func New(dir string) (*g2, error) {
  return g, nil
 }
 
-func (g *g2) HasASN() (bool, error) {
+// HasASN returns if we can do ASN lookups
+func (g *GeoIP2) HasASN() (bool, error) {
  r, err := g.get(asnDB, "GeoIP2-ASN.mmdb")
  if r != nil && err == nil {
  return true, nil
  }
  return false, err
 }
 
-func (g *g2) GetASN(ip net.IP) (string, int, error) {
+// GetASN returns the ASN for the IP (as a "as123" string and
+// an integer)
+func (g *GeoIP2) GetASN(ip net.IP) (string, int, error) {
  r, err := g.get(asnDB, "GeoIP2-ASN.mmdb")
  if err != nil {
  return "", 0, err
@@ -154,15 +161,17 @@ func (g *g2) GetASN(ip net.IP) (string, int, error) {
  return fmt.Sprintf("as%d", asn), 0, nil
 }
 
-func (g *g2) HasCountry() (bool, error) {
+// HasCountry checks if the GeoIP country database is available
+func (g *GeoIP2) HasCountry() (bool, error) {
  r, err := g.get(countryDB, "GeoIP2-Country.mmdb")
  if r != nil && err == nil {
  return true, nil
  }
  return false, err
 }
 
-func (g *g2) GetCountry(ip net.IP) (country, continent string, netmask int) {
+// GetCountry returns the country, continent and netmask for the given IP
+func (g *GeoIP2) GetCountry(ip net.IP) (country, continent string, netmask int) {
  r, err := g.get(countryDB, "GeoIP2.mmdb")
  c, err := r.Country(ip)
  if err != nil {
@@ -180,15 +189,18 @@ func (g *g2) GetCountry(ip net.IP) (country, continent string, netmask int) {
  return country, continent, 0
 }
 
-func (g *g2) HasLocation() (bool, error) {
+// HasLocation returns if the city database is available to
+// return lat/lon information for an IP
+func (g *GeoIP2) HasLocation() (bool, error) {
  r, err := g.get(cityDB, "GeoIP2-City.mmdb")
  if r != nil && err == nil {
  return true, nil
  }
  return false, err
 }
 
-func (g *g2) GetLocation(ip net.IP) (l *geo.Location, err error) {
+// GetLocation returns a geo.Location object for the given IP
+func (g *GeoIP2) GetLocation(ip net.IP) (l *geo.Location, err error) {
  c, err := g.city.City(ip)
  if err != nil {
  log.Printf("Could not lookup CountryRegion for '%s': %s", ip.String(), err)