better_ipaddr 0.1.2

data/README.md

@@ -0,0 +1,118 @@
+# BetterIpaddr
+
+[![Gem Version](https://badge.fury.io/rb/better_ipaddr.svg)](https://rubygems.org/gems/better_ipaddr)
+[![Build Status](https://travis-ci.org/bjmllr/better_ipaddr.svg)](https://travis-ci.org/bjmllr/better_ipaddr)
+
+The `IPAddr` class that network engineers always wanted.
+
+```ruby
+require "better_ipaddr"
+addr = IPAddr::V4[some_source] # shortcut for .new, because your test suite
+                               #   contains a zillion IP addresses and you're
+                               #   tired of typing Socket::AF_INET
+addr.host?                     # is it a host address?
+addr.network?                  # or a network address?
+addr.cidr                      # what is the CIDR representation?
+addr.grow(1)                   # what is the next larger enclosing network?
+addr + 1                       # what address comes after this one?
+addr.size                      # how many host addresses fit in this network?
+addr.mask_addr                 # what's the netmask (as an integer)?
+addr.prefix_length             # what's the prefix length (as an integer)?
+addr == other_addr             # are these the same network?
+addr.cover?(other_addr)        # does this network contain that one?
+addr.overlap?(other_addr)      # do these networks share any hosts?
+addr.each { ... }              # do something with each host in this network
+addr.first                     # what's the network address?
+addr.last                      # what's the broadcast address?
+addr.wildcard                  # what's the wildcard mask for this network?
+addr.summarize_with(other)     # can these networks be summarized?
+```
+
+Bonus: comes with an IP space finder.
+
+```ruby
+require "better_ipaddr/space"
+space = BetterIpaddr::Space.new(some_array_of_ipaddrs,
+                                space: IPAddr::V4["10.0.0.0/8"])
+
+space.find_by_minimum_prefix_length(26) # => a subnet with at least 64 addresses
+space.find_by_minimum_size(256)         # => a /24 or larger
+space.gaps                              # => all your free subnets
+```
+
+Coming soon: MAC addresses and their various notations.
+
+## Installation
+
+Ruby 2.0 or later is required. There are no other dependencies.
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'better_ipaddr'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install better_ipaddr
+
+## Usage
+
+There are multiple ways to load this gem.
+
+The quick and dirty way is to `require
+"better_ipaddr/core_extension"`, which adds all the additional methods
+directly to `IPAddr`. This is "monkey patching", so there may be
+unintended consequences. If you use this approach in another library
+or framework, be very clear about it with your users.
+
+```ruby
+require "better_ipaddr/core_extension"
+addr = IPAddr["1.0.0.1"]
+class_c = addr << 8 # => IPAddr::V4["1.0.0.0/24"]
+IPAddr.new("1.0.0.0/24").summarize_with(IPAddr["1.0.1.0/24"]) # => IPAddr::V4["1.0.0.0/23"]
+```
+
+The recommended way is to `require "better_ipaddr"` and use
+the `IPAddr` subclasses explicitly.
+
+```ruby
+require "better_ipaddr"
+addr = IPAddr::V4["1.0.0.1"]
+class_c = addr << 8 # => IPAddr::V4["1.0.0.0/24"]
+```
+
+Another way is to `require "better_ipaddr/methods"` and mix
+`BetterIpaddr::InstanceMethods` into your own class which implements
+the rest of the `IPAddr` API, or into individual `IPAddr` objects.
+
+`BetterIpaddr::Space`, a collection class for dealing with sets of network addresses, is also available but not loaded by default.
+
+```ruby
+require "better_ipaddr/space"
+space = BetterIpaddr::Space.new([IPAddr::V4["10.0.0.0/24"],
+                                 IPAddr::V4["10.0.2.0/24"]])
+space.gaps # => BetterIpaddr::Space.new([IPAddr::V4["10.0.1.0/24"]])
+```
+
+The available methods are described in the [API docs](http://www.rubydoc.info/gems/better_ipaddr).
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/bjmllr/better_ipaddr. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## Copyright and License
+
+Copyright (C) 2016 Ben Miller
+
+The gem is available as free software under the terms of the [GNU General Public License, Version 3](http://www.gnu.org/licenses/gpl-3.0.html).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:spec) do |t|
+  t.libs << "spec"
+  t.libs << "lib"
+  t.test_files = FileList["spec/**/*_spec.rb"]
+end
+
+task default: :spec

data/better_ipaddr.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'better_ipaddr/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "better_ipaddr"
+  spec.version       = BetterIpaddr::VERSION
+  spec.authors       = ["Ben Miller"]
+  spec.email         = ["bmiller@rackspace.com"]
+
+  spec.summary       = "IPAddr enhancements for network management."
+  spec.homepage      = "https://github.com/bjmllr/better_ipaddr"
+  spec.license       = "GPL-3.0"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+                       .reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r(^exe/)) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.0"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "better_ipaddr"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/better_ipaddr.rb

@@ -0,0 +1,2 @@
+require "ipaddr"
+require "better_ipaddr/classes"

data/lib/better_ipaddr/classes.rb

@@ -0,0 +1,72 @@
+require "better_ipaddr/methods"
+
+class IPAddr
+  class Base < IPAddr
+    include BetterIpaddr::Constants
+    include BetterIpaddr::InstanceMethods
+    include Comparable
+    include Enumerable
+
+    def inherited(cls)
+      cls.extend BetterIpaddr::ClassMethods
+    end
+
+    def self.[](address, mask = nil, family: self::FAMILY)
+      if mask
+        new(address, family).mask(new(mask, family).to_s)
+      else
+        new(address, family)
+      end
+    end
+
+    # Return the given address as an instance of a class specific to
+    # its address family.
+    #
+    # @param address [IPAddr] the address to convert
+    # @return [IPAddr::V4, IPAddr::V6, IPAddr::EUI48]
+    def self.specialize(address)
+      return address unless address.class == IPAddr
+      case address.family
+      when Family::IPV4
+        IPAddr::V4[address.to_i, address.instance_variable_get(:@mask_addr)]
+      when Family::IPV6
+        IPAddr::V6[address.to_i, address.instance_variable_get(:@mask_addr)]
+      when Family::EUI48
+        IPAddr::MAC[address.to_i, address.instance_variable_get(:@mask_addr)]
+      end
+    end
+
+    def self.specialize_constants(family)
+      const_set(:FAMILY, family)
+      const_set(:BIT_LENGTH, FAMILY_TO_BIT_LENGTH.fetch(self::FAMILY))
+      const_set(:NETMASK_TO_PREFIX_LENGTH,
+                NETMASK_TO_PREFIX_LENGTH.fetch(self::FAMILY))
+      const_set(:PREFIX_LENGTH_TO_NETMASK,
+                PREFIX_LENGTH_TO_NETMASK.fetch(self::FAMILY))
+    end
+
+    def address_family_bit_length
+      self.class::BIT_LENGTH
+    end
+
+    def network?
+      prefix_length < self.class::BIT_LENGTH
+    end
+
+    def prefix_length
+      self.class::NETMASK_TO_PREFIX_LENGTH[mask_addr]
+    end
+  end
+
+  class V4 < Base
+    specialize_constants Family::IPV4
+  end
+
+  class V6 < Base
+    specialize_constants Family::IPV6
+  end
+
+  class MAC < Base
+    specialize_constants Family::EUI48
+  end
+end

data/lib/better_ipaddr/core_extension.rb

@@ -0,0 +1,11 @@
+require "ipaddr"
+require "better_ipaddr/methods"
+require "better_ipaddr/classes"
+
+class IPAddr
+  include BetterIpaddr::Constants
+  extend BetterIpaddr::ClassMethods
+  prepend BetterIpaddr::InstanceMethods
+  include Comparable
+  include Enumerable
+end

data/lib/better_ipaddr/methods.rb

@@ -0,0 +1,332 @@
+require "ipaddr"
+require "socket"
+
+module BetterIpaddr
+  module Constants
+    # Integer codes representing supported address clases.
+    # Reuse values from Socket namespace where possible.
+    module Family
+      IPV4 = Socket::AF_INET
+      IPV6 = Socket::AF_INET6
+      EUI48 = 48
+      EUI64 = 64
+    end
+
+    # Map well known address family names to constants.
+    SYMBOL_TO_FAMILY = {
+      ipv4: Family::IPV4,
+      ipv6: Family::IPV6,
+      eui48: Family::EUI48,
+      eui64: Family::EUI64,
+      mac: Family::EUI48
+    }
+
+    # Map each address family to the size of its address space, in bits.
+    FAMILY_TO_BIT_LENGTH = {
+      Family::IPV4 => 32,
+      Family::IPV6 => 128,
+      Family::EUI48 => 48,
+      Family::EUI64 => 64
+    }
+
+    # Map all possible prefix lengths to the corresponding netmasks.
+    PREFIX_LENGTH_TO_NETMASK = {}
+    FAMILY_TO_BIT_LENGTH.each_pair do |family, size|
+      netmasks = []
+      (0..size).each do |prefix_length|
+        netmasks[prefix_length] = 2**size - 2**(size - prefix_length)
+      end
+      PREFIX_LENGTH_TO_NETMASK[family] = netmasks
+    end
+
+    # Map all possible netmasks to the corresponding prefix lengths.
+    NETMASK_TO_PREFIX_LENGTH = {}
+    PREFIX_LENGTH_TO_NETMASK.each_pair do |family, hash|
+      NETMASK_TO_PREFIX_LENGTH[family] =
+        Hash[hash.map.with_index { |e, i| [e, i] }]
+    end
+  end
+
+  module ClassMethods
+    include Constants
+
+    # @overload [](address, family)
+    #   @param address [Integer] the integer representation of the address
+    #   @param family [Symbol] a symbol named for the address's
+    #     address family, one of +:ipv4+, +:ipv6+, or +:mac+.
+    #   @return [IPAddr]
+    #   Wrapper for IPAddr.new that accepts a symbolic family name and
+    #   returns a specialized IPAddr subclass.
+    #
+    # @overload [](address, family)
+    #   @param address [Integer] the integer representation of the address
+    #   @param family [Integer] the magic number representing the address's
+    #     address family.
+    #   @return [IPAddr]
+    #   Wrapper for IPAddr.new that accepts a symbolic family name and
+    #   returns a specialized IPAddr subclass.
+    #
+    # @overload [](address)
+    #   @param address [String] the string representation of the address
+    #   @return [IPAddr]
+    #   Wrapper for IPAddr.new that accepts the string representation
+    #   of an address returns a specialized IPAddr subclass.
+
+    def [](address, family = nil)
+      instance = case family
+                 when Symbol
+                   self[address, SYMBOL_TO_FAMILY.fetch(family)]
+                 when IPAddr
+                   address
+                 when nil
+                   new(address)
+                 else
+                   new(address, family)
+                 end
+      IPAddr::Base.specialize(instance)
+    end
+  end
+
+  module InstanceMethods
+    include Constants
+
+    # Return the magic number representing the address family.
+    # @return [Integer]
+    attr_reader :family
+
+    # Return the integer representation of the netmask.
+    # @return [Integer]
+    attr_reader :mask_addr
+    alias_method :netmask, :mask_addr
+
+    # Return the address greater than the original address by the
+    # given offset.
+    # @param offset [Integer] the difference between the original
+    #   address and the returned address
+    # @return [IPAddr]
+
+    def +(offset)
+      self.class.new(@addr + offset, family)
+    end
+
+    # Return the address less than the original address by the given
+    # offset.
+    # @param offset [Integer] the difference between the original
+    #   address and the returned address
+    # @return [IPAddr]
+
+    def -(offset)
+      self + (-offset)
+    end
+
+    # @overload <=>(other)
+    #   Compare this address with another address of the same address
+    #   family.
+    #   @param [IPAddr] other
+    #   @return [Integer]
+
+    # @overload <=>(other)
+    #   Compare this address with the integer representation of another
+    #   address of the same address family.
+    #   @param [Integer] other
+    #   @return [Integer]
+
+    def <=>(other)
+      if other.is_a?(IPAddr)
+        family_difference = family <=> other.family
+        return family_difference unless family_difference == 0
+      elsif !other.is_a?(Integer)
+        fail ArgumentError, "Can't compare #{self.class} with #{other.class}"
+      end
+
+      address_difference = to_i <=> other.to_i
+
+      if address_difference != 0 || !other.is_a?(IPAddr)
+        return address_difference
+      end
+
+      other.instance_variable_get(:@mask_addr) <=> @mask_addr
+    end
+
+    # Test the equality of two IP addresses, or an IP address an
+    # integer representing an address in the same address family.
+    # @param other [IPAddr, Integer] the address to compare with
+    # @return [Boolean]
+
+    def ==(other)
+      return false if other.nil?
+      (self <=> other) == 0
+    end
+
+    # The address at the given offset relative to the network address
+    # of the network. A negative offset will be used to count
+    # backwards from the highest addresses within the network.
+    # @param offset [Integer] the index within the network of the
+    # desired address
+    # @return [IPAddr] the address at the given index
+
+    def [](offset)
+      offset2 = offset >= 0 ? offset : size + offset
+      self.class[to_i + offset2, family: family]
+    end
+
+    # Returns the number of bits allowed by the address family.
+    # A more efficient form of this method is available to the
+    # specialized IPAddr child classes.
+    #
+    # @return [Integer]
+
+    def address_family_bit_length
+      FAMILY_TO_BIT_LENGTH.fetch(family)
+    end
+
+    # Returns a string representation of the address without a prefix length.
+    #
+    # @return [String]
+
+    def base
+      _to_string(@addr)
+    end
+
+    # Return a string containing the CIDR representation of the address.
+    #
+    # @return [String]
+
+    def cidr
+      return _to_string(@addr) unless ipv4? || ipv6?
+      "#{_to_string(@addr)}/#{prefixlen}"
+    end
+
+    # Test whether or not this address completely encloses the other address.
+
+    def cover?(other)
+      first <= other.first && other.last <= last
+    end
+
+    # @overload each
+    #   Yield each host address contained within the network. A host
+    #   address, such as +1.1.1.1/32+, will yield only itself. Returns
+    #   the original object.
+    #   @yield [IPAddr]
+    #   @return [IPAddr]
+
+    # @overload each
+    #   Return an enumerator with the behavior described above.
+    #   @return [Enumerator]
+
+    def each
+      if block_given?
+        (0...size).each do |offset|
+          yield self[offset]
+        end
+        self
+      else
+        enum_for(:each)
+      end
+    end
+
+    # The first host address in the network.
+    # @return [IPAddr]
+
+    def first
+      self[0]
+    end
+
+    # Return a new address with the prefix length reduced by the given
+    # amount. The new address will cover the original address.
+    # @param shift [Integer] the decrease in the prefix length
+    # @return [IPAddr]
+
+    def grow(shift)
+      mask(prefix_length - shift)
+    end
+
+    # Return true if the address represents a host (i.e., only one address).
+
+    def host?
+      prefix_length >= address_family_bit_length
+    end
+
+    # Return the last address in the network, which by convention is
+    # the broadcast address in IP networks.
+    # @return [IPAddr]
+
+    def last
+      self[-1]
+    end
+
+    alias_method :broadcast, :last
+
+    # Test whether or not two networks have any addresses in common
+    # (i.e., if either entirely encloses the other).
+
+    def overlap?(other)
+      cover?(other) || other.cover?(self)
+    end
+
+    # Return the prefix length.
+    # A more efficient form of this method is available to the
+    # specialized +IPAddr+ child classes.
+    # @return [Integer]
+
+    def prefix_length
+      NETMASK_TO_PREFIX_LENGTH[family][mask_addr]
+    end
+
+    alias_method :prefixlen, :prefix_length
+
+    # Return a new address with the prefix length increased by the
+    # given amount. The old address will cover the new address.
+    # @param shift [Integer] the increase in the prefix length
+    # @return [Boolean]
+
+    def shrink(shift)
+      mask(prefix_length + shift)
+    end
+
+    # Return the number of host addresses representable by the network
+    # given its size.
+    # @return [Integer]
+
+    def size
+      2**(address_family_bit_length - prefix_length)
+    end
+
+    # Returns a summary address if the two networks can be combined
+    # into a single network without covering any other networks.
+    # Returns +nil+ if the two networks can't be combined this way.
+    # @return [IPAddr?]
+
+    def summarize_with(other)
+      if other.nil?
+        nil
+      elsif cover?(other)
+        self
+      elsif other.cover?(self)
+        other
+      elsif other.grow(1) == grow(1)
+        grow(1)
+      end
+    end
+
+    # Return a range representing the network. A block can be given to
+    # specify a conversion procedure, for example to convert the first
+    # and last addresses to integers before building the range.
+    # @return [Range(IPAddr)]
+
+    def to_range
+      if block_given?
+        (yield first)..(yield last)
+      else
+        first..last
+      end
+    end
+
+    # Return a wildcard mask representing the network.
+    # @return [IPAddr]
+
+    def wildcard
+      _to_string(@mask_addr.to_i ^ (2**address_family_bit_length - 1))
+    end
+  end
+end