Updated README with notes for migrating from 0.4.0 to 0.5.0

Author: ioquatix

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
 -------