useful_utilities 5.4.6 → 5.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 79bd418ad8787d74738d6fd2b99030e6c698ee1c
-  data.tar.gz: 1f227b9d219366903e323a70b043bf951eb12f6a
+  metadata.gz: 070776adf9c916abe22c6c83c0bc51af55ce327b
+  data.tar.gz: 14abcd387fe88bcc23027e7375070543dd966470
 SHA512:
-  metadata.gz: f09b24ef2b0714e6d53638984f206f04a89335fbdc37df399ae65ee66307b2094684629c0ded231edbd46947a705fcd4a0d3931ee9071a5943e1931c29069905
-  data.tar.gz: 490c74b2afb5ac686e72f145739a29e8af0a5fc6dce80fb38985a3e4880cb8b5b65bcffa3def2626e1be001ed190ab44550b09a7aff3a3ae72a7c2ef378b94d2
+  metadata.gz: 815b9225aba50b2c7062b75740daa87bc9e78054d622d8915a8511c6f0df7d3e9319d304ed06b0dcf8fc09937d2a88e8781e94ca6f1428c6f9a8e919a7de5477
+  data.tar.gz: b164e91be3ab638bded3a1bc0f9dfd1a7d3f8b80ad78e697012fc944113714a5c2f019cf07e3a6f1b00eaf8136590fa5f2e26d8c42e4622712446c6bd18859c2

data/lib/useful_utilities/ip.rb

