resolve-hostname 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: db097d50197dcc1acea87f5791721ca570040527
+  data.tar.gz: 59fb02477c21f54bdabb4580e6d3c78ec93b9930
+SHA512:
+  metadata.gz: 0ded77d0a22711f83efbd46bf97bf9a6c45ea1424b8f969986a7ba061f5979acbe1b7b85de188d6d59ccf3612953df2b48dae075eeb98926920d522e9b4178f7
+  data.tar.gz: 9776797a3bd95078ecbd8194483b740f4e21d98c883cb37d06e1dfafd695ebb2c4423a2e1988e61d5d155a934ba9e5ae085692495a035e34671ff5409f0a3656

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in resolve-dns-cached.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 TAGOMORI Satoshi
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,94 @@
+# Resolve::Hostname
+
+`Resolve::Hostname` is hostname resolver with:
+
+* caching with specified TTL
+* reloading of name server configurations (ex: `/etc/resolv.conf`)
+* skipping system resolver (default) or not when specified
+* primary IP address version specification (default: IPv4)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'resolve-hostname'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install resolve-hostname
+
+## Usage
+
+    require 'resolve/hostname'
+    
+    resolver = Resolve::Hostname.new
+    resolver.getaddress('www.google.com') #=> "173.194.72.103"
+    resolver.getaddress('www.google.com') #=> "173.194.72.103" # from cache
+
+Cache TTL(seconds) setting available for each resolver instances like this:
+
+    r = Resolve::Hostname.new(:ttl => 10) # default 60 seconds
+
+    r.getaddress('www.example.com')
+    sleep 11
+    r.getaddress('www.example.com') # not from cache, but from actual dns record (and cached)
+
+You can specify `resolver_ttl` with expectation for re-reading of `/etc/resolv.conf` in long life daemons.
+
+    r = Resolve::Hostname.new(:ttl => 10, :resolver_ttl => 20)
+    r.getaddress('www.example.com')
+
+Resolver raises `Resolve::Hostname::NotFoundError` when any records be found, and you can stop it (nil returned):
+
+    r1 = Resolve::Hostname.new
+    r1.getaddress('does-not-exists.example.com') # Resolve::Hostname::NotFoundError raised
+    
+    r2 = Resolve::Hostname.new(:raise_notfound => false)
+    r2.getaddress('does-not-exists.example.com') #=> nil
+
+### System Resolver
+
+for `/etc/hosts`:
+
+    r = Resolve::Hostname.new(:system_resolver => true)
+    r.getaddress('my-db-server.local')
+
+### IPv6 address query
+
+For queries about IPv6 addresses:
+
+    r = Resolve::Hostname.new(:version => :ipv6)
+    r.getaddress('example.com')          #=> '2001:500:88:200::10'
+    r.getaddress('ipv4only.example.com') #=> '192.0.43.10'
+
+### To deny other version of IP address
+
+Specify `:permit_other_version => false` if you are in IPv4 network and want not to get IPv6 address:
+
+    r1 = Resolve::Hostname.new
+    r1.getaddress('ipv6only.example.com') #=> '2001:500:88:200::10'
+    
+    r2 = Resolve::Hostname.new(:version => :ipv4, :permit_other_version => false)
+    r2.getaddress('ipv6only.example.com') # Resolve::Hostname::NotFoundError raised
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## TODO
+
+* negative cache support
+* DNS round robin support
+
+## Copyright
+
+* [MIT License](http://www.opensource.org/licenses/MIT).
+* Copyright (c) 2013- TAGOMORI Satoshi (tagomoris)

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:test) do |t|
+  t.rspec_opts = ["-c", "-f progress"] # '--format specdoc'
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+task :test => :spec
+task :default => :spec

data/lib/resolve/hostname.rb

