rubydns 0.6.7 → 0.7.0

data/lib/rubydns/resolver.rb

@@ -19,6 +19,7 @@
 # THE SOFTWARE.
 
 require 'rubydns/message'
+require 'rubydns/binary_string'
 
 module RubyDNS
 	class InvalidProtocolError < StandardError
@@ -117,6 +118,7 @@ module RubyDNS
 				try_next_server!
 			end
 			
+			# Once either an exception or message is received, we update the status of this request.
 			def process_response!(response)
 				finish_request!
 				
@@ -142,6 +144,7 @@ module RubyDNS
 			
 			private
 			
+			# Closes any connections and cancels any timeout.
 			def finish_request!
 				cancel_timeout
 				

data/lib/rubydns/server.rb

@@ -18,21 +18,127 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require 'fiber'
+
 require 'rubydns/transaction'
 require 'rubydns/extensions/logger'
 
 module RubyDNS
 	
-	# This class provides the core of the DSL. It contains a list of rules which
-	# 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
+		# The default server interfaces
+		DEFAULT_INTERFACES = [[:udp, "0.0.0.0", 53], [:tcp, "0.0.0.0", 53]]
+		
+		# Instantiate a server with a block
+		#
+		#	server = Server.new do
+		#		match(/server.mydomain.com/, IN::A) do |transaction|
+		#			transaction.respond!("1.2.3.4")
+		#		end
+		#	end
+		#
+		def initialize
+			@logger = Logger.new($stderr)
+		end
+
+		attr_accessor :logger
+
+		# Fire the named event as part of running the server.
+		def fire(event_name)
+		end
+		
+		# Give a name and a record type, try to match a rule and use it for processing the given arguments.
+		def process(name, resource_class, transaction)
+			raise NotImplementedError.new
+		end
+		
+		# Process a block with the current fiber. To resume processing from the block, call `fiber.resume`. You shouldn't call `fiber.resume` until after the top level block has returned.
+		def defer(&block)
+			fiber = Fiber.current
+			
+			yield(fiber)
+			
+			Fiber.yield
+		end
+		
+		# Process an incoming DNS message. Returns a serialized message to be sent back to the client.
+		def process_query(query, options = {}, &block)
+			# Setup answer
+			answer = Resolv::DNS::Message::new(query.id)
+			answer.qr = 1                 # 0 = Query, 1 = Response
+			answer.opcode = query.opcode  # Type of Query; copy from query
+			answer.aa = 1                 # Is this an authoritative response: 0 = No, 1 = Yes
+			answer.rd = query.rd          # Is Recursion Desired, copied from query
+			answer.ra = 0                 # Does name server support recursion: 0 = No, 1 = Yes
+			answer.rcode = 0              # Response code: 0 = No errors
+			
+			Fiber.new do
+				transaction = nil
+				
+				begin
+					query.question.each do |question, resource_class|
+						@logger.debug "Processing question #{question} #{resource_class}..."
+				
+						transaction = Transaction.new(self, query, question, resource_class, answer, options)
+						
+						transaction.process
+					end
+				rescue
+					@logger.error "Exception thrown while processing #{transaction}!"
+					RubyDNS.log_exception(@logger, $!)
+				
+					answer.rcode = Resolv::DNS::RCode::ServFail
+				end
+			
+				yield answer
+			end.resume
+		end
+		
+		#
+		# By default the server runs on port 53, both TCP and UDP, which is usually a priviledged port and requires root access to bind. You can change this by specifying `options[:listen]` which should contain an array of `[protocol, interface address, port]` specifications.
+		# 
+		#	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]
+		#
+		def run(options = {})
+			@logger.info "Starting RubyDNS server (v#{RubyDNS::VERSION})..."
+		
+			interfaces = options[:listen] || DEFAULT_INTERFACES
+		
+			fire(:setup)
+		
+			# Setup server sockets
+			interfaces.each do |spec|
+				@logger.info "Listening on #{spec.join(':')}"
+				if spec[0] == :udp
+					EventMachine.open_datagram_socket(spec[1], spec[2], UDPHandler, self)
+				elsif spec[0] == :tcp
+					EventMachine.start_server(spec[1], spec[2], TCPHandler, self)
+				end
+			end
+		
+			fire(:start)
+		end
+	end
+	
+	# Provides the core of the RubyDNS domain-specific language (DSL). It contains a list of rules which are used to match against incoming DNS questions. These rules are used to generate responses which are either DNS resource records or failures.
+	class RuleBasedServer < Server
+		# Represents a single rule in the server.
 		class Rule
 			def initialize(pattern, callback)
 				@pattern = pattern
 				@callback = callback
 			end
 			