@@ -0,0 +1,222 @@
+require 'ipaddr'
+
+module UsefulUtilities
+  # Provides a bunch of convinient methods to deal with ip addresses
+  # The module rely on stdlib ipaddr
+  module IP
+    IPV4 = 4
+    IPV6 = 6
+    IPVERSIONS = [IPV4, IPV6].freeze
+    MAX_NET_MASK_IPV4 = 32
+    MAX_NET_MASK_IPV6 = 128
+    MIN_NET_MASK      = 0
+    ZERO_IP_INTEGER   = 0
+
+    # integer representing ip '10.0.0.0', start of '10.0.0.0/8'
+    PRIVATE_RANGE_10_START = 167772160
+    # integer representing ip '10.255.255.255', end of '10.0.0.0/8'
+    PRIVATE_RANGE_10_END   = 184549375
+
+    # integer representing ip '172.16.0.0', start of '172.16.0.0/12'
+    PRIVATE_RANGE_172_START = 2886729728
+    # integer representing ip '172.31.255.255', end of '172.16.0.0/12'
+    PRIVATE_RANGE_172_END   = 2887778303
+
+    # integer representing ip '192.168.0.0', start of '192.168.0.0/16'
+    PRIVATE_RANGE_192_START = 3232235520
+    # integer representing ip '192.168.255.255', end of '192.168.0.0/16'
+    PRIVATE_RANGE_192_END   = 3232301055
+
+    # integer representing ip 'fc00::', start of 'fc00::/7'
+    PRIVATE_RANGE_FC_START = 334965454937798799971759379190646833152
+    # integer representing ip 'fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff',
+    # end of 'fc00::/7'
+    PRIVATE_RANGE_FC_END   = 337623910929368631717566993311207522303
+
+    private_constant :IPV4,
+                     :IPV6,
+                     :IPVERSIONS,
+                     :MAX_NET_MASK_IPV4,
+                     :MAX_NET_MASK_IPV6,
+                     :MIN_NET_MASK,
+                     :ZERO_IP_INTEGER,
+                     :PRIVATE_RANGE_10_START,
+                     :PRIVATE_RANGE_10_END,
+                     :PRIVATE_RANGE_172_START,
+                     :PRIVATE_RANGE_172_END,
+                     :PRIVATE_RANGE_192_START,
+                     :PRIVATE_RANGE_192_END,
+                     :PRIVATE_RANGE_FC_START,
+                     :PRIVATE_RANGE_FC_END
+
+    extend self
+
+    # @param ip_string [String]
+    # @return [Boolean] true if supplied string is parsable ip address string
+    # and false otherwise
+    # @example
+    #   UsefulUtilities::IP.valid_ip('10.10.0.1') #=> true
+    #   UsefulUtilities::IP.valid_ip('non-parsable-ip') #=> false
+    def valid_ip?(ip_string)
+      IPAddr.new(ip_string)
+      true
+    rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+      false
+    end
+
+    # @param ip_string [String]
+    # @return [Boolean] true if ip_string represent private ip address.
+    # If ip_sting is non-parsable ip address ArgumentError raises.
+    # It is a wrapper on the private? method of IPAddr class instance.
+    # IPv4 addresses in 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16 as defined
+    # in RFC 1918 and IPv6 Unique Local Addresses in fc00::/7 as defined in
+    # RFC 4193 are considered private.
+    # @example
+    #   UsefulUtilities::IP.private_ip?('10.10.10.10') #=> true
+    #   UsefulUtilities::IP.private_ip?('8.10.10.10') #=> false
+    def private_ip?(ip_string)
+      ip = IPAddr.new(ip_string)
+
+      # starting from ruby 2.5.0 an IPAddr instance has built-in private? method
+      # use the built-in method if exists
+      return ip.private? if ip.respond_to?(:private?)
+
+      check_private_ip(ip)
+    rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+      raise ArgumentError, 'Invalid ip address string supplied!'
+    end
+
+    # @param address [Integer]
+    # @param version. If version is not equal 4 or 6 ArgumentError raises.
+    # If supplied address can not be converted into ip address string
+    # then ArgumentError raises.
+    # @return string as human readable ip address.
+    # @example
+    #   UsefulUtilities::IP.integer_to_ip_string(1,version: 4) #=> '0.0.0.1'
+    #   UsefulUtilities::IP.integer_to_ip_string(1,version: 6) #=> '::1'
+    def integer_to_ip_string(address, version:)
+      unless address.is_a? Integer
+        raise ArgumentError, 'Supplied address is not integer!'
+      end
+
+      IPAddr.new(address, ip_address_family(version)).to_s
+    rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+      raise ArgumentError, 'Invalid address!'
+    end
+
+    # @param ip_string [String]
+    # @return integer representation of supplied ip string.
+    # ArgumentError raises if ip string can not be parsed as ip address.
+    # @example
+    #   UsefulUtilities::IP.ip_string_to_integer('0.0.0.2') #=> 2
+    #   UsefulUtilities::IP.ip_string_to_integer('::2') #=> 2
+    def ip_string_to_integer(ip_string)
+      IPAddr.new(ip_string).to_i
+    rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+      raise ArgumentError, 'Invalid ip address string supplied!'
+    end
+
+    # @param ip_string [String]
+    # @return array of 2 elements,
+    # the first: integer representation of supplied ip string,
+    # the second: version of ip protocol 4 or 6.
+    # ArgumentError raises if ip string can not be parsed as ip address.
+    # @example
+    #   UsefulUtilities::IP.ip_string_to_integer_with_version('0.0.0.1') #=> [1, 4]
+    #   UsefulUtilities::IP.ip_string_to_integer_with_version('::1') #=> [1, 6]
+    def ip_string_to_integer_with_version(ip_string)
+      ip = IPAddr.new(ip_string)
+      version = IPV4 if ip.ipv4?
+      version = IPV6 if ip.ipv6?
+
+      [ip.to_i, version]
+    rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+      raise ArgumentError, 'Invalid ip address string supplied!'
+    end
+
+    # @param ip_string [String]
+    # @param network_mask [Integer]
+    # @return [String] value representing network address derived from supplied
+    # ip address and it's network mask
+    # @example
+    #   UsefulUtilities::IP.network_address('10.10.15.33', 24) #=> "10.10.15.0"
+    def network_address(ip_string, network_mask)
+      ip = IPAddr.new(ip_string)
+
+      version = if ip.ipv4?
+                  IPV4
+                elsif ip.ipv6?
+                  IPV6
+                else
+                  raise ArgumentError, 'Unsupported ip address version!'
+                end
+
+      unless acceptable_network_mask?(network_mask, version: version)
+        raise ArgumentError,
+              "Invalid network mask: '#{network_mask}' for address: '#{ip_string}'"
+      end
+
+      ip_network_address =
+        IPAddr.new(ZERO_IP_INTEGER, ip_address_family(version))
+              .~
+              .<<(max_network_mask(version) - network_mask)
+              .&(ip)
+
+      ip_network_address.to_s
+    rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+      raise ArgumentError, 'Invalid ip address string supplied!'
+    end
+
+    # @param network_mask [Integer]
+    # @param version [Integer]
+    # @return [Boolean]
+    # ArgumentError raises if version is not equal 4 or 6.
+    # @example
+    #   UsefulUtilities::IP.acceptable_network_mask?('not int', version: 4) #=> false
+    #   UsefulUtilities::IP.acceptable_network_mask?(24, version: 4) #=> true
+    def acceptable_network_mask?(network_mask, version:)
+      return false unless network_mask.is_a? Integer
+
+      network_mask >= MIN_NET_MASK && network_mask <= max_network_mask(version)
+    end
+
+    private
+
+    def ip_address_family(ip_version)
+      return Socket::AF_INET if ip_version == IPV4
+      return Socket::AF_INET6 if ip_version == IPV6
+
+      raise ArgumentError,
+            'Unsupported ip address version! '\
+            "Supported argument values: #{IPV4} or #{IPV6}."
+    end
+
+    def max_network_mask(ip_version)
+      return MAX_NET_MASK_IPV4 if ip_version == IPV4
+      return MAX_NET_MASK_IPV6 if ip_version == IPV6
+
+      raise ArgumentError,
+            'Unsupported version supplied! '\
+            "Supported version values: #{IPV4} or #{IPV6}."
+    end
+
+    def check_private_ip(ip)
+      return true if ip.ipv4? && in_private_ipv4?(ip.to_i)
+      return true if ip.ipv6? && in_private_ipv6?(ip.to_i)
+
+      false
+    end
+
+    def in_private_ipv4?(integer_ip)
+      [
+        (PRIVATE_RANGE_10_START..PRIVATE_RANGE_10_END),
+        (PRIVATE_RANGE_172_START..PRIVATE_RANGE_172_END),
+        (PRIVATE_RANGE_192_START..PRIVATE_RANGE_192_END)
+      ].any? { |range| range.include?(integer_ip) }
+    end
+
+    def in_private_ipv6?(integer_ip)
+      (PRIVATE_RANGE_FC_START..PRIVATE_RANGE_FC_END).include?(integer_ip)
+    end
+  end
+end

