CIDRanger

https://github.com/yl2chen/cidranger
Admin
CIDRanger is a fast IP to CIDR block lookup library using a path-compressed trie data structure in...
Tokens:5,212
Snippets:30
Trust Score:7.9
License:MIT
Update:8 months ago
Show doc for...
Tokens:
Raw
### Get Total Network Count with cidranger in Go

Source: https://context7.com/yl2chen/cidranger/llms.txt

Demonstrates how to get the total count of networks (both IPv4 and IPv6) stored in the ranger. This example inserts a mix of IPv4 and IPv6 CIDR blocks and then uses the `Len()` method to retrieve the total count.

```go
package main

import (
    "fmt"
    "net"

    "github.com/yl2chen/cidranger"
)

func main() {
    ranger := cidranger.NewPCTrieRanger()

    // Insert mixed IPv4 and IPv6
    cidrs := []string{
        "10.0.0.0/8",
        "172.16.0.0/12",
        "192.168.0.0/16",
        "2001:db8::/32",
        "fc00::/7",
    }

    for _, cidr := range cidrs {
        _, network, _ := net.ParseCIDR(cidr)
        ranger.Insert(cidranger.NewBasicRangerEntry(*network))
    }

    fmt.Printf("Total networks in ranger: %d\n", ranger.Len())
}

```

--------------------------------

### Get All Networks Within a Range using CIDR Ranger

Source: https://context7.com/yl2chen/cidranger/llms.txt

Retrieves all stored CIDR blocks that are completely contained within a specified network. This function is useful for identifying sub-networks. It utilizes the `cidranger` library and requires the `net` package for IP network parsing.

```go
package main

import (
    "fmt"
    "net"

    "github.com/yl2chen/cidranger"
)

func main() {
    ranger := cidranger.NewPCTrieRanger()

    // Insert various networks
    networks := []string{
        "192.168.1.0/24",
        "192.168.2.0/24",
        "192.168.3.0/24",
        "10.0.0.0/24",
    }

    for _, cidr := range networks {
        _, network, _ := net.ParseCIDR(cidr)
        ranger.Insert(cidranger.NewBasicRangerEntry(*network))
    }

    // Find all networks covered by 192.168.0.0/16
    _, searchNet, _ := net.ParseCIDR("192.168.0.0/16")
    covered, err := ranger.CoveredNetworks(*searchNet)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Networks within 192.168.0.0/16:\n")
    for _, entry := range covered {
        fmt.Printf("  - %s\n", entry.Network().String())
    }
    // Output:
    // Networks within 192.168.0.0/16:
    //   - 192.168.1.0/24
    //   - 192.168.2.0/24
    //   - 192.168.3.0/24

    // Get all IPv4 networks using AllIPv4
    allIPv4, _ := ranger.CoveredNetworks(*cidranger.AllIPv4)
    fmt.Printf("Total IPv4 networks: %d\n", len(allIPv4))
    // Output: Total IPv4 networks: 4
}

```

--------------------------------

### Handle IPv6 Networks with cidranger in Go

Source: https://context7.com/yl2chen/cidranger/llms.txt

Demonstrates how to insert, check containment, and retrieve IPv6 networks using the cidranger library. It utilizes `net.ParseCIDR` for network parsing and `cidranger.NewPCTrieRanger` for efficient storage and lookup.

```go
package main

import (
    "fmt"
    "net"

    "github.com/yl2chen/cidranger"
)

func main() {
    ranger := cidranger.NewPCTrieRanger()

    // Insert IPv6 networks
    ipv6Networks := []string{
        "2001:db8::/32",
        "2001:db8:1234::/48",
        "2620:107:300f::/48",
        "2400:6500::/32",
    }

    for _, cidr := range ipv6Networks {
        _, network, _ := net.ParseCIDR(cidr)
        ranger.Insert(cidranger.NewBasicRangerEntry(*network))
    }

    // Check IPv6 containment
    ipv6 := net.ParseIP("2001:db8:1234::1")
    contains, _ := ranger.Contains(ipv6)
    fmt.Printf("2001:db8:1234::1 contained: %v\n", contains)

    // Get containing networks for IPv6
    entries, _ := ranger.ContainingNetworks(ipv6)
    fmt.Printf("Matching IPv6 networks:\n")
    for _, entry := range entries {
        fmt.Printf("  - %s\n", entry.Network().String())
    }

    // Get all IPv6 networks
    allIPv6, _ := ranger.CoveredNetworks(*cidranger.AllIPv6)
    fmt.Printf("Total IPv6 networks: %d\n", len(allIPv6))
}

```