+			# Returns true if the name and resource_class are sufficient:
 			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
@@ -45,6 +151,7 @@ module RubyDNS
 				end
 			end
 			
+			# Invoke the rule, if it matches the incoming request, it is evaluated and returns `true`, otherwise returns `false`.
 			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}!"
@@ -52,27 +159,38 @@ module RubyDNS
 					return false
 				end
 				
-				# Match succeeded against name?
+				# Does this rule match against the supplied 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[*args, match_data]
+						
+						@callback[*args, match_data]
+						
+						return true
 					end
 				when String
 					if @pattern[0] == name
 						server.logger.debug "String pattern matched."
-						return @callback[*args]
+						
+						@callback[*args]
+						
+						return true
 					end
 				else
 					if (@pattern[0].call(name, resource_class) rescue false)
 						server.logger.debug "Callable pattern matched."
-						return @callback[*args]
+						
+						@callback[*args]
+						
+						return true
 					end
 				end
 				
 				server.logger.debug "No pattern matched."
+				
 				# We failed to match the pattern.
 				return false
 			end
@@ -84,19 +202,19 @@ module RubyDNS
 		
 		# Instantiate a server with a block
 		#
-		#   server = Server.new do
-		#     match(/server.mydomain.com/, IN::A) do |transaction|
-		#       transaction.respond!("1.2.3.4")
-		#     end
-		#   end
+		#	server = Server.new do
+		#		match(/server.mydomain.com/, IN::A) do |transaction|
+		#			transaction.respond!("1.2.3.4")
+		#		end
+		#	end
 		#
 		def initialize(&block)
+			super()
+			
 			@events = {}
 			@rules = []
 			@otherwise = nil
-
-			@logger = Logger.new($stderr)
-
+			
 			if block_given?
 				instance_eval &block
 			end
@@ -104,23 +222,21 @@ module RubyDNS
 
 		attr_accessor :logger
 
-		# This function connects a pattern with a block. A pattern is either
-		# a String or a Regex instance. Optionally, a second argument can be
-		# provided which is either a String, Symbol or Array of resource record
-		# types which the rule matches against.
+		# This function connects a pattern with a block. A pattern is either a String or a Regex instance. Optionally, a second argument can be provided which is either a String, Symbol or Array of resource record types which the rule matches against.
 		# 
-		#   match("www.google.com")
-		#   match("gmail.com", IN::MX)
-		#   match(/g?mail.(com|org|net)/, [IN::MX, IN::A])
+		#	match("www.google.com")
+		#	match("gmail.com", IN::MX)
+		#	match(/g?mail.(com|org|net)/, [IN::MX, IN::A])
 		#
 		def match(*pattern, &block)
 			@rules << Rule.new(pattern, block)
 		end
 
 		# Register a named event which may be invoked later using #fire
-		#   on(:start) do |server|
-		#     RExec.change_user(RUN_AS)
-		#   end
+		#
+		#	on(:start) do |server|
+		#		RExec.change_user(RUN_AS)
+		#	end
 		def on(event_name, &block)
 			@events[event_name] = block
 		end
@@ -134,48 +250,51 @@ module RubyDNS
 			end
 		end
 		
-		# Specify a default block to execute if all other rules fail to match.
-		# This block is typially used to pass the request on to another server
-		# (i.e. recursive request).
+		# Specify a default block to execute if all other rules fail to match. This block is typially used to pass the request on to another server (i.e. recursive request).
 		#
-		#   otherwise do |transaction|
-		#     transaction.passthrough!($R)
-		#   end
+		#	otherwise do |transaction|
+		#		transaction.passthrough!($R)
+		#	end
 		#
 		def otherwise(&block)
 			@otherwise = block
 		end
