geoip

package
v0.30.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: Apache-2.0 Imports: 16 Imported by: 3

Documentation

Overview

Package geoip helps in geolocation operations.

Index

Constants

View Source
const (
	// ErrCodeNoDatabase is the code of ErrNoDatabase.
	ErrCodeNoDatabase = iota + 1
	// ErrCodeDownload is the code of ErrDownload.
	ErrCodeDownload
	// ErrCodeInvalidAddress is the code of ErrInvalidAddress.
	ErrCodeInvalidAddress
)
View Source
const DBIPDownloadURL = "https://download.db-ip.com/free"

DBIPDownloadURL is where DB-IP publishes its free City Lite databases, one per month.

View Source
const ErrLayer = "geoip"

ErrLayer names the geoip layer in the errors it returns.

Variables

View Source
var (
	// ErrNoDatabase is returned by [OpenDBIP] when no database opens. It is joined with the error
	// opening the last one tried, or with [os.ErrNotExist] when there was none to try.
	ErrNoDatabase = errors.New("no GeoIP database to open", ErrLayer, ErrCodeNoDatabase)
	// ErrDownload is returned by [DBIP.Refresh] when the month's database cannot be fetched, written
	// or opened. It is joined with the cause.
	ErrDownload = errors.New("cannot download the GeoIP database", ErrLayer, ErrCodeDownload)
	// ErrInvalidAddress is returned by a lookup given an IP that is neither IPv4 nor IPv6.
	ErrInvalidAddress = errors.New("invalid IP address", ErrLayer, ErrCodeInvalidAddress)
)

Functions

This section is empty.

Types

type DBIP added in v0.30.0

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

DBIP locates addresses with a DB-IP City Lite database, which answers both the country and the position. It reads the newest database it finds, downloaded or baked into the image, and DBIP.Refresh swaps in a newer month without a restart. It is safe for concurrent use.

func OpenDBIP added in v0.30.0

func OpenDBIP(dir, baked string) (*DBIP, error)

OpenDBIP opens the newest database by month among those downloaded into dir and those baked into the image in baked, trying an older one when the newest does not open. Databases are named dbip-city-lite-YYYY-MM.mmdb, which is how the month is known. It first deletes any download an earlier process left half written in dir. It returns ErrNoDatabase when nothing opens.

func (*DBIP) Close added in v0.30.0

func (d *DBIP) Close() error

Close closes the database in use and returns the reader's error, if any. Lookups after Close fail, and a Refresh after it swaps in a database nothing closes.

func (*DBIP) GetCountry added in v0.30.0

func (d *DBIP) GetCountry(ip net.IP) (string, error)

GetCountry returns the ISO 3166-1 code of ip's country, empty when the database has none. It returns ErrInvalidAddress for an ip that is neither IPv4 nor IPv6, and the database reader's error when the lookup fails, as it does after Close.

func (*DBIP) GetPosition added in v0.30.0

func (d *DBIP) GetPosition(ip net.IP) (Position, error)

GetPosition returns ip's position, the zero Position when the database has none. It returns ErrInvalidAddress for an ip that is neither IPv4 nor IPv6, and the database reader's error when the lookup fails, as it does after Close.

func (*DBIP) KeepFresh added in v0.30.0

func (d *DBIP) KeepFresh(ctx context.Context, baseURL string, c clock.Clock, every, timeout time.Duration, failed func(error))

KeepFresh calls Refresh with c's time at once and then every every until ctx ends, giving each attempt at most timeout. It hands each failure, a stalled download included, to failed and goes on with the database it has. It blocks until ctx ends.

func (*DBIP) Refresh added in v0.30.0

func (d *DBIP) Refresh(ctx context.Context, baseURL string, now time.Time) error

Refresh fetches now's month from baseURL, published there as dbip-city-lite-YYYY-MM.mmdb.gz, when the database in use is older. It writes it into the directory, swaps it in and deletes the downloads it replaced, never the baked database. It requests nothing when the database in use is already that month's, and returns nil, keeping its database, while the month is not published. It returns ErrDownload, keeping its database and leaving no partial file behind, when the fetch, the write or the opening fails. It fetches under ctx.

type Locator

type Locator interface {
	// GetCountry retrieves the ISO country code for a given IP address.
	// Returns an error if the IP lookup fails.
	GetCountry(ip net.IP) (string, error)

	// GetPosition retrieves the geographical [Position] for a given IP
	// address. Returns an error if the IP lookup fails.
	GetPosition(ip net.IP) (Position, error)
}

Locator resolves an IP address to where it is. Implementations answer from a local database, so a lookup is offline and the answer is a guess with no confidence attached.

func NewFake added in v0.30.0

func NewFake(next Locator) Locator

NewFake returns a Locator for development, where agents connect from private addresses no database places. It puts a private, loopback, link-local or unspecified address in one of a fixed list of real cities, the same city for the same address every time, never failing for one. It asks next for any other address and returns next's answer and error unchanged.

func NewNullGeoLite

func NewNullGeoLite() Locator

NewNullGeoLite returns a no-op Locator that resolves every IP to an empty country and the zero Position, never failing. The server falls back to it in every edition when no GeoIP database opens.

type Position

type Position struct {
	Longitude, Latitude float64
}

Position represents a position, longitude and latitude, in the globe.

Directories

Path Synopsis
Package geoiptest writes small GeoIP databases for tests, so no test needs a real one.
Package geoiptest writes small GeoIP databases for tests, so no test needs a real one.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL