ip2country

type Config struct {
	// Delimiter specifies the character used to separate fields in the CSV file.
	Delimiter string
	// MaxFileSize limits the size of the file to be loaded, preventing excessive memory usage.
	// The value is in bytes. A value of 0 or less means no limit.
	MaxFileSize int64
	// MaxRanges sets the maximum number of IP ranges or entries to load from the file.
	// A value of 0 or less means no limit.
	MaxRanges int
	// CacheSize defines the number of entries to keep in the LRU cache.
	// If set to 0 or less, a default value will be used.
	CacheSize int
	// SkipHeader indicates whether the first line of the CSV file should be skipped.
	SkipHeader bool
}

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

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

type IPCountryLookup interface {
	// GetCountry retrieves the country code for a given IP address string.
	// In the current implementation, this returns the same value as GetCountryCode.
	GetCountry(ipStr string) (string, error)
	// GetCountryCode retrieves the country code (e.g., "US") for a given IP address string.
	GetCountryCode(ipStr string) (string, error)
	// GetCountryWithContext retrieves the country code, respecting the context.
	GetCountryWithContext(ctx context.Context, ipStr string) (string, error)
	// GetCountryCodeWithContext retrieves the country code, respecting the context.
	GetCountryCodeWithContext(ctx context.Context, ipStr string) (string, error)
	// Stats returns the current operational statistics of the database.
	Stats() Stats
	// Reload clears the current dataset and loads it again from the source file.
	Reload() error
	// ReloadWithContext reloads the dataset, respecting the context for cancellation.
	ReloadWithContext(ctx context.Context) error
}

type IPRange struct {
	// Country is the country code (e.g., US, DE).
	Country string `json:"country"`
	// Code is the two-letter country code.
	Code string `json:"code"`
	// StartIP is the starting IP address of the range, as a 32-bit unsigned integer.
	StartIP uint32 `json:"start_ip"`
	// EndIP is the ending IP address of the range, as a 32-bit unsigned integer.
	EndIP uint32 `json:"end_ip"`
}

type ParseError struct {
	// Content is the actual content of the line that caused the error.
	Content string
	// Err is the underlying error.
	Err error
	// Line is the line number where the error occurred.
	Line int
}

type ParseResult struct {
	// Ranges is the slice of successfully parsed IP ranges.
	Ranges []IPRange
	// Errors is a slice of errors encountered during parsing.
	Errors []ParseError
	// Stats contains statistics about the parsing process.
	Stats Stats
}

type Stats struct {
	// LastUpdate is the timestamp of the last successful data load or reload.
	LastUpdate time.Time `json:"last_update"`
	// LoadTime is the duration it took to load the dataset.
	LoadTime time.Duration `json:"load_time"`
	// FileSize is the size of the source data file in bytes.
	FileSize int64 `json:"file_size"`
	// CacheHits is the number of times a lookup was served from the cache.
	CacheHits int64 `json:"cache_hits"`
	// CacheMisses is the number of times a lookup was not found in the cache.
	CacheMisses int64 `json:"cache_misses"`
	// TotalRanges is the number of IP ranges or entries currently loaded.
	TotalRanges int `json:"total_ranges"`
}