-
+		
+		# If you match a rule, but decide within the rule that it isn't the correct one to use, you can call `next!` to evaluate the next rule - in other words, to continue falling down through the list of rules.
 		def next!
 			throw :next
 		end
-
-		# Give a name and a record type, try to match a rule and use it for
-		# processing the given arguments.
-		#
-		# If a rule returns false, it is considered that the rule failed and
-		# futher matching is carried out.
+		
+		# Give a name and a record type, try to match a rule and use it for processing the given arguments.
 		def process(name, resource_class, *args)
 			@logger.debug "Searching for #{name} #{resource_class.name}"
-
+			
 			@rules.each do |rule|
 				@logger.debug "Checking rule #{rule}..."
-
+				
 				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)
+					return if rule.call(self, name, resource_class, *args)
 				end
 			end
-
+			
 			if @otherwise
 				@otherwise.call(*args)
 			else
 				@logger.warn "Failed to handle #{name} #{resource_class.name}!"
 			end
 		end
-
-		# Process an incoming DNS message. Returns a serialized message to be
-		# sent back to the client.
+		
+		# Process a block with the current fiber. To resume processing from the block, call `fiber.resume`. You shouldn't call `fiber.resume` until after the top level block has returned.
+		def defer(&block)
+			fiber = Fiber.current
+			
+			yield(fiber)
+			
+			Fiber.yield
+		end
+		
+		# Process an incoming DNS message. Returns a serialized message to be sent back to the client.
 		def process_query(query, options = {}, &block)
 			# Setup answer
 			answer = Resolv::DNS::Message::new(query.id)
@@ -185,57 +304,27 @@ module RubyDNS
 			answer.rd = query.rd          # Is Recursion Desired, copied from query
 			answer.ra = 0                 # Does name server support recursion: 0 = No, 1 = Yes
 			answer.rcode = 0              # Response code: 0 = No errors
-
-			# 1/ This chain contains a reverse list of question lambdas.
-			chain = []
-
-			# 4/ Finally, the answer is given back to the calling block:
-			chain << lambda do
-				@logger.debug "Passing answer back to caller..."
-				yield answer
-			end
-
-			# There may be multiple questions per query
-			query.question.reverse.each do |question, resource_class|
-				next_link = chain.last
-
-				chain << lambda do
-					@logger.debug "Processing question #{question} #{resource_class}..."
-
-					transaction = Transaction.new(self, query, question, resource_class, answer, options)
-					
-					# Call the next link in the chain:
-					transaction.callback do
-						# 3/ ... which calls the previous item in the chain, i.e. the next question to be answered:
-						next_link.call
-					end
-
-					# If there was an error, log it and fail:
-					transaction.errback do |response|
-						if Exception === response
-							@logger.error "Exception thrown while processing #{transaction}!"
-							RubyDNS.log_exception(@logger, response)
-						else
-							@logger.error "Failure while processing #{transaction}!"
-							@logger.error "#{response.inspect}"
-						end
-
-						answer.rcode = Resolv::DNS::RCode::ServFail
-
-						chain.first.call
-					end
-					
-					begin
-						# Transaction.process will call succeed if it wasn't deferred:
+			
+			Fiber.new do
+				transaction = nil
+				
+				begin
+					query.question.each do |question, resource_class|
+						@logger.debug "Processing question #{question} #{resource_class}..."
+				
+						transaction = Transaction.new(self, query, question, resource_class, answer, options)
+						
 						transaction.process
-					rescue
-						transaction.fail($!)
 					end
+				rescue
+					@logger.error "Exception thrown while processing #{transaction}!"
+					RubyDNS.log_exception(@logger, $!)
+				
+					answer.rcode = Resolv::DNS::RCode::ServFail
 				end
-			end
-
-			# 2/ We call the last lambda...
-			chain.last.call
+			
+				yield answer
+			end.resume
 		end
 	end
 end

data/lib/rubydns/transaction.rb

@@ -21,11 +21,16 @@
 require 'eventmachine'
 
 module RubyDNS
