geolocate

Documentation

Overview

Package geolocate provides functionality to discover the public IP address of the current host and obtain geolocation metadata (country code, ASN, and AS name) for that IP.

The package offers multiple strategies for IP discovery:

1. STUN-based discovery (preferred): Uses STUN (Session Traversal Utilities for NAT) servers to determine the public IP address. This should be attempted first and is generally more reliable behind NAT/firewall configurations.

2. HTTPS API-based discovery: public HTTPS endpoints such as ipify, ipinfo.io, and api-bdc.net, could be used if STUN discovery fails.

Once a public IP is obtained, the package queries a geolocation API (by default the OONI geolocation service) to retrieve associated metadata including the autonomous system name (ASName), autonomous system number (ASN), and country code (CC).

Configuration

The package uses sensible defaults but can be customized:

• Geolocator: Create a custom Geolocator with NewGeolocator(apiUrl) to specify a different geolocation API endpoint. The default endpoint is the OONI API at https://api.dev.ooni.io/api/v1/geolookup. Note: A custom geolocation API endpoint needs to follow OONIs json scheme

• HTTP Client: The package uses a default HTTP client with a 10-second timeout. For advanced customization, you can modify the Geolocator's Client field after instantiation.

• STUN Servers: The package includes a curated list of public STUN servers that are automatically shuffled for each lookup attempt. This list can be extended by modifying the stunServers variable if needed.

• HTTPS Providers: The package queries multiple HTTPS-based IP lookup services (bdc, ipify, ipinfo) and automatically shuffles them during discovery. The list can be extended via the httpsServers variable.

Usage

For a simple, one-shot geolocation lookup of the current host:

geo, err := geolocate.FindCurrentHostGeolocation()
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Country: %s, ASN: %d, AS Name: %s\n", geo.CC, geo.ASN, geo.ASName)

For more control over the geolocation endpoint:

geolocator := geolocate.NewGeolocator("https://my-custom-api.example.com/geolookup")
geo, err := geolocator.Geolocate("192.0.2.1")
if err != nil {
	log.Fatal(err)
}

To perform GeoIP discovery using a specific set of STUN servers:

geolocator := geolocate.NewDefaultGeolocator()
stunServers := []string{"stun.l.google.com:3478", "stun.ekiga.net:3478"}
geo, err := geolocator.FindCurrentHostGeolocationWithSTUN(stunServers)
if err != nil {
	log.Fatal(err)
}

Index

• func AttemptFetchingPublicIP() (string, error)
• func FetchIPFromHTTPSAPICall(provider string) (string, error)
• func FetchIPFromSTUNCall(uri string) (string, error)
• type GeoInfo
  • func FindCurrentHostGeolocation() (*GeoInfo, error)
• type Geolocator
  • func NewDefaultGeolocator() *Geolocator
  • func NewGeolocator(apiUrl string) *Geolocator
  • func (g *Geolocator) FindCurrentHostGeolocationWithSTUN(stunServers []string) (*GeoInfo, error)
  • func (g *Geolocator) Geolocate(ip string) (*GeoInfo, error)

Functions

func AttemptFetchingPublicIP

func AttemptFetchingPublicIP() (string, error)

AttemptFetchingPublicIP will attempt to get our public IP by exhausting all the available sources; the order is stun > https. It will return an error if all the sources are used and we still don't have a result.

func FetchIPFromHTTPSAPICall

func FetchIPFromHTTPSAPICall(provider string) (string, error)

FetchIPFromHTTPSAPICall tries to get the public IP via the passed HTTPS provider label.

func FetchIPFromSTUNCall

func FetchIPFromSTUNCall(uri string) (string, error)

FetchIPFromSTUNCall tries to get our public IP using the passed stun uri. It returns an error of the operation does not succeed.

Types

type GeoInfo

type GeoInfo struct {
	ASName string `json:"as_name"`
	ASN    int    `json:"asn"`
	CC     string `json:"cc"`
}

GeoInfo contains the minimal metadata that we need for annotating reports.

func FindCurrentHostGeolocation

func FindCurrentHostGeolocation() (*GeoInfo, error)

FindCurrentHostGeolocation will make a best-effor attempt at discovering the public IP of the vantage point where the software is running, and obtain geolocation metadata for it. This function currently uses a single endpoint for geolocation (in the OONI API).

type Geolocator

type Geolocator struct {
	API    string
	Client *http.Client
}

A Geolocator is able to geolocate IPs, using a specific http.Client.

func NewDefaultGeolocator

func NewDefaultGeolocator() *Geolocator

NewDefaultGeolocator initializes a geolocator with a default http client and OONIs public geoip service endpoint

func NewGeolocator

func NewGeolocator(apiUrl string) *Geolocator

NewGeolocator initializes a geolocator with a default http client and a custom http geoip service endpoint (that adheres to OONI's geoip json scheme)

func (*Geolocator) FindCurrentHostGeolocationWithSTUN

func (g *Geolocator) FindCurrentHostGeolocationWithSTUN(stunServers []string) (*GeoInfo, error)

FindCurrentHostGeolocationWithSTUN first tries to get the current public ip address by using the given STUN servers. It then uses countryCodeLookupURL to convert the ip address into a country code. If countryCodeLookupURL is empty, then defaultGeolocationAPI (OONI) is used

func (*Geolocator) Geolocate

func (g *Geolocator) Geolocate(ip string) (*GeoInfo, error)

Geolocate returns basic geoip meta data, retrieved from the configured geoip service