@@ -0,0 +1,182 @@
+require "resolve/hostname/version"
+
+require 'ipaddr'
+require 'socket'
+require 'resolv'
+
+module Resolve
+  class Hostname
+    class NotFoundError < StandardError; end
+  end
+end
+
+module Resolve
+  class Hostname
+    attr_accessor :ttl, :resolver_ttl, :resolver_expires
+    attr_reader :cache # for testing
+
+    DEFAULT_EXPIRATION_SECONDS = 60
+    DEFAULT_RESOLVER_TTL = 1800 # for rereading of /etc/resolve.conf
+
+    DEFAULT_ENABLE_SYSTEM_RESOLVER = false
+
+    DEFAULT_PRIMARY_ADDRESS_VERSION = :ipv4
+    DEFAULT_PERMIT_SECONDARY_ADDRESS_VERSION = true
+    ADDRESS_VERSIONS = [:ipv4, :ipv6]
+
+    DEFAULT_RAISE_NOTFOUND = true
+
+    #TODO: negative caching not implemented
+    # DEFAULT_NEGATIVE_CACHE = false # disabled
+
+    #TODO: DNS RoundRobin with resolv
+    # DEFAULT_SUPPORTS_DNS_RR = false
+
+    def initialize(opts={})
+      @primary_ip_version = opts[:version] || DEFAULT_PRIMARY_ADDRESS_VERSION
+      unless ADDRESS_VERSIONS.include? @primary_ip_version
+        raise ArgumentError, "unknown version of ip address: #{opts[:version]}"
+      end
+
+      @ttl = opts[:ttl] || DEFAULT_EXPIRATION_SECONDS
+      @resolver_ttl = opts[:resolver_ttl] || DEFAULT_RESOLVER_TTL
+
+      @system_resolver_enabled = opts.fetch(:system_resolver, DEFAULT_ENABLE_SYSTEM_RESOLVER)
+      @permit_secondary_address_version = opts.fetch(:permit_other_version, DEFAULT_PERMIT_SECONDARY_ADDRESS_VERSION)
+      @raise_notfound = opts.fetch(:raise_notfound, DEFAULT_RAISE_NOTFOUND)
+
+      @cache = {}
+      @mutex = Mutex.new
+
+      @resolver = nil
+      @resolver_expires = nil
+    end
+
+    def getaddress(name)
+      unless @cache[name]
+        @mutex.synchronize do
+          @cache[name] ||= CachedValue.new(@ttl)
+        end
+      end
+      @cache[name].get_or_refresh{ resolve(name) }
+    end
+
+    def primary_ip_version
+      @primary_ip_version
+    end
+
+    def secondary_ip_version
+      @primary_ip_version == :ipv4 ? :ipv6 : :ipv4
+    end
+
+    def primary_version_address?(str)
+      if @primary_ip_version == :ipv4
+        IPAddr.new(str).ipv4?
+      else
+        IPAddr.new(str).ipv6?
+      end
+    end
+
+    def resolve(name)
+      secondary = nil
+
+      if @system_resolver_enabled
+        addr = resolve_builtin(name)
+        if addr
+          return addr if primary_version_address?(addr)
+          secondary = addr
+        end
+      end
+
+      addr = resolve_resolv(name, primary_ip_version)
+      if addr
+        return addr if primary_version_address?(addr)
+        secondary ||= addr
+      end
+
+      if secondary.nil? && @permit_secondary_address_version
+        secondary = resolve_resolv(name, secondary_ip_version)
+      end
+
+      addr = resolve_magic(name)
+      if addr
+        return addr if primary_version_address?(addr)
+        secondary ||= addr
+      end
+
+      return secondary if secondary && @permit_secondary_address_version
+
+      raise NotFoundError, "cannot resolve hostname #{name}" if @raise_notfound
+
+      nil
+    end
+
+    def resolv_instance
+      return @resolver if @resolver && @resolver_expires >= Time.now
+
+      @resolver_expires = Time.now + @resolver_ttl
+      @resolver = Resolv::DNS.new
+
+      @resolver
+    end
+
+    def resolve_resolv(name, version)
+      t = case version
+          when :ipv4
+            Resolv::DNS::Resource::IN::A
+          when :ipv6
+            Resolv::DNS::Resource::IN::AAAA
+          else
+            raise ArgumentError, "invalid ip address version:#{version}"
+          end
+      begin
+        resolv_instance.getresource(name, t).address.to_s
+      rescue Resolv::ResolvError => e
+        raise unless e.message.start_with?('DNS result has no information for')
+        nil
+      end
+    end
+
+    def resolve_builtin(name)
+      begin
+        IPSocket.getaddress(name)
+      rescue SocketError => e
+        raise unless e.message.start_with?('getaddrinfo: nodename nor servname provided, or not known')
+        nil
+      end
+    end
+
+    def resolve_magic(name)
+      if name =~ /^localhost$/i
+        return @primary_ip_version == :ipv4 ? '127.0.0.1' : '::1'
+      end
+      nil
+    end
+
+    class CachedValue
+      attr_accessor :value, :expires, :mutex
+
+      #TODO: negative cache
+      def initialize(ttl)
+        @value = nil
+        @ttl = ttl
+        @expires = Time.now + ttl
+        @mutex = Mutex.new
+      end
+
+      def get_or_refresh
+        return @value if @value && @expires >= Time.now
+
+        @mutex.synchronize do
+          return @value if @value && @expires >= Time.now
+
+          @value = yield
+          # doesn't do negative cache (updating of @expires is passed when something raised above)
+          @expires = Time.now + @ttl
+        end
+
+        @value
+      end
+    end
+  end
+end