--------------------------------

### Create New PCTrieRanger Instance - Go

Source: https://context7.com/yl2chen/cidranger/llms.txt

Demonstrates how to initialize a new cidranger.PCTrieRanger, which is optimized for fast IP to CIDR block lookups. This ranger supports both IPv4 and IPv6 and automatically manages internal trie structures.

```go
package main

import (
    "fmt"
    "net"

    "github.com/yl2chen/cidranger"
)

func main() {
    // Create a new ranger instance
    ranger := cidranger.NewPCTrieRanger()

    // The ranger is ready to accept CIDR blocks
    fmt.Printf("Ranger created, current size: %d\n", ranger.Len())
    // Output: Ranger created, current size: 0
}
```

--------------------------------

### Initialize and Insert CIDR Blocks with cidranger

Source: https://github.com/yl2chen/cidranger/blob/master/README.md

Demonstrates how to initialize a new Path-Compressed Trie Ranger and insert CIDR blocks. It uses Go's standard `net` package for parsing IP networks and `cidranger`'s `NewBasicRangerEntry` to create entries for insertion. Custom structs implementing `RangerEntry` can also be used to attach additional data.

```go
import (
  "net"

  "github.com/yl2chen/cidranger"
)

// Create a new ranger implemented using Path-Compressed prefix trie.
ranger := cidranger.NewPCTrieRanger()

// Inserts CIDR blocks.
_, network1, _ := net.ParseCIDR("192.168.1.0/24")
_, network2, _ := net.ParseCIDR("128.168.1.0/24")
ranger.Insert(cidranger.NewBasicRangerEntry(*network1))
ranger.Insert(cidranger.NewBasicRangerEntry(*network2))
```

--------------------------------

### Attach Custom Data to Networks using Custom RangerEntry

Source: https://context7.com/yl2chen/cidranger/llms.txt

Demonstrates how to implement the `RangerEntry` interface to associate custom metadata, such as ASN, region, or service name, with CIDR blocks. This allows for richer data retrieval when looking up IP addresses. It requires the `cidranger` and `net` packages.

```go
package main

import (
    "fmt"
    "net"

    "github.com/yl2chen/cidranger"
)

// Custom entry with ASN information
type asnEntry struct {
    ipNet   net.IPNet
    asn     string
    owner   string
}

func (e *asnEntry) Network() net.IPNet {
    return e.ipNet
}

func newASNEntry(cidr, asn, owner string) cidranger.RangerEntry {
    _, network, _ := net.ParseCIDR(cidr)
    return &asnEntry{
        ipNet: *network,
        asn:   asn,
        owner: owner,
    }
}

func main() {
    ranger := cidranger.NewPCTrieRanger()

    // Insert entries with custom data
    ranger.Insert(newASNEntry("52.95.110.0/24", "AS16509", "Amazon"))
    ranger.Insert(newASNEntry("35.192.0.0/12", "AS15169", "Google"))
    ranger.Insert(newASNEntry("13.64.0.0/11", "AS8075", "Microsoft"))

    // Lookup and retrieve custom data
    ip := net.ParseIP("52.95.110.50")
    entries, err := ranger.ContainingNetworks(ip)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    for _, entry := range entries {
        // Type assert to access custom fields
        if asnData, ok := entry.(*asnEntry); ok {
            fmt.Printf("IP %s belongs to:\n", ip)
            fmt.Printf("  Network: %s\n", asnData.Network().String())
            fmt.Printf("  ASN: %s\n", asnData.asn)
            fmt.Printf("  Owner: %s\n", asnData.owner)
        }
    }
    // Output:
    // IP 52.95.110.50 belongs to:
    //   Network: 52.95.110.0/24
    //   ASN: AS16509
    //   Owner: Amazon
}

```

--------------------------------

### Benchmark Performance: cidranger vs Brute Force IP Lookup

