radixtarget 4.2.0

Fast radix tree for IP addresses and DNS names

RadixTarget

RadixTarget is a performant radix implementation designed for quick lookups of IP addresses/networks and DNS hostnames.

RadixTarget is:

• Written in Rust with Python bindings
• Capable of ~1,000,000 lookups per second regardless of database size
• 100% test coverage
• Available as both a Rust crate and Python package
• Used by:
  • BBOT
  • cloudcheck

Python

Installation

pip install radixtarget

Usage

from radixtarget import RadixTarget

rt = RadixTarget()

# IPv4
rt.add("192.168.1.0/24")
rt.get("192.168.1.10") # IPv4Network("192.168.1.0/24")
rt.get("192.168.2.10") # None

# IPv6
rt.add("dead::/64")
rt.get("dead::beef") # IPv6Network("dead::/64")
rt.get("dead:cafe::beef") # None

# DNS
rt.add("net")
rt.add("www.example.com")
rt.add("test.www.example.com")
rt.get("net") # "net"
rt.get("evilcorp.net") # "net"
rt.get("www.example.com") # "www.example.com"
rt.get("asdf.test.www.example.com") # "test.www.example.com"
rt.get("example.com") # None

# Custom data nodes
rt.add("evilcorp.co.uk", "custom_data")
rt.get("www.evilcorp.co.uk") # "custom_data"

# Insertion returns unique identifier
insertion_id = rt.insert("10.0.0.1/8")
assert insertion_id == "10.0.0.0/8"

# insert() raises ValueError for invalid input
try:
    rt.insert("http://example.com")
except ValueError:
    pass  # Invalid characters in hostname

# Store custom data with any entry
rt.insert("example.org", data={"tags": ["production"], "priority": 1})
result = rt.get("api.example.org")
# result contains your custom data: {"tags": ["production"], "priority": 1}

API Differences: Python vs Rust

Both APIs provide an insert() method that returns a unique string identifier for each entry (a normalized version of the hostname or IP address). However, the Python API includes additional functionality:

• Rust: insert() returns a string that uniquely identifies the insertion
• Python: insert() also returns this unique identifier string, but additionally supports a data= parameter that allows you to store custom data of any Python type alongside the entry. When you later call get(), it returns your custom data instead of just the matched target string.

This makes the Python API more flexible for applications that need to associate metadata with targets, while the Rust API focuses on pure performance for lookups.

Rust

Installation

cargo add radixtarget

Usage

use radixtarget::{RadixTarget, ScopeMode};
use std::collections::HashSet;

// Create a new RadixTarget
let mut rt = RadixTarget::new(&[], ScopeMode::Normal);

// IPv4 networks and addresses
rt.insert("192.168.1.0/24"); 
assert_eq!(rt.get("192.168.1.100"), Some("192.168.1.0/24".to_string()));
assert_eq!(rt.get("192.168.2.100"), None);

// insert() returns Result - Ok with normalized identifier or Err for invalid input
assert!(rt.insert("10.0.0.0/8").is_ok());
assert!(rt.insert("http://example.com").is_err());

// IPv6 networks and addresses  
rt.insert("dead::/64");
assert_eq!(rt.get("dead::beef"), Some("dead::/64".to_string()));
assert_eq!(rt.get("cafe::beef"), None);

// DNS hostnames
rt.insert("example.com");
rt.insert("api.test.www.example.com");
assert_eq!(rt.get("example.com"), Some("example.com".to_string()));
assert_eq!(rt.get("subdomain.api.test.www.example.com"), 
           Some("api.test.www.example.com".to_string()));

// Check if target contains a value
assert!(rt.contains("192.168.1.50"));
assert!(rt.contains("dead::1234"));
assert!(rt.contains("example.com"));

// Get all hosts
let hosts: HashSet<String> = rt.hosts();
println!("All hosts: {:?}", hosts);

// Delete targets
assert!(rt.delete("192.168.1.0/24"));
assert!(!rt.delete("192.168.1.0/24")); // false - already deleted

// Utility operations
println!("Number of hosts: {}", rt.len());
println!("Is empty: {}", rt.is_empty());

// Prune dead nodes (returns number of pruned nodes)
let pruned_count = rt.prune();

// Defragment overlapping networks (returns (cleaned, new) hosts)
let (cleaned_hosts, new_hosts) = rt.defrag();

Scope Modes

RadixTarget supports different scope modes for DNS matching:

use radixtarget::{RadixTarget, ScopeMode};

// Normal mode: standard radix tree behavior (default)
let mut rt_normal = RadixTarget::new(&[], ScopeMode::Normal);
rt_normal.insert("example.com");
assert_eq!(rt_normal.get("subdomain.example.com"), Some("example.com".to_string()));

// Strict mode: exact matching only
let mut rt_strict = RadixTarget::new(&[], ScopeMode::Strict);
rt_strict.insert("example.com");
assert_eq!(rt_strict.get("example.com"), Some("example.com".to_string()));
assert_eq!(rt_strict.get("subdomain.example.com"), None); // No subdomain matching

// ACL mode: Same behavior as normal, but keeps only the highest parent subnet for efficiency
let mut rt_acl = RadixTarget::new(&[], ScopeMode::Acl);
rt_acl.insert("192.168.1.0/24");
rt_acl.insert("192.168.1.0/28");
// Least specific match is returned instead of most specific
assert_eq!(rt_acl.get("192.168.1.1"), Some("192.168.1.0/24".to_string()));

Initialization with Hosts

use radixtarget::{RadixTarget, ScopeMode};

// Initialize with existing hosts
let hosts = vec!["192.168.1.0/24", "example.com", "dead::/64"];
let rt = RadixTarget::new(&hosts, ScopeMode::Normal);

assert!(rt.contains("192.168.1.100"));
assert!(rt.contains("subdomain.example.com"));
assert!(rt.contains("dead::beef"));

Development

Running Tests

# Rust tests
cargo test --verbose --all-features

# Python tests
uv run pytest

Linting

# Run clippy
cargo clippy --all-targets --all-features -- -D warnings

# Check formatting
cargo fmt --all -- --check

# Python linting
uv run ruff check && uv run ruff format