data/lib/resolve/hostname/version.rb

@@ -0,0 +1,5 @@
+module Resolve
+  class Hostname
+    VERSION = "0.0.1"
+  end
+end

data/resolve-hostname.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'resolve/hostname/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "resolve-hostname"
+  spec.version       = Resolve::Hostname::VERSION
+  spec.authors       = ["TAGOMORI Satoshi"]
+  spec.email         = ["tagomoris@gmail.com"]
+  spec.description   = %q{With caching, selector for IPv4/IPv6, and many other features}
+  spec.summary       = %q{Hostname resolver with caching}
+  spec.homepage      = "https://github.com/tagomoris/resolve-dns-cached"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/spec/resolve_hostname_spec.rb

@@ -0,0 +1,92 @@
+require_relative './spec_helper'
+
+require 'resolve/hostname'
+
+describe Resolve::Hostname do
+  context 'initialized as near default' do
+    r = Resolve::Hostname.new(:ttl => 2, :resolver_ttl => 2)
+
+    describe '#primary_ip_version' do
+      it 'returns :ipv4' do
+        expect(r.primary_ip_version).to be(:ipv4)
+      end
+    end
+
+    describe '#secondary_ip_version' do
+      it 'returns :ipv6' do
+        expect(r.secondary_ip_version).to be(:ipv6)
+      end
+    end
+
+    describe '#primary_version_address?' do
+      context 'with valid IPv4 address' do
+        it 'returns true' do
+          expect(r.primary_version_address?('127.0.0.1')).to be_true
+        end
+      end
+
+      context 'with invalid IPv4 address' do
+        it 'returns false' do
+          expect{ r.primary_version_address?('256.256.256.256') }.to raise_error(IPAddr::InvalidAddressError)
+          expect{ r.primary_version_address?('256.256.256.0')   }.to raise_error(IPAddr::InvalidAddressError)
+          expect{ r.primary_version_address?('256.256.0.0')     }.to raise_error(IPAddr::InvalidAddressError)
+          expect{ r.primary_version_address?('256.0.0.0')       }.to raise_error(IPAddr::InvalidAddressError)
+          expect{ r.primary_version_address?('0.0.0.0') }.not_to raise_error()
+        end
+      end
+
+      context 'with IPv6 address' do
+        it 'returns false' do
+          expect(r.primary_version_address?('::1')).to be_false
+        end
+      end
+    end
+
+    describe '#resolv_instance' do
+      it 'returns instance newly instanciated instead of already expired' do
+        first = r.resolv_instance
+
+        r.resolver_expires = Time.now - 1
+
+        expect(r.resolv_instance).not_to be(first)
+      end
+    end
+
+    describe '#getaddress' do
+      it 'returns ipv4 address string for www.google.com' do
+        expect(r.getaddress('www.google.com')).to match(/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/)
+      end
+
+      it 'returns 192.0.43.10 for example.com' do
+        expect(r.getaddress('example.com')).to eq('192.0.43.10')
+      end
+
+      it 'returns same ruby object for second query' do
+        first = r.getaddress('google.com')
+        expect(r.getaddress('google.com')).to be(first)
+      end
+
+      it 'raise error for records non-existing' do
+        expect { r.getaddress('not-existing.example.com') }.to raise_error(Resolve::Hostname::NotFoundError)
+      end
+
+      it 'returns newly fetched object instead of expired cache' do
+        first = r.getaddress('www.example.com')
+
+        r.cache['www.example.com'].expires = Time.now - 1
+
+        expect(r.getaddress('www.example.com')).not_to be(first)
+      end
+
+      it 'returns 127.0.0.1 for localhost' do
+        expect(r.getaddress('localhost')).to eq('127.0.0.1')
+      end
+    end
+  end
+
+  context 'initialized as system resolver enabled'
+  context 'initialized with ipv6 primary'
+  context 'initialized as not permitted for secondary address version'
+
+  context 'initialized as not to raise NotFoundError'
+end

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: resolve-hostname
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- TAGOMORI Satoshi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-07-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: With caching, selector for IPv4/IPv6, and many other features
+email:
+- tagomoris@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/resolve/hostname.rb
+- lib/resolve/hostname/version.rb
+- resolve-hostname.gemspec
+- spec/resolve_hostname_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/tagomoris/resolve-dns-cached
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.2
+signing_key: 
+specification_version: 4
+summary: Hostname resolver with caching
+test_files:
+- spec/resolve_hostname_spec.rb
+- spec/spec_helper.rb
+has_rdoc: