Dnsruby 0.6.0 → 1.0

data/doc/index.html

@@ -19,6 +19,6 @@
         <frame src="fr_class_index.html"  name="Classes" />
         <frame src="fr_method_index.html" name="Methods" />
     </frameset>
-    <frame src="files/lib/dnsruby_rb.html" name="docwin" />
+    <frame src="classes/Dnsruby.html" name="docwin" />
 </frameset>
 </html>

data/lib/Dnsruby/Config.rb

@@ -60,6 +60,8 @@ module Dnsruby
     #        domain (String)
     #        search (String)
     #        ndots (Fixnum)
+    #
+    # This method should not normally be called by client code.
     def set_config_info(config_info)
       parse_config(config_info)
     end
@@ -118,10 +120,14 @@ module Dnsruby
     
     # Set the default domain
     def domain=(dom)
-      if !dom.kind_of?(String)
-        raise ArgumentError.new("invalid domain config: #{@domain.inspect}")
+      if (dom)
+        if !dom.kind_of?(String)
+          raise ArgumentError.new("invalid domain config: #{@domain.inspect}")
+        end
+        @domain = Name::Label.split(dom)
+      else
+        @domain=nil
       end
-      @domain = Name::Label.split(dom)
     end
     
     # Set ndots
@@ -151,7 +157,7 @@ module Dnsruby
       end
       
       if !@search.kind_of?(Array) ||
-        #              !@search.all? {|ls| ls.all? {|l| Label::Str === l } }
+          #              !@search.all? {|ls| ls.all? {|l| Label::Str === l } }
         !@search.all? {|ls| ls.all? {|l| Name::Label === l } }
         raise ArgumentError.new("invalid search config: #{@search.inspect}")
       end
@@ -159,7 +165,7 @@ module Dnsruby
     
     def check_ns(ns) #:nodoc: all
       if !ns.kind_of?(Array) ||
-        !ns.all? {|n| (String === n || IPv4 === n || IPv6 === n)}
+          !ns.all? {|n| (String === n || IPv4 === n || IPv6 === n)}
         raise ArgumentError.new("invalid nameserver config: #{ns.inspect}")
       end    
       ns.each_index do |i|

data/lib/Dnsruby/DNS.rb

@@ -17,19 +17,9 @@ require 'Dnsruby/Hosts'
 require 'Dnsruby/Config'
 require "Dnsruby/Resolver"
 module Dnsruby
-  #--
-  #@TODO@ Asynchronous interface. Do we want a callback (in a new thread) or a queue system?
-  #Is there any point in taking a block? May as well...
-  #e.g. getaddresses_async(name, Queue|Proc)
-  #Could we make the final argument optional to all the standard calls? So they are either sync or async?
-  #e.g. getaddresses(name{, Queue|Proc})
-  #Yes to all but each_resource - would have to make a new each_resource_async or something...
-  #@TODO@ BUT - need to pass in an ID as well as a queue to identify correct response
-  #Proc can keep track of query ID itself
-  #++
 
   #== Dnsruby::DNS class
-  #DNS stub resolver.
+  #Resolv::DNS performs DNS queries.
   #
   #=== class methods
   #* Dnsruby::DNS.new(config_info=nil)
@@ -80,10 +70,17 @@ module Dnsruby
   #are tried (if there is no timely answer from the first).
   #
   #This class uses Resolver to perform the queries.
+  #
+  #Information taken from the following places :
+  #* STD0013 
+  #* RFC 1035, etc.
+  #* ftp://ftp.isi.edu/in-notes/iana/assignments/dns-parameters
+  #* etc.
   class DNS
-    # STD0013 (RFC 1035, etc.)
-    # ftp://ftp.isi.edu/in-notes/iana/assignments/dns-parameters
     
+    #Creates a new DNS resolver. See Resolv::DNS.new for argument details.
+    #
+    #Yields the created DNS resolver to the block, if given, otherwise returns it.
     def self.open(*args)
       dns = new(*args)
       return dns unless block_given?
@@ -94,6 +91,7 @@ module Dnsruby
       end
     end
     
+    #Closes the resolver
     def close
       @resolver.close
     end
@@ -103,6 +101,18 @@ module Dnsruby
       return "DNS : " + @config.to_s
     end
     
