Documentation
¶
Overview ¶
Package geoip helps in geolocation operations.
Index ¶
- Constants
- Variables
- type DBIP
- func (d *DBIP) Close() error
- func (d *DBIP) GetCountry(ip net.IP) (string, error)
- func (d *DBIP) GetPosition(ip net.IP) (Position, error)
- func (d *DBIP) KeepFresh(ctx context.Context, baseURL string, c clock.Clock, ...)
- func (d *DBIP) Refresh(ctx context.Context, baseURL string, now time.Time) error
- type Locator
- type Position
Constants ¶
const ( // ErrCodeNoDatabase is the code of ErrNoDatabase. ErrCodeNoDatabase = iota + 1 // ErrCodeDownload is the code of ErrDownload. ErrCodeDownload // ErrCodeInvalidAddress is the code of ErrInvalidAddress. ErrCodeInvalidAddress )
const DBIPDownloadURL = "https://download.db-ip.com/free"
DBIPDownloadURL is where DB-IP publishes its free City Lite databases, one per month.
const ErrLayer = "geoip"
ErrLayer names the geoip layer in the errors it returns.
Variables ¶
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
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
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
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
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
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
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.