Source: https://github.com/yl2chen/cidranger/blob/master/README.md

Provides benchmark results comparing the performance of `cidranger`'s path-compressed trie implementation against a brute-force approach for both IPv4 and IPv6 lookups in hit and miss scenarios. The benchmarks use a dataset of published AWS IP ranges.

```go
// Ipv4 lookup hit scenario
BenchmarkPCTrieHitIPv4UsingAWSRanges-4         	 5000000	       353   ns/op
BenchmarkBruteRangerHitIPv4UsingAWSRanges-4    	  100000	     13719   ns/op

// Ipv6 lookup hit scenario, counter-intuitively faster then IPv4 due to less IPv6 CIDR
// blocks in the AWS dataset, hence the constructed trie has less path splits and depth.
BenchmarkPCTrieHitIPv6UsingAWSRanges-4         	10000000	       143   ns/op
BenchmarkBruteRangerHitIPv6UsingAWSRanges-4    	  300000	      5178   ns/op

// Ipv4 lookup miss scenario
BenchmarkPCTrieMissIPv4UsingAWSRanges-4        	20000000	        96.5 ns/op
BenchmarkBruteRangerMissIPv4UsingAWSRanges-4   	   50000	     24781   ns/op

// Ipv6 lookup miss scenario
BenchmarkPCTrieHMissIPv6UsingAWSRanges-4       	10000000	       115   ns/op
BenchmarkBruteRangerMissIPv6UsingAWSRanges-4   	  100000	     10824   ns/op
```

--------------------------------

### Retrieve All Matching CIDR Blocks for an IP - Go

Source: https://context7.com/yl2chen/cidranger/llms.txt

Demonstrates the use of ContainingNetworks to retrieve all CIDR blocks that contain a specific IP address. This is useful for scenarios with overlapping network ranges, returning matches in ascending prefix order.

```go
package main

import (
    "fmt"
    "net"

    "github.com/yl2chen/cidranger"
)

func main() {
    ranger := cidranger.NewPCTrieRanger()

    // Insert overlapping networks
    _, network1, _ := net.ParseCIDR("10.0.0.0/8")     // Broad range
    _, network2, _ := net.ParseCIDR("10.1.0.0/16")   // More specific
    _, network3, _ := net.ParseCIDR("10.1.1.0/24")   // Most specific

    ranger.Insert(cidranger.NewBasicRangerEntry(*network1))
    ranger.Insert(cidranger.NewBasicRangerEntry(*network2))
    ranger.Insert(cidranger.NewBasicRangerEntry(*network3))

    // Find all networks containing this IP
    ip := net.ParseIP("10.1.1.50")
    entries, err := ranger.ContainingNetworks(ip)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Networks containing %s:\n", ip)
    for _, entry := range entries {
        fmt.Printf("  - %s\n", entry.Network().String())
    }
    // Output:
    // Networks containing 10.1.1.50:
    //   - 10.0.0.0/8
    //   - 10.1.0.0/16
    //   - 10.1.1.0/24
}
```

--------------------------------

### Insert CIDR Blocks into Ranger - Go

Source: https://context7.com/yl2chen/cidranger/llms.txt

Shows how to add CIDR blocks (network ranges) to a cidranger.PCTrieRanger. It utilizes NewBasicRangerEntry for standard network storage and demonstrates inserting both IPv4 and IPv6 networks.

```go
package main

import (
    "fmt"
    "net"

    "github.com/yl2chen/cidranger"
)

func main() {
    ranger := cidranger.NewPCTrieRanger()

    // Parse and insert CIDR blocks
    _, network1, _ := net.ParseCIDR("192.168.1.0/24")
    _, network2, _ := net.ParseCIDR("10.0.0.0/8")
    _, network3, _ := net.ParseCIDR("2001:db8::/32") // IPv6

    err := ranger.Insert(cidranger.NewBasicRangerEntry(*network1))
    if err != nil {
        fmt.Printf("Insert error: %v\n", err)
        return
    }

    ranger.Insert(cidranger.NewBasicRangerEntry(*network2))
    ranger.Insert(cidranger.NewBasicRangerEntry(*network3))

    fmt.Printf("Total networks stored: %d\n", ranger.Len())
    // Output: Total networks stored: 3
}
```