-
-	# This class provides all details of a single DNS question and answer. This
-	# is used by the DSL to provide DNS related functionality.
+	
+	class PassthroughError < StandardError
+	end
+	
+	# This class provides all details of a single DNS question and answer. This is used by the DSL to provide DNS related functionality.
+	# 
+	# The main functions to complete the trasaction are: {#append!} (evaluate a new query and append the results), {#passthrough!} (pass the query to an upstream server), {#respond!} (compute a specific response) and {#fail!} (fail with an error code).
 	class Transaction
-		include EventMachine::Deferrable
+		# The default time used for responses (24 hours).
+		DEFAULT_TTL = 86400
 		
 		def initialize(server, query, question, resource_class, answer, options = {})
 			@server = server
@@ -36,12 +41,12 @@ module RubyDNS
 
 			@options = options
 
-			@deferred = false
 			@question_appended = false
+
+			@fiber = nil
 		end
 
-		# The resource_class that was requested. This is typically used to generate a
-		# response.
+		# The resource_class that was requested. This is typically used to generate a response.
 		attr :resource_class
 		
 		# The incoming query which is a set of questions.
@@ -56,198 +61,154 @@ module RubyDNS
 		# Any options or configuration associated with the given transaction.
 		attr :options
 		
-		# Return the name of the question, which is typically the requested hostname.
+		# The name of the question, which is typically the requested hostname.
 		def name
 			@question.to_s
 		end
-
-		# Suitable for debugging purposes
+		
+		# Shows the question name and resource class. Suitable for debugging purposes.
 		def to_s
 			"#{name} #{@resource_class.name}"
 		end
-
-		# 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, options = {})
+		
+		# Run a new query through the rules with the given name and resource type. The results of this query are appended to the current transaction's `answer`.
+		def append!(name, resource_class = nil, options = {})
 			Transaction.new(@server, @query, name, resource_class || @resource_class, @answer, options).process
 		end
-
-		def process(&finished)
-			@server.process(name, @resource_class, self)
-
-			unless @deferred
-				succeed(self)
-			end
-		end
-
-		def defer!
-			@deferred = true
-		end
-
-		# Use the given resolver to respond to the question. The default functionality is
-		# implemented by passthrough, and if a reply is received, it will be merged with the
-		# answer for this transaction.
+		
+		# Use the given resolver to respond to the question. Uses `passthrough` to do the lookup and merges the result.
+		#
+		# If a block is supplied, this function yields with the `reply` and `reply_name` if successful. This could be used, for example, to update a cache or modify the reply.
+		#
+		# If recursion is not requested, the result is `fail!(:Refused)`. This check is ignored if an explicit `options[:name]` or `options[:force]` is given.
 		#
-		# If a block is supplied, this function yields with the reply and reply_name if
-		# successful. This could be used, for example, to update a cache or modify the
-		# reply.
+		# If the resolver does not respond, the result is `fail!(:NXDomain)`.
 		def passthrough!(resolver, options = {}, &block)
-			passthrough(resolver, options) do |response|
-				if block_given?
-					yield response
-				end
-				
-				@answer.merge!(response)
+			if @query.rd || options[:force] || options[:name]
+				passthrough(resolver, options) do |response|
+					if block_given?
+						yield response
+					end
 				
-				succeed if @deferred
+					@answer.merge!(response)
+				end
+			else
+				raise PassthroughError.new("Request is not recursive!")
 			end
-			
-			true
 		end
 		
-		# Use the given resolver to respond to the question. If recursion is
-		# not requested, the result is <tt>failure!(:Refused)</tt>. If the resolver does
-		# not respond, the result is <tt>failure!(:NXDomain)</tt>
-		#
-		# If a block is supplied, this function yields with the reply and reply_name if
-		# successful. This block is responsible for doing something useful with the reply,
-		# such as merging it or conditionally discarding it.
+		# Use the given resolver to respond to the question.
+		# 
+		# A block must be supplied, and provided a valid response is received from the upstream server, this function yields with the reply and reply_name.
 		#
