tgeo

Documentation

Index

• Constants
• Variables
• func AddrInc(addr netip.Addr) (netip.Addr, bool)
• func AddrToUint32(addr netip.Addr) uint32
• func CompressGzip(data []byte) ([]byte, error)
• func DecompressGzip(data []byte) ([]byte, error)
• func Encode(data *GeoIPData) ([]byte, error)
• func Merge(sourcesData map[string]SourceData) ([]IPRange, MergeStats)
• func Uint32ToAddr(v uint32) netip.Addr
• func VerifyAndWrite(compressed []byte, expectedChecksum string, destPath string) error
• type CompileResult
  • func Compile(ranges []IPRange) (*CompileResult, error)
• type GeoIPData
  • func Decode(raw []byte) (*GeoIPData, error)
• type IPRange
• type IPv4Entry
• type MergeStats
• type Meta
• type SourceData
• type Table
  • func LoadTable(path string) (*Table, error)
  • func LoadTableFromBytes(raw []byte) (*Table, error)
  • func (t *Table) CodeCount() int
  • func (t *Table) EntryCount() int
  • func (t *Table) LookupCountry(ip netip.Addr) string

Constants

const (
	FormatVersion  = 1
	HeaderSize     = 12 // magic(4) + version(4) + entry_count(4)
	IPv4EntrySize  = 6  // ip_start(4) + country_idx(2)
	CountryCodeLen = 2  // ISO 3166-1 alpha-2
)

Variables

var Magic = [4]byte{'T', 'G', 'E', 'O'}

Magic is the four-byte file signature for the TGEO binary format.

Functions

func AddrInc

func AddrInc(addr netip.Addr) (netip.Addr, bool)

AddrInc increments an IPv4 address by 1. Returns the incremented address and true if successful, or a zero address and false on overflow (255.255.255.255 + 1).

func AddrToUint32

func AddrToUint32(addr netip.Addr) uint32

AddrToUint32 converts an IPv4 netip.Addr to a uint32 in network byte order.

func CompressGzip

func CompressGzip(data []byte) ([]byte, error)

CompressGzip compresses data with gzip at default compression level.

func DecompressGzip

func DecompressGzip(data []byte) ([]byte, error)

DecompressGzip decompresses gzip data. Returns an error if the decompressed output exceeds 256 MB to prevent decompression bombs.

func Encode

func Encode(data *GeoIPData) ([]byte, error)

Encode serializes GeoIPData to the TGEO binary format (uncompressed).

func Merge

func Merge(sourcesData map[string]SourceData) ([]IPRange, MergeStats)

Merge combines IP ranges from multiple sources using an event-based sweep-line. Higher-priority sources win on conflict. Gaps are filled with "ZZ".

func Uint32ToAddr

func Uint32ToAddr(v uint32) netip.Addr

Uint32ToAddr converts a uint32 in network byte order to an IPv4 netip.Addr.

func VerifyAndWrite

func VerifyAndWrite(compressed []byte, expectedChecksum string, destPath string) error

VerifyAndWrite validates a compressed TGEO payload against its expected checksum, decompresses it, and atomically writes the result to destPath.

The checksum must be in the format "sha256:<hex>". The SHA-256 is computed over the compressed bytes (what was downloaded), not the decompressed content. The write is atomic: data is written to a temporary file then renamed.

Types

type CompileResult

type CompileResult struct {
	GzipData   []byte
	Checksum   string // "sha256:hex..."
	EntryCount int
	Countries  int
}

CompileResult holds the output of the compilation step.

func Compile

func Compile(ranges []IPRange) (*CompileResult, error)

Compile takes merged IPv4 ranges and produces a gzip-compressed TGEO binary along with its SHA-256 checksum. Ranges are sorted by start IP before encoding.

type GeoIPData

type GeoIPData struct {
	Entries   []IPv4Entry
	Countries []string // 2-char country codes, index matches CountryIdx
}

GeoIPData is the in-memory representation of the TGEO binary format.

func Decode

func Decode(raw []byte) (*GeoIPData, error)

Decode deserializes the TGEO binary format (uncompressed) into GeoIPData.

type IPRange

type IPRange struct {
	Start   netip.Addr
	End     netip.Addr
	Country string // ISO 3166-1 alpha-2, or "ZZ" for unknown/unallocated
}

IPRange represents a contiguous IPv4 address range mapped to a country.

type IPv4Entry

type IPv4Entry struct {
	IPStart    uint32
	CountryIdx uint16
}

IPv4Entry is a single row in the IPv4 lookup table.

type MergeStats

type MergeStats struct {
	RangesPerSource map[string]int `json:"ranges_per_source"`
	ConflictCount   int            `json:"conflict_count"`
	OutputRanges    int            `json:"output_ranges"`
	GapsFilled      int            `json:"gaps_filled"`
}

MergeStats records information about the merge operation.

type Meta

type Meta struct {
	Version     string   `json:"version"`
	PublishedAt string   `json:"published_at"`
	Checksum    string   `json:"checksum"`
	Size        int64    `json:"size"`
	DownloadURL string   `json:"download_url"`
	Sources     []string `json:"sources"`
	License     string   `json:"license"`
}

Meta is the canonical metadata type for TGEO data feeds. Both the producing service (API responses) and consuming clients (API requests) should use this type to avoid drift.

type SourceData

type SourceData struct {
	Ranges   []IPRange
	Priority int
}

SourceData holds IP ranges from a single data source along with its priority. Higher priority values win when ranges from multiple sources overlap.

type Table

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

Table is a read-optimized lookup structure loaded from a TGEO binary file. It uses parallel arrays and binary search for ~14ns IPv4 lookups.

func LoadTable

func LoadTable(path string) (*Table, error)

LoadTable reads a TGEO binary file from disk and returns a Table ready for lookups.

func LoadTableFromBytes

func LoadTableFromBytes(raw []byte) (*Table, error)

LoadTableFromBytes parses uncompressed TGEO binary data and returns a Table ready for lookups. Use this when the TGEO data is already in memory rather than on disk.

func (*Table) CodeCount

func (t *Table) CodeCount() int

CodeCount returns the number of distinct country codes in the table.

func (*Table) EntryCount

func (t *Table) EntryCount() int

EntryCount returns the number of IPv4 range entries in the table.

func (*Table) LookupCountry

func (t *Table) LookupCountry(ip netip.Addr) string

LookupCountry returns the ISO 3166-1 alpha-2 country code for an IPv4 address. Returns "ZZ" for unallocated/reserved space or non-IPv4 addresses.