+    #Creates a new DNS resolver
+    #
+    #+config_info+ can be:
+    #
+    #* nil:: Uses platform default (e.g. /etc/resolv.conf)
+    #* String:: Path to a file using /etc/resolv.conf's format
+    #* Hash:: Must contain :nameserver, :search and :ndots keys
+    #   example :
+    #
+    #    Dnsruby::DNS.new({:nameserver => ['210.251.121.21'],
+    #                      :search => ['ruby-lang.org'],
+    #                      :ndots => 1})
     def initialize(config_info=nil)
       @config = Config.new()
       @config.set_config_info(config_info)
@@ -111,32 +121,56 @@ module Dnsruby
     
     attr_reader :config    
     
+    #Gets the first IP address of +name+ from the DNS resolver
+    #
+    #+name+ can be a Dnsruby::Name or a String. Retrieved address will be a 
+    #Dnsruby::IPv4 or a Dnsruby::IPv6
     def getaddress(name)
       each_address(name) {|address| return address}
       raise ResolvError.new("DNS result has no information for #{name}")
     end
     
+    #Gets all IP addresses of +name+ from the DNS resolver
+    #
+    #+name+ can be a Dnsruby::Name or a String. Retrieved address will be a 
+    #Dnsruby::IPv4 or a Dnsruby::IPv6
     def getaddresses(name)
       ret = []
       each_address(name) {|address| ret << address}
       return ret
     end
     
+    #Iterates over all IP addresses of +name+ retrieved from the DNS resolver
+    #
+    #+name+ can be a Dnsruby::Name or a String. Retrieved address will be a 
+    #Dnsruby::IPv4 or a Dnsruby::IPv6
     def each_address(name)
       each_resource(name) {|resource| yield resource.address}
     end
     
+    #Gets the first hostname for +address+ from the DNS resolver
+    #
+    #+address+ must be a Dnsruby::IPv4, Dnsruby::IPv6 or a String. Retrieved
+    #name will be a Dnsruby::Name.
     def getname(address)
       each_name(address) {|name| return name}
       raise ResolvError.new("DNS result has no information for #{address}")
     end
     
+    #Gets all hostnames for +address+ from the DNS resolver
+    #
+    #+address+ must be a Dnsruby::IPv4, Dnsruby::IPv6 or a String. Retrieved
+    #name will be a Dnsruby::Name.
     def getnames(address)
       ret = []
       each_name(address) {|name| ret << name}
       return ret
     end
     
+    #Iterates over all hostnames for +address+ retrieved from the DNS resolver
+    #
+    #+address+ must be a Dnsruby::IPv4, Dnsruby::IPv6 or a String. Retrieved
+    #name will be a Dnsruby::Name.
     def each_name(address)
       case address
       when Name
@@ -151,44 +185,38 @@ module Dnsruby
       each_resource(ptr, Types.PTR, Classes.IN) {|resource| yield resource.domainname}
     end
     
+    #Look up the first +type+, +klass+ resource for +name+
+    #
+    #+type+ defaults to Dnsruby::Types.A
+    #+klass+ defaults to Dnsruby::Classes.IN
+    #
+    #Returned resource is represented as a Dnsruby::RR instance, e.g. 
+    #Dnsruby::RR::IN::A
     def getresource(name, type=Types.A, klass=Classes.IN)
       each_resource(name, type, klass) {|resource| return resource}
       raise ResolvError.new("DNS result has no information for #{name}")
     end
     
+    #Look up all +type+, +klass+ resources for +name+
+    #
+    #+type+ defaults to Dnsruby::Types.A
+    #+klass+ defaults to Dnsruby::Classes.IN
+    #
+    #Returned resource is represented as a Dnsruby::RR instance, e.g. 
+    #Dnsruby::RR::IN::A
     def getresources(name, type=Types.A, klass=Classes.IN)
       ret = []
       each_resource(name, type, klass) {|resource| ret << resource}
       return ret
     end
     