-		# A second argument, options, provides some control over the passthrough process.
-		# :force => true, ensures that the query will occur even if recursion is not requested.
-		# :name => resource_name, override the name for the request as it is passed to 
-		# the resolver. Implies :force.
-		# :resource_class => class, overried the resource class for a request as it is passed
-		# to the resolver.
+		# If `options[:name]` is provided, this overrides the default query name sent to the upstream server. The same logic applies to `options[:resource_class]`.
 		def passthrough(resolver, options = {}, &block)
-			if @query.rd || options[:force] || options[:name]
-				# Resolver is asynchronous, so we are now deferred:
-				defer!
-
-				query_name = options[:name] || name
-				query_resource_class = options[:resource_class] || resource_class
-
+			query_name = options[:name] || name
+			query_resource_class = options[:resource_class] || resource_class
+			
+			response = @server.defer do |handle|
 				resolver.query(query_name, query_resource_class) do |response|
-					case response
-					when RubyDNS::Message
-						yield response
-					when RubyDNS::ResolutionFailure
-						failure!(:ServFail)
-					else
-						# This shouldn't ever happen, but if it does for some reason we shouldn't hang.
-						fail(response)
-					end
+					# Not sure if this is potentially a race condition? Could fiber.resume occur before Fiber.yield?
+					handle.resume(response)
 				end
-			else
-				failure!(:Refused)
 			end
 			
-			true
+			case response
+			when RubyDNS::Message
+				yield response
+			when RubyDNS::ResolutionFailure
+				fail!(:ServFail)
+			else
+				throw PassthroughError.new("Bad response from query: #{response.inspect}")
+			end
 		end
-
-		# Respond to the given query with a resource record. The arguments to this
-		# function depend on the <tt>resource_class</tt> requested. The last argument
-		# can optionally be a hash of options.
-		#
-		# <tt>options[:resource_class]</tt>:: Override the default <tt>resource_class</tt>
-		# <tt>options[:ttl]</tt>:: Specify the TTL for the resource
-		# <tt>options[:name]</tt>:: Override the name (question) of the response.
-		#
-		# for A records:: <tt>respond!("1.2.3.4")</tt>
-		# for MX records::  <tt>respond!(10, Name.create("mail.blah.com"))</tt>
+		
+		# Respond to the given query with a resource record. The arguments to this function depend on the `resource_class` requested. This function instantiates the resource class with the supplied arguments, and then passes it to {#append!}.
 		#
-		# This function instantiates the resource class with the supplied arguments, and
-		# then passes it to <tt>append!</tt>.
+		# e.g. For A records: `respond!("1.2.3.4")`, For MX records:  `respond!(10, Name.create("mail.blah.com"))`
+		
+		# The last argument can optionally be a hash of `options`. If `options[:resource_class]` is provided, it overrides the default resource class of transaction. Additional `options` are passed to {#append!}.
 		#
-		# See <tt>Resolv::DNS::Resource</tt> for more information about the various 
-		# <tt>resource_class</tt>s available. 
-		# http://www.ruby-doc.org/stdlib/libdoc/resolv/rdoc/index.html
-		def respond! (*data)
-			options = data.last.kind_of?(Hash) ? data.pop : {}
+		# See `Resolv::DNS::Resource` for more information about the various `resource_classes` available (http://www.ruby-doc.org/stdlib/libdoc/resolv/rdoc/index.html).
+		def respond!(*args)
+			append_question!
+			
+			options = args.last.kind_of?(Hash) ? args.pop : {}
 			resource_class = options[:resource_class] || @resource_class
 			
 			if resource_class == nil
-				raise ArgumentError, "Could not instantiate resource #{resource_class}!"
+				raise ArgumentError.new("Could not instantiate resource #{resource_class}!")
 			end
 			
 			@server.logger.info "Resource class: #{resource_class.inspect}"
-			resource = resource_class.new(*data)
+			resource = resource_class.new(*args)
 			@server.logger.info "Resource: #{resource.inspect}"
 			
-			append!(resource, options)
+			add([resource], options)
 		end
