rubydns 0.6.7 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 027557f4aae547ca2ae32cc66c59909b6a6bee56
-  data.tar.gz: f19af2749cdff025edbf9b7d8e8e6546c4911377
+  metadata.gz: 190faf76114f4bfe4bcbff8896f6d54ff4d75667
+  data.tar.gz: 76d443584858fdfb9d8223215c47b3935d22f53c
 SHA512:
-  metadata.gz: bd783eaa39bb28ae521da7b20aaea97636e8c3dfe492864f0c299f7264d786407ecebce88d2e759c42c7e08aff448a914e1913243fafda6d9bf2bdf6489177e2
-  data.tar.gz: 932b3c6332d87ca10684b42d34cc37b7738730ddb489afd7b08df0f54606ef24560c772e7f30c316b40652d7483d7e3f0f15312cc0f4e68df7a9ba84783d1f14
+  metadata.gz: 2d850649e8bb3f66638a30519898ece93a710c08925e83a8ca6ef15fce6474f80795133d71dfac0f67756f8945596771ddc6c0e98d6fd554a40e081b6ba41e61
+  data.tar.gz: e797f439ff7aaa0de6b2cbe15621ebf514a24a39441b200ccc09a15cc8baabc6fbfdf5ab95e69c40f31ef2925addce7f436bf5ea8598861bbbb7e072e922f2a5

data/.travis.yml

@@ -1,6 +1,6 @@
 language: ruby
 rvm:
-  - "1.9.2"
-  - "1.9.3"
-  - "2.0"
-  - rbx-19mode
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0

data/.yardopts

@@ -0,0 +1 @@
+--markup=markdown

data/README.md

@@ -29,122 +29,128 @@ Or install it yourself as:
 
 This is copied from `test/examples/test-dns-2.rb`. It has been simplified slightly.
 
-```ruby
-#!/usr/bin/env ruby
-require 'rubydns'
-
-INTERFACES = [
-	[:udp, "0.0.0.0", 53],
-	[:tcp, "0.0.0.0", 53]
-]
-Name = Resolv::DNS::Name
-IN = Resolv::DNS::Resource::IN
-
-# Use upstream DNS for name resolution.
-UPSTREAM = RubyDNS::Resolver.new([[:udp, "8.8.8.8", 53], [:tcp, "8.8.8.8", 53]])
-
-def self.run
-    # Start the RubyDNS server
-    RubyDNS::run_server(:listen => INTERFACES) do
-        match(/test.mydomain.org/, IN::A) do |transaction|
-            transaction.respond!("10.0.0.80")
-        end
-
-        # Default DNS handler
-        otherwise do |transaction|
-            transaction.passthrough!(UPSTREAM)
-        end
-    end
-end
-run
-```
+	#!/usr/bin/env ruby
+	require 'rubydns'
+
+	INTERFACES = [
+		[:udp, "0.0.0.0", 53],
+		[:tcp, "0.0.0.0", 53]
+	]
+	Name = Resolv::DNS::Name
+	IN = Resolv::DNS::Resource::IN
+
+	# Use upstream DNS for name resolution.
+	UPSTREAM = RubyDNS::Resolver.new([[:udp, "8.8.8.8", 53], [:tcp, "8.8.8.8", 53]])
+
+	def self.run
+	    # Start the RubyDNS server
+	    RubyDNS::run_server(:listen => INTERFACES) do
+	        match(/test.mydomain.org/, IN::A) do |transaction|
+	            transaction.respond!("10.0.0.80")
+	        end
+
+	        # Default DNS handler
+	        otherwise do |transaction|
+	            transaction.passthrough!(UPSTREAM)
+	        end
+	    end
+	end
+	run
 
 Start the server using `rvmsudo ./test.rb`. You can then test it using dig:
 
-```
-$ dig @localhost test1.mydomain.org
-$ dig @localhost dev.mydomain.org
-$ dig @localhost google.com
-```
+	$ dig @localhost test1.mydomain.org
+	$ dig @localhost dev.mydomain.org
+	$ dig @localhost google.com
 
 ## Compatibility
 
