model

Documentation

Index

• type ASNIndexEntry
• type ASNPrefixes
• type BuildConfig
• type CanonicalPrefix
• type Error
  • func (e Error) Error() string
• type FetchMetadata
• type IPToASNStats
• type LookupResult
• type RDAPOrg
• type RawRow
• type Record
• type Stats

Types

type ASNIndexEntry

type ASNIndexEntry struct {
	ASN          int       `msgpack:"asn"`
	V4Count      int       `msgpack:"v4_count"`     // Number of IPv4 prefixes
	V4Collapsed  int       `msgpack:"v4_collapsed"` // Number after collapse
	LastModified time.Time `msgpack:"last_modified"`
}

ASNIndexEntry stores metadata about an ASN's prefixes

type ASNPrefixes

type ASNPrefixes struct {
	ASN       int
	Prefixes  []string // CIDR notation
	FetchedAt time.Time
}

ASNPrefixes represents announced prefixes for an ASN

type BuildConfig

type BuildConfig struct {
	// Input files
	ASNFile        string
	MMDBASNPath    string
	MMDBCityPath   string
	IPtoASNDBPath  string // Optional: use iptoasn database instead of RIPEstat API
	RIPEBulkDBPath string // Optional: use RIPE bulk database instead of RDAP for RIPE region
	ARINBulkDBPath string // Optional: use ARIN bulk database instead of RDAP for ARIN region

	// Output
	DBPath string

	// Processing options
	Workers        int
	CacheTTL       time.Duration
	SplitByMaxMind bool // Mode B: split by MaxMind city blocks
	IPv4Only       bool // Skip IPv6 prefixes entirely
	AllASNs        bool // Build for all ASNs from iptoasn database
	BulkOnly       bool // Only process ASNs/prefixes with bulk database coverage

	// API configuration
	RIPEBaseURL      string
	RDAPBootstrapURL string
	UserAgent        string

	// Rate limiting
	RDAPRateLimit float64 // requests per second
}

BuildConfig contains configuration for the build process

type CanonicalPrefix

type CanonicalPrefix struct {
	CIDR     string `msgpack:"cidr"`     // Canonical CIDR (e.g., "31.90.0.0/15")
	ASN      int    `msgpack:"asn"`      // Origin ASN
	Country  string `msgpack:"country"`  // 2-letter code
	Registry string `msgpack:"registry"` // RIR name
	ASName   string `msgpack:"asname"`   // Organization name
}

CanonicalPrefix represents a normalized prefix entry for storage

type Error

type Error string

Error types

const (
	ErrNotFound       Error = "IP not found in database"
	ErrInvalidIP      Error = "invalid IP address"
	ErrDatabaseClosed Error = "database is closed"
	ErrOverlap        Error = "overlapping range detected"
	ErrInvalidRange   Error = "invalid IP range"
	ErrRateLimited    Error = "rate limited by upstream service"
	ErrRDAPFailed     Error = "RDAP query failed"
)

func (Error) Error

func (e Error) Error() string

type FetchMetadata

type FetchMetadata struct {
	SourceURL    string    `json:"source_url"`
	ETag         string    `json:"etag,omitempty"`
	LastModified time.Time `json:"last_modified,omitempty"`
	CachePath    string    `json:"cache_path"`
	FetchedAt    time.Time `json:"fetched_at"`
}

FetchMetadata stores HTTP fetch metadata for incremental updates

type IPToASNStats

type IPToASNStats struct {
	TotalPrefixes int64            `json:"total_prefixes"`
	IPv4Prefixes  int64            `json:"ipv4_prefixes"`
	CollapsedV4   int64            `json:"collapsed_v4"`
	UniqueASNs    int              `json:"unique_asns"`
	ByRegistry    map[string]int64 `json:"by_registry"`
	SourceURL     string           `json:"source_url"`
	LastModified  time.Time        `json:"last_modified"`
	BuiltAt       time.Time        `json:"built_at"`
	ETag          string           `json:"etag,omitempty"`
}

IPToASNStats represents statistics about the iptoasn database

type LookupResult

type LookupResult struct {
	IP         string  `json:"ip"`
	ASN        int     `json:"asn"`
	ASNName    string  `json:"asn_name"`
	OrgName    string  `json:"org_name"`
	RIR        string  `json:"rir"`
	Country    string  `json:"country"`
	Region     string  `json:"region,omitempty"`
	City       string  `json:"city,omitempty"`
	Lat        float64 `json:"lat,omitempty"`
	Lon        float64 `json:"lon,omitempty"`
	Prefix     string  `json:"prefix"`
	SourceRole string  `json:"source_role"`
}

LookupResult is the output format for IP lookups

type RDAPOrg

type RDAPOrg struct {
	OrgName     string // Organization name
	RIR         string // Regional Internet Registry
	SourceRole  string // customer/registrant/asn_fallback
	StatusLabel string // Status from RDAP (e.g., ASSIGNED-PA)
	Country     string // Country code from RIR (preferred over MaxMind for RIR-managed space)
}

RDAPOrg represents organization information extracted from RDAP

type RawRow

type RawRow struct {
	Prefix   *net.IPNet // Canonical CIDR
	Start    netip.Addr // Inclusive start
	End      netip.Addr // Inclusive end
	ASN      int        // Origin ASN
	Country  string     // 2-letter code (may be "ZZ" for unknown)
	Registry string     // e.g., "ripencc", "arin", "apnic"
	ASName   string     // Provider/organization name from dataset
}

RawRow represents a parsed line from the iptoasn TSV file

type Record

type Record struct {
	Start       netip.Addr // Start IP of range
	End         netip.Addr // End IP of range
	ASN         int        // Autonomous System Number
	ASNName     string     // ASN organization name from MaxMind
	OrgName     string     // Organization name from RDAP (preferred) or ASN fallback
	RIR         string     // Regional Internet Registry (ARIN/RIPE/APNIC/LACNIC/AFRINIC)
	Country     string     // ISO 3166-1 alpha-2 country code
	Region      string     // Region/state name (optional)
	City        string     // City name (optional)
	Lat         float64    // Latitude (optional)
	Lon         float64    // Longitude (optional)
	SourceRole  string     // customer/registrant/asn_fallback - source of org_name
	StatusLabel string     // RIPE status (e.g., ASSIGNED-PA, SUB-ALLOCATED-PA)
	Prefix      string     // Original announced prefix (CIDR notation)
	LastChecked time.Time  // Last time this record was validated
	Schema      int        // Schema version for future migrations
}

Record represents a single IP range with associated metadata

type Stats

type Stats struct {
	TotalRecords     int64
	IPv4Records      int64
	IPv6Records      int64
	RecordsByRIR     map[string]int64
	RecordsByRole    map[string]int64
	RecordsByCountry map[string]int64
	LastBuiltAt      time.Time
	SchemaVersion    int
	BuilderVersion   string
}

Stats represents database statistics