-
-		# Append a given set of resources to the answer. The last argument can 
-		# optionally be a hash of options.
-		# 
-		# <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
-		# <tt>Resolv::DNS::Resource</tt> module.
-		def append! (*resources)
-			append_question!
-
-			if resources.last.kind_of?(Hash)
-				options = resources.pop
-			else
-				options = {}
-			end
-
+		
+		# Append a list of resources.
+		#
+		# By default resources are appended to the `answers` section, but this can be changed by setting `options[:section]` to either `:authority` or `:additional`.
+		#
+		# The time-to-live (TTL) of the resources can be specified using `options[:ttl]` and defaults to `DEFAULT_TTL`.
+		def add(resources, options = {})
 			# 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
-
+			ttl = options[:ttl] || DEFAULT_TTL
+			name = options[:name] || @question.to_s + "."
+			
+			section = (options[:section] || 'answer').to_sym
+			method = "add_#{section}".to_sym
+			
 			resources.each do |resource|
 				@server.logger.debug "#{method}: #{resource.inspect} #{resource.class::TypeValue} #{resource.class::ClassValue}"
 				
-				@answer.send(method, options[:name], options[:ttl], resource)
+				@answer.send(method, name, ttl, resource)
 			end
-
-			succeed if @deferred
-
-			true
 		end
-
-		# This function indicates that there was a failure to resolve the given
-		# question. The single argument must be an integer error code, typically
-		# given by the constants in <tt>Resolv::DNS::RCode</tt>.
+		
+		# This function indicates that there was a failure to resolve the given question. The single argument must be an integer error code, typically given by the constants in {Resolv::DNS::RCode}.
 		#
-		# The easiest way to use this function it to simply supply a symbol. Here is
-		# a list of the most commonly used ones:
+		# The easiest way to use this function it to simply supply a symbol. Here is a list of the most commonly used ones:
 		#
-		# <tt>:NoError</tt>:: No error occurred.
-		# <tt>:FormErr</tt>::	The incoming data was not formatted correctly.
-		# <tt>:ServFail</tt>:: The operation caused a server failure (internal error, etc).
-		# <tt>:NXDomain</tt>:: Non-eXistant Domain (domain record does not exist).
-		# <tt>:NotImp</tt>:: The operation requested is not implemented.
-		# <tt>:Refused</tt>:: The operation was refused by the server.
-		# <tt>:NotAuth</tt>:: The server is not authoritive for the zone.
+		# - `:NoError`: No error occurred.
+		# - `:FormErr`: The incoming data was not formatted correctly.
+		# - `:ServFail`: The operation caused a server failure (internal error, etc).
+		# - `:NXDomain`: Non-eXistant Domain (domain record does not exist).
+		# - `:NotImp`: The operation requested is not implemented.
+		# - `:Refused`: The operation was refused by the server.
+		# - `:NotAuth`: The server is not authoritive for the zone.
 		#
-		# See http://www.rfc-editor.org/rfc/rfc2929.txt for more information
-		# about DNS error codes (specifically, page 3).
-		def failure! (rcode)
+		# See [RFC2929](http://www.rfc-editor.org/rfc/rfc2929.txt) for more information about DNS error codes (specifically, page 3).
+		#
+		# **This function will complete deferred transactions.**
+		def fail!(rcode)
 			append_question!
-
+			
 			if rcode.kind_of? Symbol
 				@answer.rcode = Resolv::DNS::RCode.const_get(rcode)
 			else
 				@answer.rcode = rcode.to_i
 			end
-
-			# The transaction itself has completed, but contains a failure:
-			succeed(rcode) if @deferred
-
-			true
 		end
-
+		
+		# @deprecated
+		def failure!(*args)
+			@server.logger.warn "failure! is deprecated, use fail! instead"
+			
+			fail!(*args)
+		end
+		
+		# A helper method to process the transaction on the given server. Unless the transaction is deferred, it will {#succeed} on completion.
+		def process
+			@server.process(name, @resource_class, self)
+		end
+		
+		protected
+		
+		# A typical response to a DNS request includes both the question and answer. This helper appends the question unless it looks like the user is already managing that aspect of the response.
 		def append_question!
 			if @answer.question.size == 0
 				@answer.add_question(@question, @resource_class) unless @question_appended