-### Migrating from RubyDNS 0.5.x to 0.6.x ###
+### Migrating from RubyDNS 0.6.x to 0.7.x
+
+The asynchronous deferred processing became the default and only method for processing requests in `0.7.0`. This simplifies the API but there were a few changes, notably the removal of `defer!` and the addition of `defer`. The reason for this was due to issues relating to deferred processing and the flow of control, which were confusing and introduced bugs in specific situations. Now, you can assume flow control through the entire block even with non-blocking functions.
+
+	RubyDNS::run_server(:listen => SERVER_PORTS) do
+		match(/\.*.com/, IN::A) do |transaction|
+			# Won't block and won't continue until handle.resume is called.
+			defer do |fiber|
+				# No domain exists, after 5 seconds:
+				EventMachine::Timer.new(5) do
+					transaction.fail!(:NXDomain)
+					
+					fiber.resume
+				end
+			end
+		end
+
+		otherwise do
+			transaction.fail!(:NXDomain)
+		end
+	end
+
+You can see a complete example in `test/test_slow_server.rb`.
+
+#### Server structure changes
+
+When integrating RubyDNS into another project, the rule based DSL is often a hurdle rather than a feature. Thus, the rule-based DSL component of `RubyDNS::Server` class has been separated into a derived `RubyDNS::RuleBasedServer` class. `RubyDNS::Server` can be derived and the `RubyDNS::Server#process` method can be overridden to provide a single entry point for DNS processing.
+
+In addition, `RubyDNS::Server#run` can now start the server, provided you are within an `EventMachine#run` context. The existing entry point, `RubyDNS::run_server` provides the same rule-based DSL as previous versions.
+
+#### Method name changes
+
+Some method names have changed to improve consistency.
+
+- `failure!` became `fail!`
+- `append` became `add`
+- `append_query!` became `append!`
+
+### Migrating from RubyDNS 0.5.x to 0.6.x
 
 The order of arguments to pattern based rules has changed. For regular expression based rules, the arguments are now ordered `|transaction, match_data|`. The main reason for this change was that in many cases match_data is not important and can thus be ignored, e.g. `|transaction|`.
 
 Going forward, Ruby 1.8.x is no longer supported.
 
-### 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.
-```ruby
-match(..., :A)
-```
-becomes
-```ruby
-IN = Resolv::DNS::Resource::IN
-match(..., IN::A)
-```
-### Migrating from RubyDNS 0.4.x to 0.5.x ###
+### 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:
-```ruby
-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
+	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
-end
-```
+
 Existing code that uses `Resolv::DNS` as a resolver will need to be updated:
-```ruby
-# 1/ Add this at the top of your file; Host specific system information:
-require 'rubydns/system'
+
+	# 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`.
+	# 2/ Change from R = Resolv::DNS.new to:
+	R = RubyDNS::Resolver.new(RubyDNS::System::nameservers)
 
-#### Deferred Transactions ####
+Everything else in the server can remain the same. You can see a complete example in `test/test_resolver.rb`.
 
-The implementation of the above depends on a new feature which was added in 0.5.0:
+### Migrating from RubyDNS 0.3.x to 0.4.x
 
-```ruby
-transaction.defer!
-```
+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.
 
-Once you call this, the transaction won't complete until you call either `transaction.succeed` or `transaction.fail`.
-```ruby
-RubyDNS::run_server(:listen => SERVER_PORTS) do
-	match(/\.*.com/, IN::A) do |transaction|
-		transaction.defer!
-		
-		# No domain exists, after 5 seconds:
-		EventMachine::Timer.new(5) do
-			transaction.failure!(:NXDomain)
-		end
-	end
+	match(..., :A)
 
-	otherwise do
-		transaction.failure!(:NXDomain)
-	end
-end
-```
+becomes
 
-You can see a complete example in `test/test_slow_server.rb`.
+	IN = Resolv::DNS::Resource::IN
+	match(..., IN::A)
 
 ## Contributing
 
@@ -163,7 +169,7 @@ You can see a complete example in `test/test_slow_server.rb`.
 
 Released under the MIT license.
 
