geoipdb

README

geoipdb

GeoIP related related helper functions for TurboBytes stack

Documentation

Overview

Package geoipdb is a library of GeoIP related helper functions for TurboBytes stack.

Basics

Get a geoipdb Handler with NewHandler, and use its lookup methods at will.

Lookup of Autonomous System Numbers

For looking up the autonomous system number of an IP address, use LookupAsn as it wraps more than one search method.

If you want a specific service to be queried for ASN, see other Handler lookup methods.

Example (LookupAsn)

package main

import (
	"fmt"
	"time"

	"github.com/turbobytes/geoipdb"
)

func main() {
	ip := "8.8.8.8"
	gh, err := geoipdb.NewHandler(nil, time.Second*5)
	if err != nil {
		panic(err)
	}
	asn, descr, err := gh.LookupAsn(ip)
	if err != nil {
		panic(err)
	}
	fmt.Printf("ASN for %s: %s (%s)\n", ip, asn, descr)
}

Output:

ASN for 8.8.8.8: AS15169 (Google Inc.)

Index

• Variables
• type AsnOverride
• type Handler
  • func NewHandler(overrides *mgo.Collection, timeout time.Duration) (Handler, error)
  • func (h Handler) AsnCacheList() []string
  • func (h Handler) AsnCachePurge()
  • func (h Handler) CymruDnsLookup(asn string) (string, error)
  • func (h Handler) IpInfoLookup(ip string) (string, string, error)
  • func (h Handler) LibGeoipLookup(ip string) (string, string)
  • func (h Handler) LookupAsn(ip string) (string, string, error)
  • func (h Handler) LookupIp(asn string) []string
  • func (h Handler) OverridesList() ([]AsnOverride, error)
  • func (h Handler) OverridesLookup(asn string) (string, error)
  • func (h Handler) OverridesRemove(asn string) error
  • func (h Handler) OverridesSet(asn string, descr string) error

Examples

• Package (LookupAsn)

Variables

var (
	// MalformedIPError is returned on parse failure of IP parameter.
	MalformedIPError = errors.New("malformed IP address")
	// PrivateIPError is returned on AS lookup of a private IP address.
	PrivateIPError = errors.New("private IP address")
)

var OverridesAsnNotFoundError = errors.New("ASN not found")

OverridesAsnNotFoundError is returned by OverridesLookup when there is no override defined.

var OverridesMalformedAsnError = errors.New("malformed ASN")

OverridesMalformedAsnError is returned by OverridesSet when parameter asn does not conform to an ASN identification.

var OverridesNilCollectionError = errors.New("nil overrides collection")

OverridesNilCollectionError is returned by Overrides<...> methods when Handler was created without an overrides collection (see NewHandler).

Types

type AsnOverride

type AsnOverride struct {
	Asn  string `bson:"_id" json:"asn"`
	Name string `bson:"name" json:"name"`
}

AsnOverride is what is stored in the overrides collection.

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler is a handler to TurboBytes GeoIP helper functions.

func NewHandler

func NewHandler(overrides *mgo.Collection, timeout time.Duration) (Handler, error)

NewHandler creates a handler for accessing geoipdb features.

Parameter overrides, if not nil, is used to access a collection of overrides of ASN descriptions. (See Overrides<...> methods.)

Parameter timeout is honored by methods that access external services. Pass zero to disable timeout.

Returns a geoipdb handler.

func (Handler) AsnCacheList

func (h Handler) AsnCacheList() []string

AsnCacheList retrieves all ASNs known to the cache.

Returns a non nil list of ASNs.

func (Handler) AsnCachePurge

func (h Handler) AsnCachePurge()

AsnCachePurge erases all LookupAsn cached data.

func (Handler) CymruDnsLookup

func (h Handler) CymruDnsLookup(asn string) (string, error)

CymruDnsLookup performs a query to Team Cymru's DNS service for the description of a given ASN.

Returns the ASN description.

func (Handler) IpInfoLookup

func (h Handler) IpInfoLookup(ip string) (string, string, error)

IpInfoLookup queries ipinfo.io for the ASN of a given ip address.

Returns an ASN identification and the corresponding description.

func (Handler) LibGeoipLookup

func (h Handler) LibGeoipLookup(ip string) (string, string)

LibGeoipLookup queries the libgeoip database for the ASN of a given ip address.

Returns an ASN identification and the corresponding description.

func (Handler) LookupAsn

func (h Handler) LookupAsn(ip string) (string, string, error)

LookupAsn searches for the Autonomous System Number (ASN) of a valid IP address.

This is the preferred ASN lookup function to be used by clients, as it queries several resources for finding proper answers. Particularly, the overrides collection (see NewHandler) takes precedence for querying ASN descriptions.

Data returned by LookupAsn is cached with a 1 day TTL. Also see: AsnCachePurge.

Returns an ASN identification and the corresponding description.

func (Handler) LookupIp

func (h Handler) LookupIp(asn string) []string

LookupIp searches the cache for all IP addresses associated with a given ASN.

Returns a non nil list of IP addresses.

func (Handler) OverridesList

func (h Handler) OverridesList() ([]AsnOverride, error)

OverridesList answers all ASN description overrides.

func (Handler) OverridesLookup

func (h Handler) OverridesLookup(asn string) (string, error)

OverridesLookup queries the database of local overrides for the description of a given ASN.

Returns the ASN description, or OverridesAsnNotFoundError if there is no override for the ASN.

func (Handler) OverridesRemove

func (h Handler) OverridesRemove(asn string) error

OverridesRemove removes the description for a given ASN from the database of local overrides. If there is no such ASN, OverridesRemove returns silently without error.

Moreover, this method purges the cache (see LookupAsn) of all data related to the given asn.

func (Handler) OverridesSet

func (h Handler) OverridesSet(asn string, descr string) error

OverridesSet stores or updates a user defined description for a given ASN in the database of local overrides.

Moreover, this method purges the cache (see LookupAsn) of all data related to the given asn.