geolocate

README

Package github.com/ooni/probe-engine/geolocate

Package geolocate implements IP lookup, resolver lookup, and geolocation.

Documentation

Overview

Package geolocate implements IP lookup, resolver lookup, and geolocation.

Index

• Constants
• Variables
• func LookupASN(path, ip string) (asn uint, org string, err error)
• type Config
• type Logger
• type ResourcesManager
• type Results
  • func (r *Results) ASNString() string
• type Task
  • func Must(task *Task, err error) *Task
  • func NewTask(config Config) (*Task, error)
  • func (op Task) Run(ctx context.Context) (*Results, error)

Constants

const (
	// DefaultProbeASN is the default probe ASN as number.
	DefaultProbeASN uint = 0

	// DefaultProbeCC is the default probe CC.
	DefaultProbeCC = "ZZ"

	// DefaultProbeIP is the default probe IP.
	DefaultProbeIP = model.DefaultProbeIP

	// DefaultProbeNetworkName is the default probe network name.
	DefaultProbeNetworkName = ""

	// DefaultResolverASN is the default resolver ASN.
	DefaultResolverASN uint = 0

	// DefaultResolverIP is the default resolver IP.
	DefaultResolverIP = "127.0.0.2"

	// DefaultResolverNetworkName is the default resolver network name.
	DefaultResolverNetworkName = ""
)

Variables

var (
	// DefaultProbeASNString is the default probe ASN as a string.
	DefaultProbeASNString = fmt.Sprintf("AS%d", DefaultProbeASN)

	// DefaultResolverASNString is the default resolver ASN as a string.
	DefaultResolverASNString = fmt.Sprintf("AS%d", DefaultResolverASN)
)

var (
	// ErrAllIPLookuppersFailed indicates that we failed with looking
	// up the probe IP for with all the lookuppers that we tried.
	ErrAllIPLookuppersFailed = errors.New("all IP lookuppers failed")

	// ErrInvalidIPAddress indicates that the code returned to us a
	// string that actually isn't a valid IP address.
	ErrInvalidIPAddress = errors.New("lookupper did not return a valid IP")
)

var (
	// ErrMissingResourcesManager indicates that no resources
	// manager has been configured inside of Config.
	ErrMissingResourcesManager = errors.New("geolocate: ResourcesManager is nil")
)

var (
	// ErrNoIPAddressReturned indicates that no IP address was
	// returned by a specific DNS resolver.
	ErrNoIPAddressReturned = errors.New("geolocate: no IP address returned")
)

Functions

func LookupASN

func LookupASN(path, ip string) (asn uint, org string, err error)

LookupASN returns the ASN and the organization associated with the given ip using the ASN database at path.

Types

type Config

type Config struct {
	// EnableResolverLookup indicates whether we want to
	// perform the optional resolver lookup.
	EnableResolverLookup bool

	// HTTPClient is the HTTP client to use. If not set, then
	// we will use the http.DefaultClient.
	HTTPClient *http.Client

	// Logger is the logger to use. If not set, then we will
	// use a logger that discards all messages.
	Logger Logger

	// ResourcesManager is the mandatory resources manager. If not
	// set, we will not be able to perform any lookup.
	ResourcesManager ResourcesManager

	// UserAgent is the user agent to use. If not set, then
	// we will use a default user agent.
	UserAgent string
}

Config contains configuration for a geolocate Task.

type Logger

type Logger interface {
	Debugf(format string, v ...interface{})
}

Logger is the definition of Logger used by this package.

type ResourcesManager

type ResourcesManager interface {
	// ASNDatabasePath returns the path of the ASN database.
	ASNDatabasePath() string

	// CountryDatabasePath returns the path of the country database.
	CountryDatabasePath() string

	// MaybeUpdateResources ensures that the required resources
	// have been downloaded and are current.
	MaybeUpdateResources(ctx context.Context) error
}

ResourcesManager manages the required resources.

type Results

type Results struct {
	// ASN is the autonomous system number
	ASN uint

	// CountryCode is the country code
	CountryCode string

	// DidResolverLookup indicates whether we did a resolver lookup.
	DidResolverLookup bool

	// NetworkName is the network name
	NetworkName string

	// IP is the probe IP
	ProbeIP string

	// ResolverASN is the resolver ASN
	ResolverASN uint

	// ResolverIP is the resolver IP
	ResolverIP string

	// ResolverNetworkName is the resolver network name
	ResolverNetworkName string
}

Results contains geolocate results

func (*Results) ASNString

func (r *Results) ASNString() string

ASNString returns the ASN as a string

type Task

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

Task performs a geolocation. You must create a new instance of Task using the NewTask factory.

func Must

func Must(task *Task, err error) *Task

Must ensures that NewTask is successful.

func NewTask

func NewTask(config Config) (*Task, error)

NewTask creates a new instance of Task from config.

func (Task) Run

func (op Task) Run(ctx context.Context) (*Results, error)

Run runs the task.