Documentation
¶
Overview ¶
Package ipmatcher provides high-performance IP address matching using the bart radix tree library. It supports both IPv4 and IPv6 addresses, CIDR notation, and provides thread-safe operations for concurrent access.
Key features: - High-performance IP matching using bart radix trees - Support for both IPv4 and IPv6 addresses - CIDR notation support for network ranges - Thread-safe operations with RWMutex - Separate whitelist and blocklist trees - Efficient memory usage and fast lookup times
Index ¶
- type IPMatcher
- func (m *IPMatcher) ClearBlocklist()
- func (m *IPMatcher) ClearWhitelist()
- func (m *IPMatcher) EnableDebugTracking(enable bool)
- func (m *IPMatcher) GetBlocklistEntries() []string
- func (m *IPMatcher) GetBlocklistSize() int
- func (m *IPMatcher) GetWhitelistEntries() []string
- func (m *IPMatcher) GetWhitelistSize() int
- func (m *IPMatcher) IsBlocked(ipStr string) (bool, string, error)
- func (m *IPMatcher) LoadBlocklist(entries []string) error
- func (m *IPMatcher) LoadWhitelist(entries []string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type IPMatcher ¶
type IPMatcher struct {
// contains filtered or unexported fields
}
IPMatcher provides high-performance IP address matching using bart radix trees. It maintains separate trees for whitelist and blocklist entries, allowing efficient lookup and prioritizing whitelist checks over blocklist checks.
The IPMatcher is thread-safe and can be used concurrently from multiple goroutines. It uses RWMutex to allow concurrent reads while ensuring exclusive access during writes.
func NewIPMatcher ¶
func NewIPMatcher() *IPMatcher
NewIPMatcher creates a new IPMatcher instance with empty whitelist and blocklist trees. The trees are initialized but contain no entries.
Returns:
*IPMatcher - A new IPMatcher instance ready for use
Example:
matcher := NewIPMatcher() err := matcher.LoadWhitelist(whitelistEntries) err := matcher.LoadBlocklist(blocklistEntries)
func (*IPMatcher) ClearBlocklist ¶
func (m *IPMatcher) ClearBlocklist()
ClearBlocklist clears all entries from the blocklist. This is useful when blocklist changes are detected and the entire blocklist needs to be reloaded.
This function is thread-safe and acquires a write lock to ensure exclusive access during the clear operation.
func (*IPMatcher) ClearWhitelist ¶
func (m *IPMatcher) ClearWhitelist()
ClearWhitelist clears all entries from the whitelist. This is useful when whitelist changes are detected and the entire whitelist needs to be reloaded.
This function is thread-safe and acquires a write lock to ensure exclusive access during the clear operation.
func (*IPMatcher) EnableDebugTracking ¶
EnableDebugTracking enables tracking of loaded entries for debugging This should be called before loading any entries to ensure they are tracked
func (*IPMatcher) GetBlocklistEntries ¶
GetBlocklistEntries returns the loaded blocklist entries (for debugging) Returns nil if debug tracking is not enabled
func (*IPMatcher) GetBlocklistSize ¶
GetBlocklistSize returns the number of entries in the blocklist. This is useful for monitoring and debugging the size of the blocklist.
Returns:
int - Number of entries in the blocklist
This function is thread-safe and can be called concurrently.
func (*IPMatcher) GetWhitelistEntries ¶
GetWhitelistEntries returns the loaded whitelist entries (for debugging) Returns nil if debug tracking is not enabled
func (*IPMatcher) GetWhitelistSize ¶
GetWhitelistSize returns the number of entries in the whitelist. This is useful for monitoring and debugging the size of the whitelist.
Returns:
int - Number of entries in the whitelist
This function is thread-safe and can be called concurrently.
func (*IPMatcher) IsBlocked ¶
IsBlocked checks if an IP is blocked or whitelisted. This is the main lookup function that performs the actual IP matching.
The function: - Acquires a read lock for thread-safe access - Parses the IP address - Checks whitelist first (whitelist takes precedence over blocklist) - Checks blocklist if not whitelisted - Returns whether the IP is blocked, the reason, and any error
Parameters:
ipStr - The IP address to check (IPv4 or IPv6)
Returns:
bool - true if the IP is blocked, false if allowed string - Reason for the decision: - "whitelisted" if the IP is in the whitelist - "matched IP <ip>" if the IP is in the blocklist - empty string if the IP is neither blocked nor whitelisted error - Any error that occurred during parsing
Example:
blocked, reason, err := matcher.IsBlocked("198.51.100.1")
func (*IPMatcher) LoadBlocklist ¶
LoadBlocklist loads IP addresses and CIDR blocks into the blocklist. This replaces any existing blocklist entries with the new ones.
The function: - Acquires a write lock for thread safety - Clears the existing blocklist - Parses and adds each entry to the blocklist tree - Supports both single IP addresses and CIDR notation - Skips empty lines and comments
Parameters:
entries - List of IP addresses or CIDR blocks to add to blocklist
Returns:
error - Any error that occurred during parsing or insertion
Example:
err := matcher.LoadBlocklist([]string{"198.51.100.1", "2001:db8::/32", "203.0.113.0/24"})
func (*IPMatcher) LoadWhitelist ¶
LoadWhitelist loads IP addresses and CIDR blocks into the whitelist. This replaces any existing whitelist entries with the new ones.
The function: - Acquires a write lock for thread safety - Clears the existing whitelist - Parses and adds each entry to the whitelist tree - Supports both single IP addresses and CIDR notation - Skips empty lines and comments
Parameters:
entries - List of IP addresses or CIDR blocks to add to whitelist
Returns:
error - Any error that occurred during parsing or insertion
Example:
err := matcher.LoadWhitelist([]string{"198.51.100.1", "2001:db8::/32", "203.0.113.0/24"})
Source Files