--------------------------------

### Retrieve All Stored CIDR Networks with cidranger

Source: https://github.com/yl2chen/cidranger/blob/master/README.md

Illustrates how to fetch all CIDR blocks currently stored within the ranger. The `CoveredNetworks` method can be used for both IPv4 and IPv6 address families, accepting predefined constants like `*AllIPv4` or `*AllIPv6`.

```go
entries, err := ranger.CoveredNetworks(*cidranger.AllIPv4) // for IPv4
entries, err := ranger.CoveredNetworks(*cidranger.AllIPv6) // for IPv6
```

--------------------------------

### Retrieve Containing CIDR Networks with cidranger

Source: https://github.com/yl2chen/cidranger/blob/master/README.md

Demonstrates how to retrieve all CIDR networks that contain a specific IP address. The `ContainingNetworks` method returns a slice of `RangerEntry` interfaces, each representing a network that includes the queried IP, along with any potential errors.

```go
containingNetworks, err := ranger.ContainingNetworks(net.ParseIP("128.168.1.0"))
```

--------------------------------

### Check IP Containment within CIDR Blocks - Go

Source: https://context7.com/yl2chen/cidranger/llms.txt

Illustrates how to use the Contains method of cidranger.PCTrieRanger to efficiently check if a given IP address falls within any of the previously inserted CIDR blocks. This is a core, fast lookup operation.

```go
package main

import (
    "fmt"
    "net"

    "github.com/yl2chen/cidranger"
)

func main() {
    ranger := cidranger.NewPCTrieRanger()

    // Insert AWS Route53 CIDR block
    _, network, _ := net.ParseCIDR("52.95.110.0/24")
    ranger.Insert(cidranger.NewBasicRangerEntry(*network))

    // Check containment
    ip1 := net.ParseIP("52.95.110.1")
    ip2 := net.ParseIP("192.168.1.1")

    contains1, err := ranger.Contains(ip1)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    contains2, _ := ranger.Contains(ip2)

    fmt.Printf("52.95.110.1 is in AWS range: %v\n", contains1)
    fmt.Printf("192.168.1.1 is in AWS range: %v\n", contains2)
    // Output:
    // 52.95.110.1 is in AWS range: true
    // 192.168.1.1 is in AWS range: false
}
```

--------------------------------

### Check IP Containment within CIDR Blocks using cidranger

Source: https://github.com/yl2chen/cidranger/blob/master/README.md

Shows how to check if a given IP address is contained within any of the CIDR blocks stored in the ranger. It utilizes the `Contains` method, which returns a boolean indicating containment and an error if any occurred during the IP parsing or lookup process.

```go
contains, err := ranger.Contains(net.ParseIP("128.168.1.0")) // returns true, nil
contains, err = ranger.Contains(net.ParseIP("192.168.2.0")) // returns false, nil
```

--------------------------------

### Remove CIDR Blocks from Ranger using CIDR Ranger

Source: https://context7.com/yl2chen/cidranger/llms.txt

Deletes a specified network from the ranger and returns the removed entry. The function automatically applies path compression to maintain an optimal trie structure. It requires the `cidranger` and `net` packages.

```go
package main

import (
    "fmt"
    "net"

    "github.com/yl2chen/cidranger"
)

func main() {
    ranger := cidranger.NewPCTrieRanger()

    // Insert networks
    _, network1, _ := net.ParseCIDR("192.168.1.0/24")
    _, network2, _ := net.ParseCIDR("192.168.2.0/24")

    ranger.Insert(cidranger.NewBasicRangerEntry(*network1))
    ranger.Insert(cidranger.NewBasicRangerEntry(*network2))

    fmt.Printf("Before removal: %d networks\n", ranger.Len())

    // Remove a network
    removedEntry, err := ranger.Remove(*network1)
    if err != nil {
        fmt.Printf("Remove error: %v\n", err)
        return
    }

    if removedEntry != nil {
        fmt.Printf("Removed: %s\n", removedEntry.Network().String())
    }

    fmt.Printf("After removal: %d networks\n", ranger.Len())
    // Output:
    // Before removal: 2 networks
    // Removed: 192.168.1.0/24
    // After removal: 1 networks
}

```
Tokens:
Raw