Source code

Directory structure

dnstraverse, being a Ruby Gem, follows the standard directory structure for gems.

General flow

There is one Traverser object that maintains the stack. It creates initial Referral objects to represent the root(s) and puts them on the stack. Although this doesn't happen for the initial root(s), for each Referral object on the stack it is first resolved if there aren't any IP addresses. This might involve a traversal for the resolution, in which case these are put on the stack and processed. Once a Referral object is resolved, it is processed. This means that for each IP address in a Referral a Response object is created. The Response object has an InfoCache that represents a normal resolver cache, and a DecodedQuery that does the actual query and then decodes and processes it. Based on the ResponseObject, more Referral objects might be created and put on the Traverser's stack. Once a Referral has been concluded, calculations are done to collect the statistics together. This keeps going recursively.

Source file descriptions

caching_resolver.rb - DNSTraverse::CachingResolver
This is a wrapper cache class around Dnsruby::Resolver that remembers identical queries for a particular resolver (identified by IP address) and returns them from cache if requested again.
decoded_query.rb - DNSTraverse::DecodedQuery
This object represents a decoded query for a particular name/type/class to a particular IP address in a particular bailiwick. It calls CachingResolver to do the actual work and then processes the reply, including:
  • Checking for exceptions and error conditions
  • Processing the authority section
  • Picking out the cacheable entries based on the bailiwick
  • Following CNAME referrals
  • Seeing if there is a final answer or NODATA condition
  • Detecting referral and re-start states
decoded_query_cache.rb - DNSTraverse::DecodedQueryCache
This object is a wrapper cache class that will remember identical DecodedQuery requests and return them from cache if requested again.
fingerprint.rb - DNSTraverse::Fingerprint
This is a Ruby implementation of Perl's Net::DNS::Fingerprint (fpdns)
This file is from Net::DNS::Fingerprint and is (c) Roy Arends & Jakob Schlyter
info_cache.rb - DNSTraverse::InfoCache
This is a representation of a resolver cache. Cacheable authority records are stored in here as a traversal happens. There is an InfoCache at every node in the traversal. Each node builds upon the InfoCache of it's parent. For memory conservation purposes they are chained.
log.rb - Log::Formatter
This is a logging class
message_utility.rb - DNSTraverse::MessageUtility
This is a utility class that contains module_functions to process Dnsruby::Message objects.
referral.rb - DNSTraverse::Referral
This is an object that represents a referral to a particular server with a given name/type/class. It is the main node in the dnstraverse structure. If you imagine that a DNS request has resulted in 3 referrals, this will generate 3 Referral objects. Each object may be initialised with IP address(es) (if relevant records supplied in query response or in the InfoCache) or without, meaning that some resolution is required. Once resolved a Referral object may represent multiple name servers (different IP addresses for the same referral) and there will be one Response object per server.
response.rb - DNSTraverse::Response
This brings together the InfoCache and the DecodedQuery to represent a specific response in the traversal. The query is evaluated using DecodedQuery and then a new InfoCache is created, updated with the results. If the DecodedQuery indicated a referral or restart the InfoCache can now be used to find the starting servers. Lame server detection can also be completed at this stage.
response_noglue.rb - DNSTraverse::Response::NoGlue
A special type of Response object representing the situation where there is no glue.
traverser.rb - DNSTraverse::Traverser
This is the main traverser, responsible for creating the initial DNSTraverse::Referral objects and then repeatedly resolving/processing them. When the resolve or process method of DNSTraverse::Referral returns more DNSTraverse::Referral objects, these are placed on the stack and processed accordingly. The answer/stats calculation methods are also called when each branch compeltes so that the probabilities are maintained.