rubydns 0.5.0 → 0.5.1

data/README.md

@@ -1,9 +1,8 @@
 RubyDNS
 =======
 
-* Author: Samuel G. D. Williams (<http://www.oriontransfer.co.nz>)
-* Copyright (C) 2009, 2011 Samuel G. D. Williams.
 * Released under the MIT license.
+* Copyright (C) 2009, 2011 [Samuel G. D. Williams](http://www.codeotaku.com/samuel-williams/).
 * [![Build Status](https://secure.travis-ci.org/ioquatix/rubydns.png)](http://travis-ci.org/ioquatix/rubydns)
 
 RubyDNS is a simple programmatic DSL (domain specific language) for configuring and running a DNS server. RubyDNS provides a daemon that runs a DNS server which can process DNS requests depending on specific policy. Rule selection is based on pattern matching, and results can be hard-coded, computed, fetched from a remote DNS server, fetched from a local cache, etc.
@@ -63,8 +62,6 @@ After starting this server you can test it using dig:
 Compatibility
 -------------
 
-From RubyDNS version `0.4.0`, the recommended minimum Ruby version is `1.9.3` for complete support. Some features may not work as expected on Ruby version `1.8.x` and it is not tested significantly.
-
 ### Migrating from RubyDNS 0.3.x to 0.4.x ###
 
 Due to changes in `resolv.rb`, superficial parts of RubyDNS have changed. Rather than using `:A` to specify A-records, one must now use the class name.
@@ -76,12 +73,68 @@ becomes
 	IN = Resolv::DNS::Resource::IN
 	match(..., IN::A)
 
+### Migrating from RubyDNS 0.4.x to 0.5.x ###
+
+The system standard resolver was synchronous, and this could stall the server when making upstream requests to other DNS servers. A new resolver `RubyDNS::Resolver` now provides an asynchronous interface and the `Transaction::passthrough` makes exclusive use of this to provide high performance asynchonous resolution.
+
+Here is a basic example of how to use the new resolver in full. It is important to provide both `:udp` and `:tcp` connection specifications, so that large requests will be handled correctly:
+
+	resolver = RubyDNS::Resolver.new([[:udp, "8.8.8.8", 53], [:tcp, "8.8.8.8", 53]])
+	
+	EventMachine::run do
+		resolver.query('google.com', IN::A) do |response|
+			case response
+			when RubyDNS::Message
+				puts "Got response: #{response.answers.first}"
+			else
+				# Response is of class RubyDNS::ResolutionFailure
+				puts "Failed: #{response.message}"
+			end
+			
+			EventMachine::stop
+		end
+	end
+
+Existing code that uses `Resolv::DNS` as a resolver will need to be updated:
+
+	# 1/ Add this at the top of your file; Host specific system information:
+	require 'rubydns/system'
+	
+	# 2/ Change from R = Resolv::DNS.new to:
+	R = RubyDNS::Resolver.new(RubyDNS::System::nameservers)
+
+Everything else in the server can remain the same. You can see a complete example in `test/test_resolver.rb`.
+
+#### Deferred Transactions ####
+
+The implementation of the above depends on a new feature which was added in 0.5.0:
+
+	transaction.defer!
+
+Once you call this, the transaction won't complete until you call either `transaction.succeed` or `transaction.fail`.
+
+	RubyDNS::run_server(:listen => SERVER_PORTS) do
+		match(/\.*.com/, IN::A) do |match, transaction|
+			transaction.defer!
+			
+			# No domain exists, after 5 seconds:
+			EventMachine::Timer.new(5) do
+				transaction.failure!(:NXDomain)
+			end
+		end
+		
+		otherwise do
+			transaction.failure!(:NXDomain)
+		end
+	end
+
+You can see a complete example in `test/test_slow_server.rb`.
+
 Todo
 ----
 
-* Support for more features of DNS such as zone transfer
-* Support reverse records more easily
-* Better support for deferred requests/concurrency.
+* Support for more features of DNS such as zone transfer.
+* Support reverse records more easily.
 
 License
 -------

data/lib/rubydns.rb

@@ -21,16 +21,14 @@
 require 'rubydns/version'
 
 if RUBY_VERSION < "1.9"
-	require 'rubydns/extensions/resolv-1.8'
 	require 'rubydns/extensions/string-1.8'
 elsif RUBY_VERSION < "1.9.3"
-	require 'rubydns/extensions/resolv-1.9'
 	require 'rubydns/extensions/string-1.9.2'
 else
-	require 'rubydns/extensions/resolv-1.9'
 	require 'rubydns/extensions/string-1.9.3'
 end
 
+require 'rubydns/message'
 require 'rubydns/server'
 require 'rubydns/resolver'
 require 'rubydns/handler'

data/lib/rubydns/extensions/{resolv-1.8.rb → resolv.rb}

@@ -22,31 +22,6 @@ require 'resolv'
 
 class Resolv
 	class DNS
-		# Queries the given DNS server and returns its response in its entirety.
-		# This allows such responses to be passed upstream with little or no
-		# modification/reinterpretation.
-		def query(name, typeclass)
-			lazy_initialize
-			requester = make_requester
-			senders = {}
-			begin
-				@config.resolv(name) {|candidate, tout, nameserver|
-					msg = Message.new
-					msg.rd = 1
-					msg.add_question(candidate, typeclass)
-					unless sender = senders[[candidate, nameserver]]
-						sender = senders[[candidate, nameserver]] =
-						requester.sender(msg, candidate, nameserver)
-					end
-					reply, reply_name = requester.request(sender, tout)
-
-					return reply, reply_name
-				}
-			ensure
-				requester.close
-			end
-		end
-
 		class Message
 			# Merge the given message with this message. A number of heuristics are
 			# applied in order to ensure that the result makes sense. For example,

data/lib/rubydns/handler.rb

@@ -21,19 +21,24 @@
 require 'rubydns/message'
 
 module RubyDNS
+	
+	def self.get_peer_details(connection)
+		Socket.unpack_sockaddr_in(connection.get_peername)[1]
+	end
+	
 	module UDPHandler
 		def initialize(server)
 			@server = server
 		end
 
-		def self.process(server, data, &block)
+		def self.process(server, data, options = {}, &block)
 			server.logger.debug "Receiving incoming query (#{data.bytesize} bytes)..."
 			query = nil
 
 			begin
 				query = RubyDNS::decode_message(data)
 
-				return server.process_query(query, &block)
+				return server.process_query(query, options, &block)
 			rescue
 				server.logger.error "Error processing request!"
 				server.logger.error "#{$!.class}: #{$!.message}"
@@ -56,7 +61,9 @@ module RubyDNS
 		end
 		
 		def receive_data(data)
-			UDPHandler.process(@server, data) do |answer|
+			options = {:peer => RubyDNS::get_peer_details(self)}
+			
+			UDPHandler.process(@server, data, options) do |answer|
 				data = answer.encode
 				
 				@server.logger.debug "Writing response to client (#{data.bytesize} bytes) via UDP..."
@@ -107,7 +114,9 @@ module RubyDNS
 			if (@buffer.size - @processed) >= @length
 				data = @buffer.string.byteslice(@processed, @length)
 				
-				UDPHandler.process(@server, data) do |answer|
+				options = {:peer => RubyDNS::get_peer_details(self)}
+				
+				UDPHandler.process(@server, data, options) do |answer|
 					data = answer.encode
 					
 					@server.logger.debug "Writing response to client (#{data.bytesize} bytes) via TCP..."

data/lib/rubydns/message.rb

@@ -22,6 +22,8 @@ require 'eventmachine'
 require 'stringio'
 require 'resolv'
 
+require 'rubydns/extensions/resolv'
+
 module RubyDNS
 	UDP_TRUNCATION_SIZE = 512
 	

data/lib/rubydns/server.rb

@@ -26,6 +26,61 @@ module RubyDNS
 	# are used to match against incoming DNS questions. These rules are used to
 	# generate responses which are either DNS resource records or failures.
 	class Server
+		class Rule
+			def initialize(pattern, callback)
+				@pattern = pattern
+				@callback = callback
+			end
+			
+			def match(name, resource_class)
+				# If the pattern doesn't specify any resource classes, we implicitly pass this test:
+				return true if @pattern.size < 2
+				
+				# Otherwise, we try to match against some specific resource classes:
+				if Class === @pattern[1]
+					@pattern[1] == resource_class
+				else
+					@pattern[1].include?(resource_class) rescue false
+				end
+			end
+			
+			def call(server, name, resource_class, *args)
+				unless match(name, resource_class)
+					server.logger.debug "Resource class #{resource_class} failed to match #{@pattern[1].inspect}!"
+					
+					return false
+				end
+				
+				# Match succeeded against name?
+				case @pattern[0]
+				when Regexp
+					match_data = @pattern[0].match(name)
+					if match_data
+						server.logger.debug "Regexp pattern matched with #{match_data.inspect}."
+						return @callback[match_data, *args]
+					end
+				when String
+					if @pattern[0] == name
+						server.logger.debug "String pattern matched."
+						return @callback[*args]
+					end
+				else
+					if (@pattern[0].call(name, resource_class) rescue false)
+						server.logger.debug "Callable pattern matched."
+						return @callback[*args]
+					end
+				end
+				
+				server.logger.debug "No pattern matched."
+				# We failed to match the pattern.
+				return false
+			end
+			
+			def to_s
+				@pattern.inspect
+			end
+		end
+		
 		# Instantiate a server with a block
 		#
 		#   server = Server.new do
@@ -58,7 +113,7 @@ module RubyDNS
 		#   match(/g?mail.(com|org|net)/, [IN::MX, IN::A])
 		#
 		def match(*pattern, &block)
-			@rules << [pattern, Proc.new(&block)]
+			@rules << Rule.new(pattern, block)
 		end
 
 		# Register a named event which may be invoked later using #fire
@@ -66,7 +121,7 @@ module RubyDNS
 		#     RExec.change_user(RUN_AS)
 		#   end
 		def on(event_name, &block)
-			@events[event_name] = Proc.new(&block)
+			@events[event_name] = block
 		end
 		
 		# Fire the named event, which must have been registered using on.
@@ -87,7 +142,11 @@ module RubyDNS
 		#   end
 		#
 		def otherwise(&block)
-			@otherwise = Proc.new(&block)
+			@otherwise = block
+		end
+
+		def next!
+			throw :next
 		end
 
 		# Give a name and a record type, try to match a rule and use it for
@@ -99,55 +158,11 @@ module RubyDNS
 			@logger.debug "Searching for #{name} #{resource_class.name}"
 
 			@rules.each do |rule|
-				@logger.debug "Checking rule #{rule[0].inspect}..."
-				
-				pattern = rule[0]
-
-				# Match failed against resource_class?
-				case pattern[1]
-				when Class
-					next unless pattern[1] == resource_class
-					@logger.debug "Resource class #{resource_class.name} matched"
-				when Array
-					next unless pattern[1].include?(resource_class)
-					@logger.debug "Resource class #{resource_class} matched #{pattern[1].inspect}"
-				end
+				@logger.debug "Checking rule #{rule}..."
 
-				# Match succeeded against name?
-				case pattern[0]
-				when Regexp
-					match_data = pattern[0].match(name)
-					if match_data
-						@logger.debug "Query #{name} matched #{pattern[0].to_s} with result #{match_data.inspect}"
-						if rule[1].call(match_data, *args)
-							@logger.debug "Rule returned successfully"
-							return
-						end
-					else
-						@logger.debug "Query #{name} failed to match against #{pattern[0].to_s}"
-					end
-				when String
-					if pattern[0] == name
-						@logger.debug "Query #{name} matched #{pattern[0]}"
-						if rule[1].call(*args)
-							@logger.debug "Rule returned successfully"
-							return
-						end
-					else
-						@logger.debug "Query #{name} failed to match against #{pattern[0]}"
-					end
-				else
-					if pattern[0].respond_to? :call
-						if pattern[0].call(name)
-							@logger.debug "Query #{name} matched #{pattern[0]}"
-							if rule[1].call(*args)
-								@logger.debug "Rule returned successfully"
-								return
-							end
-						else
-							@logger.debug "Query #{name} failed to match against #{pattern[0]}"
-						end
-					end
+				catch (:next) do
+					# If the rule returns true, we assume that it was successful and no further rules need to be evaluated.
+					return true if rule.call(self, name, resource_class, *args)
 				end
 			end
 
@@ -160,7 +175,7 @@ module RubyDNS
 
 		# Process an incoming DNS message. Returns a serialized message to be
 		# sent back to the client.
-		def process_query(query, &block)
+		def process_query(query, options = {}, &block)
 			# Setup answer
 			answer = Resolv::DNS::Message::new(query.id)
 			answer.qr = 1                 # 0 = Query, 1 = Response
@@ -186,7 +201,7 @@ module RubyDNS
 				chain << lambda do
 					@logger.debug "Processing question #{question} #{resource_class}..."
 
-					transaction = Transaction.new(self, query, question, resource_class, answer)
+					transaction = Transaction.new(self, query, question, resource_class, answer, options)
 					
 					# Call the next link in the chain:
 					transaction.callback do
@@ -196,9 +211,16 @@ module RubyDNS
 
 					# If there was an error, log it and fail:
 					transaction.errback do |response|
-						@logger.error "Exception thrown while processing #{transaction}!"
-						@logger.error "#{response.class}: #{response.message}"
-						response.backtrace.each { |at| @logger.error at }
+						if Exception === response
+							@logger.error "Exception thrown while processing #{transaction}!"
+							@logger.error "#{response.class}: #{response.message}"
+							if response.backtrace
+								Array(response.backtrace).each { |at| @logger.error at }
+							end
+						else
+							@logger.error "Failure while processing #{transaction}!"
+							@logger.error "#{response.inspect}"
+						end
 
 						answer.rcode = Resolv::DNS::RCode::ServFail
 

data/lib/rubydns/transaction.rb

@@ -27,13 +27,15 @@ module RubyDNS
 	class Transaction
 		include EventMachine::Deferrable
 		
-		def initialize(server, query, question, resource_class, answer)
+		def initialize(server, query, question, resource_class, answer, options = {})
 			@server = server
 			@query = query
 			@question = question
 			@resource_class = resource_class
 			@answer = answer
 
+			@options = options
+
 			@deferred = false
 			@question_appended = false
 		end
@@ -51,6 +53,9 @@ module RubyDNS
 		# The current full answer to the incoming query.
 		attr :answer
 		
+		# Any options or configuration associated with the given transaction.
+		attr :options
+		
 		# Return the name of the question, which is typically the requested hostname.
 		def name
 			@question.to_s
@@ -63,8 +68,8 @@ module RubyDNS
 
 		# Run a new query through the rules with the given name and resource type. The
 		# results of this query are appended to the current transactions <tt>answer</tt>.
-		def append_query!(name, resource_class = nil)
-			Transaction.new(@server, @query, name, resource_class || @resource_class, @answer).process
+		def append_query!(name, resource_class = nil, options = {})
+			Transaction.new(@server, @query, name, resource_class || @resource_class, @answer, options).process
 		end
 
 		def process(&finished)
@@ -93,6 +98,8 @@ module RubyDNS
 				end
 				
 				@answer.merge!(response)
+				
+				succeed if @deferred
 			end
 			
 			true
@@ -117,8 +124,10 @@ module RubyDNS
 					case response
 					when RubyDNS::Message
 						yield response
-						succeed(response)
+					when RubyDNS::ResolverFailure
+						failure!(:ServFail)
 					else
+						# This shouldn't ever happen, but if it does for some reason we shouldn't hang.
 						fail(response)
 					end
 				end
@@ -166,6 +175,8 @@ module RubyDNS
 		# 
 		# <tt>options[:ttl]</tt>:: Specify the TTL for the resource
 		# <tt>options[:name]</tt>:: Override the name (question) of the response.
+		# <tt>options[:section]</tt>:: Specify whether the response should go in the `:answer`
+		#                             `:authority` or `:additional` section.
 		# 
 		# This function can be used to supply multiple responses to a given question.
 		# For example, each argument is expected to be an instantiated resource from
@@ -173,17 +184,27 @@ module RubyDNS
 		def append! (*resources)
 			append_question!
 
-			options = resources.last.kind_of?(Hash) ? resources.pop.dup : {}
+			if resources.last.kind_of?(Hash)
+				options = resources.pop
+			else
+				options = {}
+			end
+
+			# Use the default options if provided:
+			options = options.merge(@options)
+
 			options[:ttl] ||= 16000
 			options[:name] ||= @question.to_s + "."
+			
+			method = ("add_" + (options[:section] || 'answer').to_s).to_sym
 
 			resources.each do |resource|
-				@server.logger.debug "add_answer: #{resource.inspect} #{resource.class::TypeValue} #{resource.class::ClassValue}"
-				@answer.add_answer(options[:name], options[:ttl], resource)
+				@server.logger.debug "#{method}: #{resource.inspect} #{resource.class::TypeValue} #{resource.class::ClassValue}"
+				
+				@answer.send(method, options[:name], options[:ttl], resource)
 			end
 
-			# Raise an exception if there was something wrong with the resource
-			@answer.encode
+			succeed if @deferred
 
 			true
 		end
@@ -214,6 +235,9 @@ module RubyDNS
 				@answer.rcode = rcode.to_i
 			end
 
+			# The transaction itself has completed, but contains a failure:
+			succeed(rcode) if @deferred
+
 			true
 		end