geoip

Documentation

Overview

Package geoip reads MaxMind-DB files — the free DB-IP lite country and ASN databases, or the operator's own — with the standard library alone, and answers "where is this address from" for the agent (rules and exemptions by country or AS, SPEC §5.3) and for the controller (the map, the facets). Public: the controller imports it, so both sides read the same files the same way.

Package geoip answers "where is this address from" — a country and an autonomous system — from MaxMind-DB files on the controller's disk (SPEC §5.1: enrichment from local databases only, plain files updated out of band). The reader is this file: the format is small, and a dependency for it would be larger than the code.

Index

• type AS
• type DB
  • func Open(path string) (*DB, error)
  • func Parse(b []byte) (*DB, error)
  • func (db *DB) Lookup(ip netip.Addr) (any, error)
  • func (db *DB) Prefixes(keep func(record any) bool, max int) ([]netip.Prefix, error)
  • func (db *DB) Walk(visit func(p netip.Prefix, record any)) error
• type Network
• type Origin
• type Resolver
  • func (r *Resolver) CityStatus() (kind string, built time.Time, loaded bool)
  • func (r *Resolver) Country(code string, max int) (prefixes []netip.Prefix, count int, err error)
  • func (r *Resolver) Index() error
  • func (r *Resolver) Indexed() bool
  • func (r *Resolver) Load(countryPath, asnPath string) error
  • func (r *Resolver) LoadCity(path string) error
  • func (r *Resolver) Lookup(value string) Origin
  • func (r *Resolver) LookupAddr(ip netip.Addr) Origin
  • func (r *Resolver) Network(asn uint32, max int) (Network, error)
  • func (r *Resolver) Ready() bool
  • func (r *Resolver) Search(q string, max int) []AS
  • func (r *Resolver) Status() (country, asn string, built time.Time)

Types

type AS

type AS struct {
	ASN      uint32
	Name     string
	Prefixes int
	V4       int
	V6       int
}

AS is one autonomous system as the ASN database knows it: its number, its name, and how many prefixes it announces there. What a person picks a network from — by name or by number — without knowing either exactly.

type DB

type DB struct {

	// Type describes the database ("DBIP-Country-Lite", "GeoLite2-ASN"),
	// Built when it was made — shown so an operator sees what they run.
	Type  string
	Built int64
	// contains filtered or unexported fields
}

DB is one MaxMind-DB file, read whole into memory: the free country and ASN databases are a few megabytes, and a lookup is a tree walk.

func Open

func Open(path string) (*DB, error)

Open reads a database file.

func Parse

func Parse(b []byte) (*DB, error)

Parse reads a database from its bytes.

func (*DB) Lookup

func (db *DB) Lookup(ip netip.Addr) (any, error)

Lookup returns the record for an address as decoded data — a map for the databases this package reads — or nil when the address is not in the database.

func (*DB) Prefixes

func (db *DB) Prefixes(keep func(record any) bool, max int) ([]netip.Prefix, error)

Prefixes walks the whole tree and returns every prefix whose record satisfies keep — how "which ranges belong to this network" is answered from a database that only maps the other way. A full walk of the free ASN database is a few hundred thousand leaves: tens of milliseconds, so callers cache what they ask often. Bounded by max results.

func (*DB) Walk

func (db *DB) Walk(visit func(p netip.Prefix, record any)) error

Walk visits every leaf of the tree with its prefix and its record, decoded once per distinct data offset. Prefixes is the filtered form of it; Walk is for building an index of the whole database.

type Network

type Network struct {
	ASN      uint32
	Name     string
	Prefixes []netip.Prefix // bounded; Count is the true number
	Count    int
}

Network is what the ASN database holds for one autonomous system.

type Origin

type Origin struct {
	Country     string // ISO 3166-1 alpha-2, "" when unknown
	CountryName string
	ASN         uint32 // 0 when unknown
	ASName      string
	// From a city database, when one is loaded (the controller's option;
	// an agent never needs it): the city and its region, in English, and
	// the point the database gives — a rough one on free data.
	City     string
	Region   string
	Lat, Lon float64
}

Origin is what the databases say about an address.

type Resolver

type Resolver struct {
	Loaded time.Time
	// contains filtered or unexported fields
}

Resolver answers from a country database and an ASN database, either of which may be missing. Safe for concurrent use; Reload swaps files.

func (*Resolver) CityStatus

func (r *Resolver) CityStatus() (kind string, built time.Time, loaded bool)

CityStatus describes the city database, if one is loaded.

func (*Resolver) Country

func (r *Resolver) Country(code string, max int) (prefixes []netip.Prefix, count int, err error)

Country lists the prefixes the country database places in one country (ISO code), at most max, by walking it; Count is the true number. A country is tens of thousands of leaves at most: a walk, not a cache.

func (*Resolver) Index

func (r *Resolver) Index() error

Index builds the AS index from the loaded ASN database; a second call on the same database is a no-op. It walks the whole tree, so callers run it off the hot path.

func (*Resolver) Indexed

func (r *Resolver) Indexed() bool

Indexed reports whether the AS index is ready.

func (*Resolver) Load

func (r *Resolver) Load(countryPath, asnPath string) error

Load opens the files given (empty paths are skipped).

func (*Resolver) LoadCity

func (r *Resolver) LoadCity(path string) error

LoadCity opens a city database beside the two others ("" unloads it).

func (*Resolver) Lookup

func (r *Resolver) Lookup(value string) Origin

Lookup resolves an address, or the address of a range (its first). A value that is not an address, or an unknown one, is an empty Origin.

func (*Resolver) LookupAddr

func (r *Resolver) LookupAddr(ip netip.Addr) Origin

LookupAddr resolves one address — the hot path: no parsing.

func (*Resolver) Network

func (r *Resolver) Network(asn uint32, max int) (Network, error)

Network lists an autonomous system's prefixes, at most max, by walking the ASN database; the answer is cached for an hour.

func (*Resolver) Ready

func (r *Resolver) Ready() bool

Ready reports whether anything is loaded.

func (*Resolver) Search

func (r *Resolver) Search(q string, max int) []AS

Search finds autonomous systems by number (exact, or a number the query begins with — "3215" also offers AS32150…) or by a word of their name, case-insensitively; the biggest first, at most max. An empty query returns the biggest networks.

func (*Resolver) Status

func (r *Resolver) Status() (country, asn string, built time.Time)

Status describes what is loaded.