netaddr 1.0.0

data/lib/net_addr.rb

@@ -0,0 +1,26 @@
+=begin rdoc
+ Copyright (c) 2006 Dustin Spinhirne (www.spinhirne.com)
+  
+ Licensed under the same terms as Ruby, No Warranty is provided.
+=end
+
+
+require File.join(File.dirname(__FILE__), 'methods.rb')
+require File.join(File.dirname(__FILE__), 'cidr.rb')
+require File.join(File.dirname(__FILE__), 'tree.rb')
+require File.join(File.dirname(__FILE__), 'eui.rb')
+
+module NetAddr
+
+class BoundaryError < StandardError #:nodoc:
+end
+
+class ValidationError < StandardError #:nodoc:
+end
+
+class VersionError < StandardError #:nodoc:
+end
+
+end # module NetAddr
+
+__END__

data/lib/tree.rb

@@ -0,0 +1,880 @@
+=begin rdoc
+ Copyright (c) 2006 Dustin Spinhirne (www.spinhirne.com) 
+ 
+ Licensed under the same terms as Ruby, No Warranty is provided.
+=end
+
+module NetAddr
+
+#=Tree
+#
+#A class & series of methods for creating and manipulating IP-based
+#heirarchical trees. Both IPv4 and IPv6 are supported.
+# 
+#A sample tree would look like:
+# 192.168.1.0/24
+#   192.168.1.0/26
+#      192.168.1.0/27
+#         192.168.1.0/28
+#         192.168.1.16/29
+#            192.168.1.16/30
+#         192.168.1.24/30
+#            192.168.1.25/32
+#         192.168.1.28/30
+#      192.168.1.32/27
+#   192.168.1.64/26
+#      192.168.1.64/27
+#   192.168.1.128/26
+#   192.168.1.192/26
+#
+class Tree
+
+#==============================================================================#
+# initialize()
+#==============================================================================#
+
+#===Synopsis
+#Create a new Tree object.
+#
+# tree = NetAddr::Tree.new()
+#
+#===Arguments:
+#* none
+#
+    def initialize()
+        # root of our ordered IP tree
+        @root = NetStruct.new(nil, nil, [])
+    end
+
+#==============================================================================#
+# add!()
+#==============================================================================#
+
+#===Synopsis
+# Add a CIDR address or NetAddr::CIDR object to the tree.
+#
+# tree.add!('192.168.1.0/24')
+# cidr = NetAddr::CIDR.create(:CIDR => '192.168.1.0/24', :Tag => {:title => 'test net'}
+# tree.add!(cidr)
+#
+#===Arguments:
+#* String or NetAddr::CIDR object
+#
+#===Returns:
+#* nil
+#
+    def add!(new)
+        duplicate = false
+
+        # validate object
+        if ( !new.kind_of?(NetAddr::CIDR) )
+            begin
+                cidr = NetAddr::CIDR.create(new)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        else
+            cidr = new.dup
+        end
+
+        version = cidr.version
+        new_entry = NetStruct.new(cidr, nil, [])
+
+        # find cidr's parent
+        new_entry.parent = find_parent(cidr, @root)
+
+        # check parent for subnets of cidr
+        new_entry.parent.children.each do |old_entry|
+            if (old_entry.cidr.version == version)
+                comp = cidr.cmp(old_entry.cidr)
+                if (comp && comp == 1)
+                    old_entry.parent = new_entry
+                    new_entry.children.push(old_entry)
+                elsif (comp && comp == 0)
+                    duplicate = true
+                    break
+                end
+            end
+        end
+
+        if (!duplicate)
+            new_entry.children.each do |old_entry|
+                new_entry.parent.children.delete(old_entry)
+            end
+
+            # add new object as an ordered entry to parent.children
+            add_to_parent(new_entry,new_entry.parent)
+        end
+
+        return(nil)
+    end
+
+#==============================================================================#
+# ancestors()
+#==============================================================================#
+
+#===Synopsis
+# Returns all the ancestors of the provided CIDR addresses.
+#
+# puts tree.ancestors('192.168.1.0/27')
+#
+#===Arguments:
+#* String or NetAddr::CIDR object
+#
+#===Returns:
+#* Array of NetAddr::CIDR objects
+#
+    def ancestors(cidr)
+        # validate object
+        if ( !cidr.kind_of?(NetAddr::CIDR) )
+            begin
+                cidr = NetAddr::CIDR.create(cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+        
+        list = []
+        parent = find_parent(cidr,@root)
+        
+        until (parent == @root)
+            list.push(parent.cidr)
+            parent = parent.parent
+        end
+
+        return(list)
+    end
+
+#==============================================================================#
+# children()
+#==============================================================================#
+
+#===Synopsis
+# Returns all the immediate children of the provided CIDR addresses.
+#
+# puts tree.children('192.168.1.0/24')
+#
+#===Arguments:
+#* String or NetAddr::CIDR object
+#
+#===Returns:
+#* Array of NetAddr::CIDR objects
+#
+    def children(cidr)
+        # validate object
+        if ( !cidr.kind_of?(NetAddr::CIDR) )
+            begin
+                cidr = NetAddr::CIDR.create(cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+
+        list = []
+        find_me(cidr).children.each do |child|
+            list.push(child.cidr)
+        end
+
+        return(list)
+    end
+
+#==============================================================================#
+# descendants
+#==============================================================================#
+
+#===Synopsis
+# Return all descendants of the provided CIDR address.
+#
+# descendants = tree.descendants('192.168.1.0/24')
+#
+#===Arguments:
+#* String or NetAddr::CIDR object
+#
+#===Returns:
+#* Array of NetAddr::CIDR objects
+#
+    def descendants(cidr)
+        list = []
+        
+        # validate object
+        if ( !cidr.kind_of?(NetAddr::CIDR) )
+            begin
+                cidr = NetAddr::CIDR.create(cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+
+        me = find_me(cidr)        
+        dump_children(me).each {|x| list.push(x[:NetStruct].cidr)} if (me)
+
+        return(list)
+    end
+
+#==============================================================================#
+# delete!()
+#==============================================================================#
+
+#===Synopsis
+# Remove the provided CIDR address from the tree.
+#
+# did_remove = tree.remove!('192.168.1.0/24')
+#
+#===Arguments:
+#* String or NetAddr::CIDR object
+#
+#===Returns:
+#* true on success or false on fail
+#
+    def delete!(cidr)
+        removed = false
+        
+        # validate object
+        if ( !cidr.kind_of?(NetAddr::CIDR) )
+            begin
+                cidr = NetAddr::CIDR.create(cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+
+        # find matching
+        me = find_me(cidr)
+        
+        # remove
+        if (me)
+            parent = me.parent
+            children = me.children 
+            parent.children.delete(me)
+            children.each {|x| add_to_parent(x,parent)}
+            removed = true
+        end
+
+        return(removed)
+    end
+
+#==============================================================================#
+# dump
+#==============================================================================#
+
+#===Synopsis
+# Dump the contents of this tree.
+#
+# dumped = tree.dump()
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* ordered array of hashes with the following fields: 
+#    :CIDR => NetAddr::CIDR object
+#    :Depth => (depth level in tree)
+#
+    def dump()
+        list = []
+        dumped = dump_children(@root)
+
+        dumped.each do |entry|
+            depth = entry[:Depth]
+            net_struct = entry[:NetStruct]
+            list.push({:Depth => depth, :CIDR => net_struct.cidr})
+        end
+
+        return(list)
+    end
+
+#==============================================================================#
+# exists?()
+#==============================================================================#
+
+#===Synopsis
+# Has a CIDR address already been added to the tree?
+#
+# added = tree.exists?('192.168.1.0/24')
+#
+#===Arguments:
+#* String or NetAddr::CIDR object
+#
+#===Returns:
+#* true or false
+#
+    def exists?(cidr)
+        found = false
+
+        # validate object
+        if ( !cidr.kind_of?(NetAddr::CIDR) )
+            begin
+                cidr = NetAddr::CIDR.create(cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+
+        found = true if (find_me(cidr))
+        return(found)
+    end
+
+#==============================================================================#
+# fill_in!()
+#==============================================================================#
+
+#===Synopsis
+# Fill in the missing subnets of a particular CIDR.
+#
+# success = tree.fill_in!('192.168.1.0/24')
+#
+#===Arguments:
+#* String or NetAddr::CIDR object
+#
+#===Returns:
+#* true or false
+#
+    def fill_in!(cidr)
+        filled = false
+
+        # validate object
+        if ( !cidr.kind_of?(NetAddr::CIDR) )
+            begin
+                cidr = NetAddr::CIDR.create(cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+
+        me = find_me(cidr)        
+        if (me && me.children.length != 0)
+            list = []
+            me.children.each {|x| list.push(x.cidr)}
+            me.cidr.fill_in(list, :Objectify => true).each do |cidr|
+                self.add!(cidr)
+            end
+            filled = true
+        end
+        return(filled)
+    end
+
+#==============================================================================#
+# find()
+#==============================================================================#
+
+#===Synopsis
+# Find and return a CIDR from within the tree.
+#
+# cidr = tree.find('192.168.1.0/24')
+#
+#===Arguments:
+#* String or NetAddr::CIDR object
+#
+#===Returns:
+#* NetAddr::CIDR object, or nil
+#
+    def find(cidr)
+        if ( !cidr.kind_of?(NetAddr::CIDR) )
+            begin
+                cidr = NetAddr::CIDR.create(:CIDR => cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+
+        return(find_me(cidr).cidr)
+    end
+
+#==============================================================================#
+# find_space()
+#==============================================================================#
+
+#===Synopsis
+# Find subnets that are of at least size X. Only subnets that are not themselves 
+# subnetted will be returned. :Subnet takes precedence over :IPCount
+#
+# subnets = tree.find_space(:IPCount => 16)
+#
+#===Arguments:
+#* Minimum subnet size in bits, or a Hash with the following keys:
+#    :Subnet - minimum subnet size in bits for returned subnets
+#    :IPCount - minimum IP count per subnet required for returned subnets
+#    :Version - restrict results to IPvX
+#
+#===Returns:
+#* Array of NetAddr::CIDR objects
+#
+    def find_space(options)
+        known_args = [:Subnet, :IPCount, :Version]
+        version = nil
+        if (options.kind_of? Integer)
+            bits4 = options
+            bits6 = options
+        elsif (options.kind_of? Hash) 
+            NetAddr.validate_args(options.keys,known_args)
+            if (options.has_key?(:Version))
+                version = options[:Version]
+                raise "IP version should be 4 or 6, but was #{version}." if (version != 4 && version !=6)
+            end
+
+            if (options.has_key?(:Subnet))
+                bits4 = options[:Subnet]
+                bits6 = options[:Subnet]
+            elsif(options.has_key?(:IPCount))
+                bits4 = NetAddr.minimum_size(options[:IPCount], :Version => 4)
+                bits6 = NetAddr.minimum_size(options[:IPCount], :Version => 6)
+            else
+                raise "Missing arguments: :Subnet/:IPCount"
+            end
+        else
+            raise "Integer or Hash expected, but #{options.class} provided."
+        end
+
+        list4 = []
+        list6 = []
+        dump_children(@root).each do |entry|
+            netstruct = entry[:NetStruct]
+            if (netstruct.cidr.version == 4)
+                if ( (netstruct.children.length == 0) && (netstruct.cidr.bits <= bits4) )
+                    list4.push(netstruct.cidr)
+                end
+            else
+                if ( (netstruct.children.length == 0) && (netstruct.cidr.bits <= bits6) )
+                    list6.push(netstruct.cidr)
+                end
+            end
+        end
+        
+        list = []
+        if (!version)
+            list.concat(list4)
+            list.concat(list6)
+        else
+            list.concat(list4) if (version == 4)
+            list.concat(list6) if (version == 6)
+        end
+
+        return(list)
+    end
+
+#==============================================================================#
+# longest_match()
+#==============================================================================#
+
+#===Synopsis
+#Find the longest matching branch of our tree to which a 
+#CIDR address belongs. Useful for performing 'routing table' style lookups.
+#
+# longest_match = tree.longest_match('192.168.1.1')
+#
+#===Arguments:
+#* String or NetAddr::CIDR object
+#
+#===Returns:
+#* NetAddr::CIDR object, or nil
+#
+    def longest_match(cidr)
+        if ( !cidr.kind_of?(NetAddr::CIDR) )
+            begin                
+                cidr = NetAddr::CIDR.create(cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+        
+        found = find_me(cidr)
+        found = find_parent(cidr, @root) if !found
+
+        return(found.cidr)
+    end
+
+#==============================================================================#
+# merge_subnets!()
+#==============================================================================#
+
+#===Synopsis
+# Merge (summarize) all subnets of the provided CIDR address.
+#
+# tree.merge_subnets!('192.168.1.0/24')
+#
+#===Arguments:
+#* String or NetAddr::CIDR object
+#
+#===Returns:
+#* true on success or false on fail
+#
+    def merge_subnets!(cidr)
+        merged = false
+        
+        # validate object
+        if ( !cidr.kind_of?(NetAddr::CIDR) )
+            begin
+                cidr = NetAddr::CIDR.create(cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+
+        me = find_me(cidr)
+        
+        if (me)
+            to_merge = []
+            me.children.each {|x| to_merge.push(x.cidr)}
+            to_merge.each {|x| delete!(x)}
+
+            NetAddr.merge(to_merge).each {|x| add!(x)}            
+            merged = true
+        end
+
+        return(merged)
+    end
+
+#==============================================================================#
+# prune!()
+#==============================================================================#
+
+#===Synopsis
+# Remove all subnets of the provided CIDR address.
+#
+# did_prune = tree.prune!('192.168.1.0/24')
+#
+#===Arguments:
+#* String or NetAddr::CIDR object
+#
+#===Returns:
+#* true on success or false on fail
+#
+    def prune!(cidr)
+        pruned = false
+        
+        # validate object
+        if ( !cidr.kind_of?(NetAddr::CIDR) )
+            begin
+                cidr = NetAddr::CIDR.create(:CIDR => cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+
+        me = find_me(cidr)
+        
+        if (me)
+            me.children.clear
+            pruned = true
+        end
+
+        return(pruned)
+    end
+
+#==============================================================================#
+# remove!()
+#==============================================================================#
+
+#===Synopsis
+# Remove the provided CIDR address, and all of its subnets from the tree.
+#
+# did_remove = tree.remove!('192.168.1.0/24')
+#
+#===Arguments:
+#* String or NetAddr::CIDR object
+#
+#===Returns:
+#* true on success or false on fail
+#
+    def remove!(cidr)
+        removed = false
+        found = nil
+        
+        # validate object
+        if ( !cidr.kind_of?(NetAddr::CIDR) )
+            begin
+                cidr = NetAddr::CIDR.create(:CIDR => cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+
+        me = find_me(cidr)
+        
+        if (me)
+            parent = me.parent
+            parent.children.delete(me)
+            removed = true
+        end
+        
+        return(removed)
+    end
+
+#==============================================================================#
+# resize!()
+#==============================================================================#
+
+#===Synopsis
+# Resize the provided CIDR address.
+#
+# resized = tree.resize!('192.168.1.0/24', 23)
+#
+#===Arguments:
+#* CIDR address as a String or an NetAddr::CIDR object
+#* Integer representing the bits of the new netmask
+#
+#===Returns:
+#* true on success or false on fail
+#
+    def resize!(cidr,bits)
+        resized = false
+        
+        # validate cidr
+        if ( !cidr.kind_of?(NetAddr::CIDR) )
+            begin
+                cidr = NetAddr::CIDR.create(:CIDR => cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+
+        me = find_me(cidr)
+        
+        if (me)
+            new = me.cidr.resize(bits)
+            delete!(me.cidr)
+            add!(new)
+            resized = true
+        end
+        
+        return(resized)
+    end
+
+#==============================================================================#
+# root()
+#==============================================================================#
+
+#===Synopsis
+# Returns the root of the provided CIDR address.
+#
+# puts tree.root('192.168.1.32/27')
+#
+#===Arguments:
+#* String or NetAddr::CIDR object
+#
+#===Returns:
+#* NetAddr::CIDR object
+#
+    def root(cidr)
+        # validate object
+        if ( !cidr.kind_of?(NetAddr::CIDR) )
+            begin
+                cidr = NetAddr::CIDR.create(cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+        
+        parent = find_parent(cidr,@root)
+        
+        if (parent && parent != @root)
+            until (parent.parent == @root)
+                parent = parent.parent
+            end
+        end
+
+        return(parent.cidr)
+    end
+
+#==============================================================================#
+# show()
+#==============================================================================#
+
+#===Synopsis
+# Print the tree in a nicely formatted string.
+#
+# puts tree.show()
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* String
+#
+    def show()
+        printed = ""
+        list = dump_children(@root)
+
+        list.each do |entry|
+            cidr = entry[:NetStruct].cidr
+            depth = entry[:Depth]
+
+            if (depth == 0)
+                indent = ""
+            else
+                indent = " " * (depth*3)
+            end
+
+            printed << "#{indent}#{cidr.desc(:Short => true)}\n"
+        end
+
+        return(printed)
+    end
+
+#==============================================================================#
+# siblings()
+#==============================================================================#
+
+#===Synopsis
+# Return list of the sibling CIDRs of the provided CIDR address.
+#
+# puts tree.siblings('192.168.1.0/27')
+#
+#===Arguments:
+#* String or NetAddr::CIDR object
+#
+#===Returns:
+#* Array of NetAddr::CIDR objects
+#
+    def siblings(cidr)
+        # validate object
+        if ( !cidr.kind_of?(NetAddr::CIDR) )
+            begin
+                cidr = NetAddr::CIDR.create(cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+        
+        list = []
+        find_parent(cidr,@root).children.each do |entry|
+            if (!cidr.cmp(entry.cidr))
+                list.push(entry.cidr)
+            end
+        end
+
+        return(list)
+    end
+
+#==============================================================================#
+# supernets()
+#==============================================================================#
+
+#===Synopsis
+# Return list of the top-level supernets of this tree.
+#
+# supernets = tree.supernets()
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* Array of NetAddr::CIDR objects
+#
+    def supernets()
+       supernets = []
+       @root.children.each {|x| supernets.push(x.cidr)}
+       return (supernets)
+    end
+
+
+# PRIVATE INSTANCE METHODS
+private
+
+#==============================================================================#
+# add_to_parent() private
+#==============================================================================#
+
+# Add NetStruct object to an array of NetStruct's
+#
+    def add_to_parent(new_entry, parent)       
+        index = 0
+        parent.children.each do
+            if(new_entry.cidr.packed_network < parent.children[index].cidr.packed_network)
+                break
+            end
+            index += 1
+        end
+
+        parent.children.insert(index, new_entry)
+
+        return()
+    end
+
+#==============================================================================#
+# dump_children() private
+#==============================================================================#
+
+#  Dump contents of an Array of NetStruct objects
+#
+    def dump_children(parent,depth=nil)
+        list = []
+        depth = 0 if (!depth)
+
+        parent.children.each do |entry|
+            list.push({:NetStruct => entry, :Depth => depth})
+
+            if (entry.children.length > 0)
+                list.concat( dump_children(entry, (depth+1) ) )
+            end
+        end
+
+        return(list)
+    end
+
+#==============================================================================#
+# find_me() private
+#==============================================================================#
+
+# Find the NetStruct to which a cidr belongs.
+#
+    def find_me(cidr)
+        me = nil
+        
+        # find matching
+        parent = find_parent(cidr,@root)
+        parent.children.each do |entry|
+            if (entry.cidr.version == cidr.version)
+                if (entry.cidr.cmp(cidr) == 0)
+                    me = entry
+                    break
+                end
+            end
+        end
+
+        return(me)
+    end
+
+#==============================================================================#
+# find_parent() private
+#==============================================================================#
+
+# Find the parent NetStruct to which a child NetStruct belongs.
+#
+    def find_parent(cidr,parent)
+        version = cidr.version
+
+        parent.children.each do |entry|
+            if (entry.cidr.version == version && entry.cidr.contains?(cidr))
+                parent = entry
+
+                if (parent.children.length > 0)
+                    search_results = find_parent(cidr,parent)
+                    parent = search_results if (search_results)
+                end
+                break
+            end
+        end
+
+        return(parent)
+    end
+
+end # class Tree
+
+end # module NetAddr
+__END__