-    def send_query(name, type=Types.A, klass=Classes.IN)
-      q = Queue.new
-      candidates = @config.generate_candidates(name)
-      exception = nil
-      candidates.each do |candidate|
-        msg = Message.new
-        msg.header.rd = 1
-        msg.add_question(candidate, type, klass)
-        @resolver.send_async(msg, q, q)
-        id, ret, exception = q.pop
-        if (exception == nil && ret.header.rcode == RCode.NOERROR)
-          return ret, ret.question[0].qname
-        end
-        #        if (ret.kind_of?Message)
-        #          exception = ret.header.rcode
-        #          if (ret.header.rcode==RCode.NOERROR)
-        #            return ret, ret.question[0].qname
-        #          end
-        #        else
-        #          #@TODO@ Keep trying until all the candidates are done
-        #          #          raise ret
-        #          exception = ret
-        #        end
-      end
-      raise exception
-    end
-    
+    #Iterates over all +type+, +klass+ resources for +name+
+    #
+    #+type+ defaults to Dnsruby::Types.A
+    #+klass+ defaults to Dnsruby::Classes.IN
+    #
+    #Yielded resource is represented as a Dnsruby::RR instance, e.g. 
+    #Dnsruby::RR::IN::A
     def each_resource(name, type=Types.A, klass=Classes.IN, &proc)
       type = Types.new(type)
       klass = Classes.new(klass)
@@ -203,12 +231,10 @@ module Dnsruby
       else
         TheLog.error("Unexpected rcode : #{reply.header.rcode.string}")
         raise Config::OtherResolvError.new(reply_name.to_s)
-      end
-      
+      end      
     end
     
-    def extract_resources(msg, name, type, klass)
-      #      if type < Types.ANY
+    def extract_resources(msg, name, type, klass) # :nodoc:
       if type == Types.ANY
         n0 = Name.create(name)
         msg.each_answer {|rec|
@@ -242,12 +268,33 @@ module Dnsruby
         end
       }
     end
-    
-    class DecodeError < StandardError
-    end
 
-    class EncodeError < StandardError
+    def send_query(name, type=Types.A, klass=Classes.IN) # :nodoc:
+      candidates = @config.generate_candidates(name)
+      exception = nil
+      candidates.each do |candidate|
+        q = Queue.new
+        msg = Message.new
+        msg.header.rd = 1
+        msg.add_question(candidate, type, klass)
+        @resolver.send_async(msg, q)
+        id, ret, exception = q.pop
+        if (exception == nil && ret.header.rcode == RCode.NOERROR)
+          return ret, ret.question[0].qname
+        end
+      end
+      raise exception
     end
-
+    
   end
-end
+end
+#--
+#@TODO@ Asynchronous interface. Do we want a callback (in a new thread) or a queue system?
+#Is there any point in taking a block? May as well...
+#e.g. getaddresses_async(name, Queue|Proc)
+#Could we make the final argument optional to all the standard calls? So they are either sync or async?
+#e.g. getaddresses(name{, Queue|Proc})
+#Yes to all but each_resource - would have to make a new each_resource_async or something...
+#@TODO@ BUT - need to pass in an ID as well as a queue to identify correct response
+#Proc can keep track of query ID itself
+#++

data/lib/Dnsruby/Hosts.rb

@@ -15,7 +15,7 @@
 #++
 module Dnsruby
 #== Dnsruby::Hosts class
-#hostname resolver using /etc/hosts format.
+#Dnsruby::Hosts is a hostname resolver that uses the system hosts file
 #
 #=== class methods
 #* Dnsruby::Hosts.new(hosts='/etc/hosts')
@@ -39,13 +39,14 @@ module Dnsruby
       DefaultFileName = '/etc/hosts'
     end
     
+    #Creates a new Dnsruby::Hosts using +filename+ for its data source
     def initialize(filename = DefaultFileName)
       @filename = filename
       @mutex = Mutex.new
       @initialized = nil
     end
     