-Copyright, 2009, 2012, by [Samuel G. D. Williams](http://www.codeotaku.com/samuel-williams).
+Copyright, 2009, 2012, 2014, by [Samuel G. D. Williams](http://www.codeotaku.com/samuel-williams).
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/rubydns.rb

@@ -20,14 +20,6 @@
 
 require 'rubydns/version'
 
-if RUBY_VERSION < "1.9"
-	require 'rubydns/extensions/string-1.8'
-elsif RUBY_VERSION < "1.9.3"
-	require 'rubydns/extensions/string-1.9.2'
-else
-	require 'rubydns/extensions/string-1.9.3'
-end
-
 require 'rubydns/message'
 require 'rubydns/server'
 require 'rubydns/resolver'
@@ -42,50 +34,16 @@ require 'rubydns/handler'
 
 module RubyDNS
 	
-	# Run a server with the given rules. A number of options can be supplied:
-	#
-	# <tt>:interfaces</tt>:: A set of sockets or addresses as defined below.
-	#
-	# One important feature of DNS is the port it runs on. The <tt>options[:listen]</tt>
-	# allows you to specify a set of network interfaces and ports to run the server on. This
-	# must be a list of <tt>[protocol, interface address, port]</tt>.
-	# 
-	#   INTERFACES = [[:udp, "0.0.0.0", 5300]]
-	#   RubyDNS::run_server(:listen => INTERFACES) do
-	#     ...
-	#   end
-	#
-	# You can specify already connected sockets if need be:
-	#
-	#   socket = UDPSocket.new; socket.bind("0.0.0.0", 53)
-	#   Process::Sys.setuid(server_uid)
-	#   INTERFACES = [socket]
-	#
-	# The default interface is <tt>[[:udp, "0.0.0.0", 53]]</tt>. The server typically needs
-	# to run as root for this to work, since port 53 is privileged.
-	#
+	# Run a server with the given rules.
 	def self.run_server (options = {}, &block)
-		server = RubyDNS::Server.new(&block)
-		server.logger.info "Starting RubyDNS server (v#{RubyDNS::VERSION})..."
-		
-		options[:listen] ||= [[:udp, "0.0.0.0", 53], [:tcp, "0.0.0.0", 53]]
+		server = RubyDNS::RuleBasedServer.new(&block)
 		
 		EventMachine.run do
-			server.fire(:setup)
-			
-			# Setup server sockets
-			options[:listen].each do |spec|
-				server.logger.info "Listening on #{spec.join(':')}"
-				if spec[0] == :udp
-					EventMachine.open_datagram_socket(spec[1], spec[2], UDPHandler, server)
-				elsif spec[0] == :tcp
-					EventMachine.start_server(spec[1], spec[2], TCPHandler, server)
-				end
-			end
-			
-			server.fire(:start)
+			server.run(options)
 		end
 		
 		server.fire(:stop)
 	end
+	
+	
 end

data/lib/rubydns/{extensions/string-1.9.3.rb → binary_string.rb}

@@ -1,3 +1,4 @@
+
 # Copyright, 2009, 2012, by Samuel G. D. Williams. <http://www.codeotaku.com>
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -21,6 +22,7 @@
 require 'stringio'
 
 module RubyDNS
+	# A helper class for processing incoming network data.
 	class BinaryStringIO < StringIO
 		def initialize
 			super

data/lib/rubydns/extensions/logger.rb

@@ -19,7 +19,7 @@
 # THE SOFTWARE.
 
 module RubyDNS
-	# Logs an exception nicely.
+	# Logs an exception nicely to a standard `Logger`.
 	def self.log_exception(logger, exception)
 		logger.error "#{exception.class}: #{exception.message}"
 		if exception.backtrace

data/lib/rubydns/extensions/resolv.rb

@@ -23,11 +23,7 @@ require 'resolv'
 class Resolv
 	class DNS
 		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,
-			# If the current message is not recursive but is being merged with a
-			# message that was recursive, this bit is maintained. If either message
-			# is authoritive, then the result is also authoritive.
+			# Merge the given message with this message. A number of heuristics are applied in order to ensure that the result makes sense. For example, If the current message is not recursive but is being merged with a message that was recursive, this bit is maintained. If either message is authoritive, then the result is also authoritive.
 			#
 			# Modifies the current message in place.
 			def merge! (other)

data/lib/rubydns/extensions/string.rb

@@ -21,6 +21,7 @@
 require 'rubydns/chunked'
 
 class String
+	# Chunk a string which is required for the TEXT `resource_class`.
 	def chunked(chunk_size = 255)
 		RubyDNS::chunked(self)
 	end

data/lib/rubydns/handler.rb

@@ -19,18 +19,21 @@
 # THE SOFTWARE.
 
 require 'rubydns/message'
+require 'rubydns/binary_string'
 
 module RubyDNS
-	
+	# @returns the [port, ip address] of the given connection.
 	def self.get_peer_details(connection)
 		Socket.unpack_sockaddr_in(connection.get_peername)
 	end
 	
+	# Handling incoming UDP requests, which are single data packets, and pass them on to the given server.
 	module UDPHandler
 		def initialize(server)
 			@server = server
 		end
-
+		
+		# Process a packet of data with the given server. If an exception is thrown, a failure message will be sent back.
 		def self.process(server, data, options = {}, &block)
 			server.logger.debug "Receiving incoming query (#{data.bytesize} bytes)..."
 			query = nil
@@ -98,6 +101,7 @@ module RubyDNS
 			@processed = 0
 		end
 		
+		# Receive the data via a TCP connection, process messages when we receive the indicated amount of data.
 		def receive_data(data)
 			# We buffer data until we've received the entire packet:
 			@buffer.write(data)
@@ -132,6 +136,7 @@ module RubyDNS
 			end
 		end
 		
+		# Check that all data received was processed.
 		def unbind
 			if @processed != @buffer.size
 				raise LengthError.new("Unprocessed data remaining (#{@buffer.size - @processed} bytes unprocessed)")

data/lib/rubydns/message.rb

@@ -46,18 +46,31 @@ module RubyDNS
 			RubyDNS.log_exception(bad_messages_log, error)
 		end
 	end
-
+	
+	# Decodes binary data into a {Message}.
 	def self.decode_message(data)
+		# Otherwise the decode process might fail with non-binary data.
 		if data.respond_to? :force_encoding
 			data.force_encoding("BINARY")
 		end
 		
-		Message.decode(data)
+		begin
+			return Message.decode(data)
+		rescue DecodeError
+			raise
+		rescue StandardError => error
+			new_error = DecodeError.new(error.message)
+			new_error.set_backtrace(error.backtrace)
+			
+			raise new_error
+		end
+		
 	rescue => error
+		# Log the bad messsage if required:
 		if @dump_bad_message
-			@dump_bad_message.call(StandardError.new("foo"), data)
+			@dump_bad_message.call(error, data)
 		end
 		
 		raise
 	end
-end
+end