data/lib/useful_utilities/version.rb

@@ -1,3 +1,3 @@
 module UsefulUtilities
-  VERSION = '5.4.6'.freeze
+  VERSION = '5.5.0'.freeze
 end

data/lib/useful_utilities.rb

@@ -8,6 +8,7 @@ module UsefulUtilities
   require_relative 'useful_utilities/size'
   require_relative 'useful_utilities/api'
   require_relative 'useful_utilities/i18n'
+  require_relative 'useful_utilities/ip'
   require_relative 'useful_utilities/hash'
   require_relative 'useful_utilities/yaml'
   require_relative 'useful_utilities/redhat_release'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: useful_utilities
 version: !ruby/object:Gem::Version
-  version: 5.4.6
+  version: 5.5.0
 platform: ruby
 authors:
 - OnApp Ltd.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-03-27 00:00:00.000000000 Z
+date: 2018-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -94,8 +94,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: |2
-      A bunch of useful modules to work with time/size constants/hashes
+description: "    A bunch of useful modules to work with time/size constants/hashes\n"
 email: onapp@onapp.com
 executables: []
 extensions: []
@@ -108,6 +107,7 @@ files:
 - lib/useful_utilities/centos_version.rb
 - lib/useful_utilities/hash.rb
 - lib/useful_utilities/i18n.rb
+- lib/useful_utilities/ip.rb
 - lib/useful_utilities/numeric.rb
 - lib/useful_utilities/redhat_release.rb
 - lib/useful_utilities/size.rb
@@ -141,7 +141,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.3
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
 summary: Helpful methods for time, sizes, hashes etc.