-    def lazy_initialize
+    def lazy_initialize# :nodoc:
       @mutex.synchronize {
         unless @initialized
           @name2addr = {}
@@ -80,17 +81,20 @@ module Dnsruby
       self
     end
     
+    #Gets the first IP address for +name+ from the hosts file
     def getaddress(name)
       each_address(name) {|address| return address}
       raise ResolvError.new("#{@filename} has no name: #{name}")
     end
     
+    #Gets all IP addresses for +name+ from the hosts file
     def getaddresses(name)
       ret = []
       each_address(name) {|address| ret << address}
       return ret
     end
     
+    #Iterates over all IP addresses for +name+ retrieved from the hosts file
     def each_address(name, &proc)
       lazy_initialize
       if @name2addr.include?(name)
@@ -98,17 +102,20 @@ module Dnsruby
       end
     end
     
+    #Gets the first hostname of +address+ from the hosts file
     def getname(address)
       each_name(address) {|name| return name}
       raise ResolvError.new("#{@filename} has no address: #{address}")
     end
     
+    #Gets all hostnames for +address+ from the hosts file
     def getnames(address)
       ret = []
       each_name(address) {|name| ret << name}
       return ret
     end
     
+    #Iterates over all hostnames for +address+ retrieved from the hosts file
     def each_name(address, &proc)
       lazy_initialize
       if @addr2name.include?(address)

data/lib/Dnsruby/Resolver.rb

@@ -16,18 +16,19 @@
 require "Dnsruby/SingleResolver"
 module Dnsruby
   #== Description
-  # This class uses a set of SingleResolvers to perform queries with retries across multiple nameservers.
+  #Dnsruby::Resolver is a DNS stub resolver.
+  #This class uses a set of SingleResolvers to perform queries with retries across multiple nameservers.
   #
-  # The retry policy is a combination of the Net::DNS and dnsjava approach, and has the option of :
+  #The retry policy is a combination of the Net::DNS and dnsjava approach, and has the option of :
   #* A total timeout for the query (defaults to 0, meaning "no total timeout")
   #* A retransmission system that targets the namervers concurrently once the first query round is 
   #  complete, but in which the total time per query round is split between the number of nameservers 
   #  targetted for the first round. and total time for query round is doubled for each query round
   #   
-  #  Note that, if a total timeout is specified, then that will apply regardless of the retry policy 
-  #  (i.e. it may cut retries short).
+  # Note that, if a total timeout is specified, then that will apply regardless of the retry policy 
+  #(i.e. it may cut retries short).
   #  
-  #  Note also that these timeouts are distinct from the SingleResolver's packet_timeout
+  # Note also that these timeouts are distinct from the SingleResolver's packet_timeout
   #
   #== Methods
   # 
@@ -74,7 +75,7 @@ module Dnsruby
     attr_reader :use_tcp
     
     
-    attr_reader :tsig_key
+    attr_reader :tsig
     
     # Should truncation be ignored?
     # i.e. the TC bit is ignored and thus the resolver will not requery over TCP if TC is set
@@ -159,7 +160,7 @@ module Dnsruby
     def send_message(message)
       TheLog.debug("Resolver : sending message")
       q = Queue.new
-      send_async(message, q, q)
+      send_async(message, q)
       id, result, error = q.pop
       TheLog.debug("Resolver : result received")
       if (error != nil)
@@ -170,22 +171,48 @@ module Dnsruby
     end
     
     
-    # Asynchronously sends a DNS packet (Dnsruby::Message). The client must pass in the 
-    # Message to be sent, a client_query_id to identify the message and a client_queue (of 
-    # class Queue) to pass the response back in. 
+    #Asynchronously send a Message to the server. The send can be done using just
+    #Dnsruby, or using EventMachine.
     # 
-    # A tuple of (query_id, response_message, exception) will be added to the client_queue.
+    #== Dnsruby pure Ruby event loop :
+    # 
+    #A client_queue is supplied by the client, 
+    #along with an optional client_query_id to identify the response. The client_query_id
+    #is generated, if not supplied, and returned to the client.
+    #When the response is known, 
+    #a tuple of (query_id, response_message, exception) will be added to the client_queue.
+    # 
+    #The query is sent synchronously in the caller's thread. The select thread is then used to 
+    #listen for and process the response (up to pushing it to the client_queue). The client thread 
+    #is then used to retrieve the response and deal with it.
+    # 
+    #Takes :
+    # 
+    #* msg - the message to send
+    #* client_queue - a Queue to push the response to, when it arrives
+    #* client_query_id - an optional ID to identify the query to the client
+    #* use_tcp - whether to use TCP (defaults to SingleResolver.use_tcp)
     #
+    #Returns :
     # 
-    # example :
+    #* client_query_id - to identify the query response to the client. This ID is
+    #generated if it is not passed in by the client
     # 
+    #=== Example invocations :
+    #
+    #    id = res.send_async(msg, queue)
+    #    NOT SUPPORTED : id = res.send_async(msg, queue, use_tcp)
+    #    id = res.send_async(msg, queue, id)
+    #    id = res.send_async(msg, queue, id, use_tcp)
+    #    
+    #=== Example code :
+    #
     #   require 'Dnsruby'
     #   res = Dnsruby::Resolver.new
     #   query_id = 10 # can be any object you like
     #   query_queue = Queue.new
     #   res.send_async(Message.new("example.com", Types.MX),  query_queue, query_id)
-    #   query_id += 1
-    #   res.send_async(Message.new("example.com", Types.A), query_queue, query_id)
+    #   query_id_2 = res.send_async(Message.new("example.com", Types.A), query_queue)
     #   # ...do a load of other stuff here...
     #   2.times do 
     #     response_id, response, exception = query_queue.pop
@@ -196,7 +223,49 @@ module Dnsruby
     #         # deal with problem
     #     end
     #   end
-    # @TODO@ Sort out RDoc arguments to send_async!
+    #
+    #== If EventMachine is being used :
+    # 
+    #If EventMachine is being used (see Dnsruby::Resolver::use_eventmachine, then this method returns
+    #an EM::Deferrable object. When the response is known, then the Deferrable will complete.
+    #If a queue (and ID) is passed in, then the response will also be 
+    #pushed to the Queue. Note that an ID is not automatically generated by this version.
+    # 
+    #=== Example invocations :
+    #
+    #    deferrable = res.send_async(msg)
+    #    deferrable = res.send_async(msg, use_tcp)
+    #    deferrable = res.send_async(msg, q, id, use_tcp)
+    #    
+    #=== Example code  
+    #* Here is an example of using the code in an EventMachine style :
+    #
+    #    require 'Dnsruby'
+    #    require 'eventmachine'
+    #    res = Dnsruby::Resolver.new
+    #    Dnsruby::Resolver.use_eventmachine
+    #    Dnsruby::Resolver.start_eventmachine_loop(false)
+    #    EventMachine::run {
+    #      df = res.send_async(Dnsruby::Message.new("example.com"))
+    #      df.callback {|msg|
+    #         puts "Response : #{msg}"
+    #         EM.stop}
+    #      df.errback {|msg, err|
+    #         puts "Response : #{msg}"
+    #         puts "Error: #{err}"
+    #         EM.stop}
+    #    }
+    #
+    #* And an example in a normal Dnsruby style :
+    #
+    #    require 'Dnsruby'
+    #    res = Dnsruby::Resolver.new
+    #    Dnsruby::Resolver.use_eventmachine
+    #    Dnsruby::Resolver.start_eventmachine_loop(true) # default
+    #    q = Queue.new
+    #    id = res.send_async(Dnsruby::Message.new("example.com"),q)
+    #    id, response, error = q.pop
+    #
     def send_async(*args) # msg, client_queue, client_query_id)
       if (Resolver.eventmachine?)
         if (!@resolver_em)
@@ -223,7 +292,7 @@ module Dnsruby
     # 
     # * :port
     # * :use_tcp
-    # * :tsig_key
+    # * :tsig
     # * :ignore_truncation
     # * :src_address
     # * :src_port
@@ -238,6 +307,9 @@ module Dnsruby
     # * :retry_times
     # * :retry_delay
     def initialize(*args)
+      @resolver_em = nil
+      @resolver_ruby = nil
+      @src_address = nil
       reset_attributes
       
       # Process args
@@ -263,7 +335,7 @@ module Dnsruby
           @config = args[0]
         end
       else
-        #@TODO@ ?
+        # Anything to do?
       end
       if (@single_resolvers==[])
         add_config_nameservers
@@ -302,7 +374,7 @@ module Dnsruby
       @port = DefaultPort
       @udp_size = DefaultUDPSize
       @use_tcp = false
-      @tsig_key = nil
+      @tsig = nil
       @ignore_truncation = false
       @config = Config.new()
       @src_addr        = '0.0.0.0'
@@ -316,7 +388,7 @@ module Dnsruby
     def update #:nodoc: all
       #Update any resolvers we have with the latest config
       @single_resolvers.each do |res|
-        [:port, :use_tcp, :tsig_key, :ignore_truncation, :packet_timeout, 
+        [:port, :use_tcp, :tsig, :ignore_truncation, :packet_timeout, 
           :src_address, :src_port, :persistent_tcp, :persistent_udp, :recurse, 
           :udp_size].each do |param|
           
@@ -337,6 +409,11 @@ module Dnsruby
       add_config_nameservers
     end
     
+    #--
+    #@TODO@ Should really auto-generate these methods.
+    #Also, any way to tie them up with SingleResolver RDoc?
+    #++
+    
     def packet_timeout=(t)
       @packet_timeout = t
       update
@@ -352,8 +429,17 @@ module Dnsruby
       update
     end
     
-    def tsig_key=(t)
-      @tsig_key = t
+    #Sets the TSIG to sign outgoing messages with.
+    #Pass in either a Dnsruby::RR::TSIG, or a key_name and key (or just a key)
+    #Pass in nil to stop tsig signing.
+    #It is possible for client code to sign packets prior to sending - see
+    #Dnsruby::RR::TSIG#apply and Dnsruby::Message#sign
+    #Note that pre-signed packets will not be signed by SingleResolver.
+    #* res.tsig=(tsig_rr)
+    #* res.tsig=(key_name, key)
+    #* res.tsig=nil # Stop the resolver from signing
+    def tsig=(t)
+      @tsig=t
       update
     end
     
@@ -400,7 +486,7 @@ module Dnsruby
     #
     #Takes a bool to say whether or not to use EventMachine.
     def Resolver.use_eventmachine(on=true)
-      if (!@@event_machine_available)
+      if (on && !@@event_machine_available)
         raise RuntimeError.new("EventMachine is not available in this environment!")
       end
       @@use_eventmachine = on
@@ -552,13 +638,13 @@ module Dnsruby
       df = single_resolver.send_async(msg) # client_queue, client_query_id)
       persistent_data.to_send-=1
       df.callback { |answer|
-        TheLog.debug("Response returned, answer=#{answer}")
+        TheLog.debug("Response returned")
         persistent_data.outstanding.delete(df)
         cancel_queries(persistent_data)
         return_to_client(persistent_data.deferrable, client_queue, client_query_id, answer, nil)
       }  
       df.errback { |response, error|
-        TheLog.debug("Error #{error} returned, response=#{response}")
+        TheLog.debug("Error #{error} returned")
         persistent_data.outstanding.delete(df)
         if (response!="cancelling")
 
@@ -618,7 +704,6 @@ module Dnsruby
     end
     
     def return_to_client(deferrable, client_queue, client_query_id, answer, error)
-      TheLog.debug("Returning answer=#{answer}, error=#{error} to client")
       if (client_queue)
         client_queue.push([client_query_id, answer, error])
       end
@@ -648,10 +733,11 @@ module Dnsruby
       msg=args[0]
       client_queue=nil
       client_query_id=nil
-        client_queue=args[1]
-        if (args.length > 2)
-          client_query_id = args[2]
+      client_queue=args[1]
+      if (args.length > 2)
+        client_query_id = args[2]
       end
+
       
       # This is the whole point of the Resolver class.
       # We want to use multiple SingleResolvers to run a query.
@@ -664,7 +750,7 @@ module Dnsruby
       
       q = Queue.new
       if (client_query_id==nil)
-        client_query_id = msg
+        client_query_id = Time.now + rand(10000)
       end
       
       if (!client_queue.kind_of?Queue)
@@ -711,7 +797,7 @@ module Dnsruby
       # These are created at the same time in case the parameters change during the life of the query.
       # 
       # These should be absolute, rather than relative
-      # The first value should be Time.now
+      # The first value should be Time.now[      
       time_now = Time.now
       timeouts=@parent.generate_timeouts(time_now)
       return timeouts
@@ -732,7 +818,6 @@ module Dnsruby
     # Send the result back to the client, and close the socket for that query by removing 
     # the query from the select thread.
     def send_result_and_close(client_queue, client_query_id, select_queue, msg, error) #:nodoc: all
-      TheLog.debug("Sending result #{error} to client")
       # We might still get some callbacks, which we should ignore
       st = SelectThread.instance
       st.remove_observer(select_queue, self)