nesser 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2647db1767dd49b7498c90b61a6db3e42ddd0baa
-  data.tar.gz: 1dca698d183e7e4415ec2cbc2dd75babbab39919
+  metadata.gz: 7c6c93d335d6983d60154b25ed5251f122a30534
+  data.tar.gz: 4d8dca606688b56847e0e82712e92b5467173659
 SHA512:
-  metadata.gz: 05a2335a136d62fa438592616af81e0a4d1aecf23b8a3c4cfb65e35d024d2af862e08bc62957f54f0db9de85795cdea42a06f46a133e4b2692c4c3f2207b85c1
-  data.tar.gz: cf8809e713363f6497bf0ecb7caafa9ab4643cbfbb658d926724519b9939c3d7dd6fbe552896f59fbb31b43338733d2f51b9db593fed6fca0a51bb50bce7359c
+  metadata.gz: c048c7eccf69dcd6091308ab2d95b485a3706a02749b5b20ef97f15c104dec50eb56ae20f52df64dd2d1f2bba2faf9cd0c5092f07922ffd2491b7431a88c5017
+  data.tar.gz: 0d18a1aee601408787d45d87bd3f0477ed89219cf5e7baa08db44115d27a333390647a27ec318311890a2922f4e448cb72f5c58db1267e70dec6ac7dab0e357c

data/LICENSE.md

@@ -0,0 +1,10 @@
+Copyright (c) 2013-2017, Ron Bowes
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+- Neither the name of the organization nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -20,9 +20,160 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Client
+
+After installing the gem, using it as a client is pretty straight forward.
+I wrote an example file in [lib/nesser/examples](lib/nesser/examples), but in
+a nutshell, here's the code:
+
+```ruby
+require 'socket'
+require 'nesser'
+
+# Create a UDP socket
+s = UDPSocket.new()
+
+# Perform a query for 'google.com', of type ANY. I chose this because it has a
+# wide array of varied answers.
+#
+# See packets/constants.rb for a full list of possible request types.
+result = Nesser::Nesser.query(s: s, hostname: 'google.com', type: Nesser::TYPE_ANY)
+
+# Print the result
+puts result
+```
+
+You can find all constant definitions in
+[the constants.rb file](lib/nesser/packets/constants.rb)
+
+The return from Nesser.query() is an instance of
+[Nesser::Answer](lib/nesser/packets/answer.rb).
+
+### Server
+
+Writing a server is a little more complicated, because you have to deal with
+much more of the nitty gritty DNS stuff.
+
+To start a server, create an instance of Nesser, and pass in a block that
+handles queries. From [examples/server.rb](lib/nesser/examples/server.rb):
+
+```ruby
+nesser = Nesser::Nesser.new(s: s) do |transaction|
+  puts transaction
+
+  # ...
+end
+nesser.wait()
+```
+
+This is called once per packet received - since many servers send the same
+request several times, that has to be handled by the application. Since the
+function starts a thread and returns instantly, `nesser.wait()` is necessary
+so the program doesn't end until the thread does.
+
+The transaction is an instance of [Nesser::Transaction](lib/nesser/transaction.rb).
+Any methods of transaction that end with an exclamation mark
+(`transaction.answer!()`, for example) will send a response and can only be
+called once, after which the transaction is done and shouldn't be used anymore.
+
+The request packet can be accessed via `transaction.request`, and the response
+can be directly accessed (or changed, though I don't recommend that) via
+`transaction.response` and `transaction.response=()`. Both are instances of
+[Nesser::Packet](lib/nesser/packets/packet.rb). The response already has the
+appropriate `trn_id` and `flags` and the `question`, so all you have to do is
+add answers and send it off using `transaction.reply!()`.
+
+A much easier way to reply to a request is to use one of the two helper
+functions, `transaction.answer!()` or `transaction.error!()`. Each of these
+will take the `transaction.response` packet, with whatever changes have been
+made to it, add to it, and send it off.
+
+`transaction.answer!()` takes an optional array of
+[Nesser::Answer](lib/nesser/packets/answer.rb), adds them to the packet, then sends
+it.
+
+`transaction.error!()` takes a response code (see
+[constants.rb](lib/nesser/packets/constants.rb) for the list), updates the
+packet with that code, then sends it.
+
+You'll rarely need to do anything with the transaction other than inspecting the
+request and using one of those two functions to answer.
+
+Here's a full example that replies to requests for test.com with '1.2.3.4' and
+sends a "name not found" error for anything else:
+
+```ruby
+require 'socket'
+require 'nesser'
+
+# Create a UDP socket
+s = UDPSocket.new()
+
+# Create a new instance of Nesser to handle transactions
+nesser = Nesser::Nesser.new(s: s) do |transaction|
+  # We only have an answer for 'test.com' (this is, after all, an example)
+  if transaction.request.questions[0].name == 'test.com'
+    # Create an A-type resource record pointing to 1.2.3.4. See README.md for
+    # details on how to create other record types
+    rr = Nesser::A.new(address: '1.2.3.4')
+
+    # Create an answer. The name will almost always be the same as the original
+    # name, but the type and cls don't necessarily have to match the request
+    # type (in this case, we don't even check what the request type was).
+    #
+    # You'll probably want the rr's type to match the type: argument. I'm not
+    # sure if it'll work otherwise, but the client it's sent to sure as heck
+    # won't know what to do with it. :)
+    answer = Nesser::Answer.new(
+      name: 'test.com',
+      type: Nesser::TYPE_A, # See constants.rb for other options
+      cls: Nesser::CLS_IN,
+      ttl: 1337,
+      rr: rr,
+    )
+
+    # The transaction's functions that end with '!' actually send the message -
+    # in this case, answer!() sends an array of the one answre that we created.
+    transaction.answer!([answer])
+  else
+    # Response NXDomain - aka, no such domain name - to everything other than
+    # 'test.com'.
+    transaction.error!(Nesser::RCODE_NAME_ERROR)
+  end
+
+  # Display the transaction
+  puts(transaction)
+end
+
+# Since Nesser::Nesser.new() runs in a new thread, we have to basically join
+# the thread to prevent the program from ending
+nesser.wait()
+```
+
+We currently support A, NS, CNAME, SOA, MX, TXT, and AAAA records. We can also
+parse and send unknown types as well. You can find the definitions in
+[rr_types.rb](lib/nesser/packets/rr_types.rb).
+
+For quick reference:
+
+* `a = Nesser::A.new(address: '1.2.3.4')`
+* `ns = Nesser::NS.new(name: 'google.com')`
+* `cname = Nesser::CNAME.new(name: 'google.com')`
+* `soa = Nesser::SOA.new(primary: 'google.com', responsible: 'test.google.com', serial: 1, refresh: 2, retry_interval: 3, expire: 4, ttl: 5)`
+* `mx = Nesser::MX.new(name: 'mail.google.com', preference: 10)`
+* `txt = Nesser::TXT.new(data: 'hello this is data!')`
+* `aaaa = Nesser::AAAA.new(address: '::1')`
+* `unknown = Nesser::RRUnknown.new(type: 0x1337, data: 'datagoeshere')`
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/iagox86/nesser
 
+Please try to follow my style as much as possible, and update test coverage
+when necessary!
+
+## Version history / changelog
+
+* 0.0.1 - Test deploy
+* 0.0.2 - Code complete
+* 0.0.3 - First actual release

data/lib/nesser.rb

@@ -16,9 +16,9 @@
 # There are two methods for using this library: as a client (to make a query)
 # or as a server (to listen for queries and respond to them).
 #
-# To make a query, use Nesser.query:
-#
-# ...TODO...
+# To avoid putting too much narrative in this header, I wrote full usage
+# details in README.md in the root directory. Check that out for full usage
+# details!
 ##
 
 require 'ipaddr'
@@ -35,6 +35,35 @@ module Nesser
   class Nesser
     attr_reader :thread
 
+    ##
+    # Create a new instance and start listening for requests in a new thread.
+    # Returns instantly (use the `wait()` method to pause until the thread is
+    # over (pretty much indefinitely).
+    #
+    # The `s` parameter should be an instance of `UDPSocket` in `socket`. The
+    # logger will default to an instance of `Nesser::Logger` if it's not
+    # specified, which simply logs to stdout.
+    #
+    # The other parameters are reasonably self explanatory.
+    #
+    # When you create an instance, you must also specify a proc:
+    #
+    # ```ruby
+    # Nesser::Nesser.new(s: s) do |transaction|
+    #   # ...
+    # end
+    # ```
+    #
+    # Whenever a valid DNS message comes in, a new `Nesser::Transaction` is
+    # created and the proc is called with it (an invalid packet will be printed
+    # to the logger and discarded). It's up to the user to answer it using
+    # `transaction.answer!()`, `transaction.error!()`, etc. (see README.md for
+    # examples).
+    #
+    # If the handler function throws an Exception (most non-system errors),
+    # a SERVFAIL message will be returned automatically and the error will be
+    # logged to the logger.
+    ##
     def initialize(s:, logger: nil, host:"0.0.0.0", port:53)
       @s = s
       @s.bind(host, port)
@@ -42,48 +71,47 @@ module Nesser
       @logger = (logger = logger || Logger.new())
 
       @thread = Thread.new() do
-        begin
-          loop do
-            # Grab all the data we can off the socket
-            data = @s.recvfrom(65536)
-
-            begin
-              # Data is an array where the first element is the actual data, and the second is the host/port
-              request = Packet.parse(data[0])
-            rescue DnsException => e
-              logger.error("Failed to parse the DNS packet: %s" % e.to_s())
-              next
-            rescue Exception => e
-              logger.error("Error: %s" % e.to_s())
-              logger.info(e.backtrace().join("\n"))
-            end
+        loop do
+          # Grab all the data we can off the socket
+          data = @s.recvfrom(65536)
+
+          begin
+            # Data is an array where the first element is the actual data, and the second is the host/port
+            request = Packet.parse(data[0])
+          rescue DnsException => e
+            logger.error("Failed to parse the DNS packet: %s" % e.to_s())
+            next
+          rescue Exception => e
+            logger.error("Error: %s" % e.to_s())
+            logger.info(e.backtrace().join("\n"))
+          end
 
-            # Create a transaction object, which we can use to respond
-            transaction = Transaction.new(
-              s: @s,
-              request_packet: request,
-              host: data[1][3],
-              port: data[1][1],
-            )
-
-            begin
-              proc.call(transaction)
-            rescue StandardError => e
-              logger.error("Error thrown while processing the DNS packet: %s" % e.to_s())
-              logger.info(e.backtrace().join("\n"))
-
-              if transaction.open?()
-                transaction.error!(RCODE_SERVER_FAILURE)
-              end
+          # Create a transaction object, which we can use to respond
+          transaction = Transaction.new(
+            s: @s,
+            request: request,
+            host: data[1][3],
+            port: data[1][1],
+          )
+
+          begin
+            proc.call(transaction)
+          rescue Exception => e
+            logger.error("Error thrown while processing the DNS packet: %s" % e.to_s())
+            logger.info(e.backtrace().join("\n"))
+
+            if transaction.open?()
+              transaction.error!(RCODE_SERVER_FAILURE)
             end
           end
-        ensure
-          @s.close()
         end
       end
     end
 
-    # Kill the listener
+    ##
+    # Kill the listener thread (once this is called, the class instance is
+    # worthless).
+    ##
     def stop()
       if(@thread.nil?)
         @logger.error("Tried to stop a listener that wasn't listening!")
@@ -94,8 +122,10 @@ module Nesser
       @thread = nil
     end
 
-    # After calling on_request(), this can be called to halt the program's
-    # execution until the thread is stopped.
+    ##
+    # Pauses as long as the listener thread is alive (generally, that means
+    # indefinitely).
+    ##
     def wait()
       if(@thread.nil?)
         @logger.error("Tried to wait on a Nesser instance that wasn't listening!")
@@ -105,7 +135,18 @@ module Nesser
       @thread.join()
     end
 
-    # Send out a query
+    ##
+    # Send a query.
+    #
+    # * `s`: an instance of `UDPSocket` from 'socket'.
+    # * `hostname`: the name being queried - eg, 'example.org'.
+    # * `server` and `port`: The upstream DNS server to query.
+    # * `type` and `cls`: typical DNS values, you can find a list of them in
+    #    packets/constants.rb.
+    # * `timeout`: The number of seconds to wait for a response before giving up.
+    #
+    # Returns a Nesser::Packet (nesser/packets/packet.rb).
+    ##
     def self.query(s:, hostname:, server: '8.8.8.8', port: 53, type: TYPE_A, cls: CLS_IN, timeout: 3)
       s = UDPSocket.new()
 

data/lib/nesser/examples/client.rb

@@ -11,8 +11,16 @@
 $LOAD_PATH.unshift File.expand_path('../../../', __FILE__)
 
 require 'socket'
-
 require 'nesser'
 
+# Create a UDP socket
 s = UDPSocket.new()
-puts Nesser::Nesser.query(s: s, hostname: 'google.com', type: Nesser::TYPE_ANY)
+
+# Perform a query for 'google.com', of type ANY. I chose this because it has a
+# wide array of varied answers.
+#
+# See packets/constants.rb for a full list of possible request types.
+result = Nesser::Nesser.query(s: s, hostname: 'google.com', type: Nesser::TYPE_ANY)
+
+# Print the result
+puts result

data/lib/nesser/examples/server.rb

@@ -13,21 +13,45 @@ $LOAD_PATH.unshift File.expand_path('../../../', __FILE__)
 require 'socket'
 require 'nesser'
 
+# Create a UDP socket
 s = UDPSocket.new()
 
+# Create a new instance of Nesser to handle transactions
 nesser = Nesser::Nesser.new(s: s) do |transaction|
-  if transaction.request_packet.questions[0].name == 'test.com'
-    transaction.answer!([Nesser::Answer.new(
+  # We only have an answer for 'test.com' (this is, after all, an example)
+  if transaction.request.questions[0].name == 'test.com'
+    # Create an A-type resource record pointing to 1.2.3.4. See README.md for
+    # details on how to create other record types
+    rr = Nesser::A.new(address: '1.2.3.4')
+
+    # Create an answer. The name will almost always be the same as the original
+    # name, but the type and cls don't necessarily have to match the request
+    # type (in this case, we don't even check what the request type was).
+    #
+    # You'll probably want the rr's type to match the type: argument. I'm not
+    # sure if it'll work otherwise, but the client it's sent to sure as heck
+    # won't know what to do with it. :)
+    answer = Nesser::Answer.new(
       name: 'test.com',
-      type: Nesser::TYPE_A,
+      type: Nesser::TYPE_A, # See constants.rb for other options
       cls: Nesser::CLS_IN,
       ttl: 1337,
-      rr: Nesser::A.new(address: '1.2.3.4')
-    )])
+      rr: rr,
+    )
+
+    # The transaction's functions that end with '!' actually send the message -
+    # in this case, answer!() sends an array of the one answre that we created.
+    transaction.answer!([answer])
   else
+    # Response NXDomain - aka, no such domain name - to everything other than
+    # 'test.com'.
     transaction.error!(Nesser::RCODE_NAME_ERROR)
   end
+
+  # Display the transaction
   puts(transaction)
 end
 
+# Since Nesser::Nesser.new() runs in a new thread, we have to basically join
+# the thread to prevent the program from ending
 nesser.wait()

data/lib/nesser/logger.rb

@@ -1,12 +1,12 @@
 # Encoding: ASCII-8BIT
 ##
-# dns_exception.rb
+# logger.rb.rb
 # Created June 20, 2017
 # By Ron Bowes
 #
 # See LICENSE.md
 #
-# Implements a simple exception class for dns errors.
+# A super simple logger implementation.
 ##
 
 module Nesser

data/lib/nesser/packets/answer.rb

@@ -6,15 +6,26 @@
 #
 # See: LICENSE.md
 #
-# A DNS answer. A DNS response packet contains zero or more Answer records
-# (defined by the 'ancount' value in the header). An answer contains the
-# name of the domain from the question, followed by a resource record.
+# A DNS answer. A DNS packet contains zero or more Answer records (defined in
+# the 'ancount' value in the header). An answer contains the name of the domain
+# followed by a resource record.
 ##
 
 module Nesser
   class Answer
     attr_reader :name, :type, :cls, :ttl, :rr
 
+    ##
+    # Create an answer.
+    #
+    # * `name`: Should match the name from the question.
+    # * `type`: The type of resource record (eg, TYPE_A, TYPE_NS, etc). You can
+    #   find a list of types in constants.rb.
+    # * `cls`: The DNS class - this will almost certainly be `Nesser::CLS_IN`,
+    #   since 'IN' means 'Internet'. I'm not familiar with any others.
+    # * `ttl`: The time-to-live for the response, in seconds
+    # * `rr`: A resource record - you can find these classes in rr_types.rb.
+    ##
     def initialize(name:, type:, cls:, ttl:, rr:)
       @name = name
       @type = type
@@ -23,6 +34,11 @@ module Nesser
       @rr   = rr
     end
 
+    ##
+    # Parse an answer from a DNS packet. You won't likely need to use this, but
+    # if you do, it's necessary to use a Nesser::Unpacker that's loaded with the
+    # full DNS message (due to in-packet pointers).
+    ##
     def self.unpack(unpacker)
       name = unpacker.unpack_name()
       type, cls, ttl = unpacker.unpack("nnN")
@@ -55,6 +71,10 @@ module Nesser
       )
     end
 
+    ##
+    # Pack this into a Nesser::Packer in preparation for being sent over the
+    # wire.
+    ##
     def pack(packer)
       # The name is echoed back
       packer.pack_name(@name)

data/lib/nesser/packets/constants.rb

@@ -5,6 +5,9 @@
 # By Ron Bowes
 #
 # See: LICENSE.md
+#
+# A bunch of constants used with DNS - some of them for the protocol, others for
+# error checking the outgoing messages.
 ##
 
 module Nesser
@@ -21,6 +24,8 @@ module Nesser
   MAX_SEGMENT_LENGTH = 63
   MAX_TOTAL_LENGTH = 253
 
+  # DNS classes - I only define IN (Internet) because I don't even know what to
+  # do with others.
   CLS_IN                = 0x0001 # Internet
   CLSES = {
     CLS_IN => "IN",
@@ -42,7 +47,6 @@ module Nesser
   RCODE_NAME_ERROR      = 0x0003 # :NXDomain
   RCODE_NOT_IMPLEMENTED = 0x0004
   RCODE_REFUSED         = 0x0005
-
   RCODES = {
     RCODE_SUCCESS         => ":NoError (RCODE_SUCCESS)",
     RCODE_FORMAT_ERROR    => ":FormErr (RCODE_FORMAT_ERROR)",
@@ -56,7 +60,6 @@ module Nesser
   OPCODE_QUERY  = 0x0000
   OPCODE_IQUERY = 0x0800
   OPCODE_STATUS = 0x1000
-
   OPCODES = {
     OPCODE_QUERY  => "OPCODE_QUERY",
     OPCODE_IQUERY => "OPCODE_IQUERY",
@@ -72,7 +75,6 @@ module Nesser
   TYPE_TXT   = 0x0010
   TYPE_AAAA  = 0x001c
   TYPE_ANY   = 0x00FF
-
   TYPES = {
     TYPE_A     => "A",
     TYPE_NS    => "NS",

data/lib/nesser/packets/packer.rb

@@ -24,11 +24,18 @@ module Nesser
       @segment_cache = {}
     end
 
+    ##
+    # This is simply a wrapper around String.pack() - it's for packing perfectly
+    # ordinary data into a DNS packet.
+    ##
     public
     def pack(format, *data)
       @data += data.pack(format)
     end
 
+    ##
+    # Sanity check a name (length, legal characters, etc).
+    ##
     private
     def validate!(name)
       if name.chars.detect { |ch| !LEGAL_CHARACTERS.include?(ch) }
@@ -44,9 +51,37 @@ module Nesser
       end
     end
 
-    # Take a name, as a dotted string ("google.com") and return it as length-
-    # prefixed segments ("\x06google\x03com\x00"). It also does a pointer
-    # (\xc0\xXX) when possible!
+    ##
+    # This function is sort of the point of this class's existance.
+    #
+    # You pass in a typical DNS name, such as "google.com". If that name
+    # doesn't appear in the packet yet, it's simply encoded with length-
+    # prefixed segments - "\x06google\x03com\x00".
+    #
+    # However, if all or part of the name already exist in the packet, this will
+    # save packet space by re-using those segments. For example, let's say that
+    # "google.com" exists 0x0c bytes into the packet (which it normally does).
+    # In that case, instead of including "\x06google\x03com\x00" a second time,
+    # it will simply encode the offset with "\xc0" in front - "\xc0\x0c".
+    #
+    # Let's say that later in the packet, we have "www.google.com". That string
+    # as a whole hasn't appeared yet, but "google.com" appeared at offset 0x0c.
+    # It will then be encoded "\x03www\xc0\x0c" - the longest possible segment
+    # is encoded.
+    #
+    # This logic is somewhat complicated, but this function seems to work
+    # pretty well. :)
+    #
+    # * `name`: The name to encode, as a normal dotted string.
+    # * `dry_run`: If set to true, don't actually "write" the name. This is
+    #   unfortunately needed to check the size of something that *would* be
+    #   encoded, since we occasionally need the length written to the buffer
+    #   before the name.
+    # * `compress`: If set (which it always probably should be), will attempt
+    #   to do the compression ("\xc0") stuff discussed earlier.
+    #
+    # Returns the actual length of the name.
+    ##
     public
     def pack_name(name, dry_run:false, compress:true)
       length = 0
@@ -89,6 +124,9 @@ module Nesser
       return length
     end
 
+    ##
+    # Retrieve the buffer as a string.
+    ##
     public
     def get()
       return @data

data/lib/nesser/packets/packet.rb

@@ -5,6 +5,9 @@
 # By Ron Bowes
 #
 # See: LICENSE.md
+#
+# An implementation of a DNS packet, including encoding and parsing. This covers
+# the header and questions/answers.
 ##
 
 require 'nesser/dns_exception'
@@ -19,6 +22,25 @@ module Nesser
   class Packet
     attr_accessor :trn_id, :qr, :opcode, :flags, :rcode, :questions, :answers
 
+    ##
+    # Create a new packet.
+    #
+    # * `trn_id`: The 16-bit transaction id - should be random for clients, and
+    #   match the incoming trn_id for servers.
+    # * `qr`: QR_QUERY or QR_RESPONSE.
+    # * `opcode`: will likely be OPCODE_QUERY.
+    # * `flags`: A combination of the flags FLAG_AA, FLAG_TC, FLAG_RD, and
+    #   FLAG_RA.
+    # * `rcode`: A response code - RCODE_SUCCESS for requests or good responses,
+    #   or an error code (RCODE_NAME_ERROR, RCODE_SERVER_FAILURE, etc) for
+    #   errors. Find the list in constants.rb.
+    # * `questions`: An array (although most implementations only handle exactly
+    #   one) of questions - Nesser::Question.
+    # * `answers`: An array of zero or more ansewrs - Nesser::Answer.
+    #
+    # We don't support authority or additional records right now (or perhaps
+    # ever).
+    ##
     def initialize(trn_id:, qr:, opcode:, flags:, rcode:, questions:[], answers:[])
       @trn_id    = trn_id
       @qr        = qr
@@ -33,6 +55,9 @@ module Nesser
       @answers   = answers
     end
 
+    ##
+    # Add a Nesser::Question.
+    ##
     def add_question(question)
       if !question.is_a?(Question)
         raise(DnsException, "Questions must be of type Question!")
@@ -41,6 +66,9 @@ module Nesser
       @questions << question
     end
 
+    ##
+    # Add a Nesser::Answer.
+    ##
     def add_answer(answer)
       if !answer.is_a?(Answer)
         raise(DnsException, "Questions must be of type Question!")
@@ -49,6 +77,12 @@ module Nesser
       @answers << answer
     end
 
+    ##
+    # Parse an incoming DNS packet. Takes a byte string as an argument, and
+    # returns an instance of Nesser::Packet - this class.
+    #
+    # Raises a DnsException if things go badly.
+    ##
     def self.parse(data)
       unpacker = Unpacker.new(data)
       trn_id, full_flags, qdcount, ancount, _, _ = unpacker.unpack("nnnnnn")
@@ -81,6 +115,11 @@ module Nesser
       return packet
     end
 
+    ##
+    # Convert a query packet to the corresponding answer - the trn_id is copied,
+    # the qr is changed to QR_RESPONSE, the opcode and flags are updated, and
+    # the question from the query is added.
+    ##
     def answer(answers:[], question:nil)
       question = question || @questions[0]
 
@@ -95,6 +134,10 @@ module Nesser
       )
     end
 
+    ##
+    # Convert a query packet to the corresponding error answer with the given
+    # rcode (see constants.rb for a list of rcodes).
+    ##
     def error(rcode:, question:nil)
       question = question || @questions[0]
 
@@ -109,6 +152,9 @@ module Nesser
       )
     end
 
+    ##
+    # Serialize the packet to an array of bytes.
+    ##
     def to_bytes()
       packer = Packer.new()
 

data/lib/nesser/packets/question.rb

@@ -6,20 +6,29 @@
 #
 # See: LICENSE.md
 #
-# This defines a DNS question. One question is sent in outgoing packets,
-# and one question is also sent in the response - generally, the same as
-# the question that was asked.
+# This defines a DNS question. Typically, a single question is sent in both
+# incoming and outgoing packets. Most implementations can't handle any other
+# situation.
 ##
 module Nesser
   class Question
     attr_reader :name, :type, :cls
 
+    ##
+    # Create a question.
+    #
+    # The name is a typical dotted name, like "google.com". The type and cls
+    # are DNS-specific values that can be found in constants.rb.
+    ##
     def initialize(name:, type:, cls:)
       @name  = name
       @type  = type
       @cls  = cls
     end
 
+    ##
+    # Parse a question from a DNS packet.
+    ##
     def self.unpack(unpacker)
       name = unpacker.unpack_name()
       type, cls = unpacker.unpack("nn")
@@ -27,6 +36,9 @@ module Nesser
       return self.new(name: name, type: type, cls: cls)
     end
 
+    ##
+    # Serialize the question.
+    ##
     def pack(packer)
       packer.pack_name(@name)
       packer.pack('nn', type, cls)

data/lib/nesser/packets/rr_types.rb

@@ -5,6 +5,16 @@
 # By Ron Bowes
 #
 # See: LICENSE.md
+#
+# These are implementations of resource records - ie, the records found in a DNS
+# answer that contain, for example, an ip address, a mail exchange, etc.
+#
+# Every one of these classes follows the same paradigm (I guess in Java you'd
+# say they implement the same interface). They can be initialized with
+# type-dependent parameters; they implement `self.unpack()`, which takes a
+# `Nesser::Unpacker` and returns an instance of itself; they implement `pack()`,
+# which serialized itself into a `Nesser::Packer` instance; and they have a
+# `to_s()` function, which stringifies the record in a fairly user-friendly way.
 ##
 
 require 'ipaddr'
@@ -15,6 +25,9 @@ require 'nesser/packets/packer'
 require 'nesser/packets/unpacker'
 
 module Nesser
+  ##
+  # An A record is a typical IPv4 address - eg, '1.2.3.4'.
+  ##
   class A
     attr_accessor :address
 
@@ -54,6 +67,9 @@ module Nesser
     end
   end
 
+  ##
+  # Nameserver record: eg, 'ns1.google.com'.
+  ##
   class NS
     attr_accessor :name
 
@@ -80,6 +96,9 @@ module Nesser
     end
   end
 
+  ##
+  # Alias record: eg, 'www.google.com'->'google.com'.
+  ##
   class CNAME
     attr_accessor :name
 
@@ -105,6 +124,9 @@ module Nesser
     end
   end
 
+  ##
+  # Statement of authority record.
+  ##
   class SOA
     attr_accessor :primary, :responsible, :serial, :refresh, :retry_interval, :expire, :ttl
 
@@ -155,6 +177,9 @@ module Nesser
     end
   end
 
+  ##
+  # Mail exchange record - eg, 'mail.google.com' 10.
+  ##
   class MX
     attr_accessor :preference, :name
 
@@ -188,6 +213,10 @@ module Nesser
     end
   end
 
+  ##
+  # A TXT record, with is simply binary data (except on some libraries where it
+  # can't contain a NUL byte).
+  ##
   class TXT
     attr_accessor :data
 
@@ -223,6 +252,9 @@ module Nesser
     end
   end
 
+  ##
+  # IPv6 record, eg, "::1".
+  ##
   class AAAA
     attr_accessor :address
 
@@ -264,6 +296,9 @@ module Nesser
     end
   end
 
+  ##
+  # An unknown record type.
+  ##
   class RRUnknown
     attr_reader :type, :data
     def initialize(type:, data:)

data/lib/nesser/packets/unpacker.rb

@@ -22,12 +22,21 @@ module Nesser
   class Unpacker
     attr_accessor :data, :offset
 
+    ##
+    # Create a new unpacker with a string (the string must be the full DNS
+    # request, starting at the `trn_id` - otherwise, unpacking compressed
+    # fields won't work properly!
+    ##
     public
     def initialize(data)
       @data = data
       @offset = 0
     end
 
+    ##
+    # Does some basic error checking to make sure we didn't run off the end of
+    # packet - doesn't catch every case, though.
+    ##
     private
     def _verify_results(results)
       # If there's at least one nil included in our results, bad stuff happened
@@ -36,8 +45,11 @@ module Nesser
       end
     end
 
-    # Unpack from the string, exactly like the normal `String#Unpack` method
-    # in Ruby, except that an offset into the string is maintained and updated.
+    ##
+    # Unpack from the string, exactly like the normal `String.unpack()` method
+    # in Ruby, except that a pointer offset into the string is maintained and
+    # updated (which is required for unpacking names).
+    ##
     public
     def unpack(format)
       if @offset >= @data.length
@@ -53,6 +65,13 @@ module Nesser
       return *results
     end
 
+    ##
+    # Unpack a single element from the buffer and return it (this is a simple
+    # little utility function that I wrote to save myself time).
+    #
+    # The `format` argument works exactly like in `String.unpack()`, but only
+    # one element can be given.
+    ##
     public
     def unpack_one(format)
       results = unpack(format)
@@ -65,9 +84,10 @@ module Nesser
       return results.pop()
     end
 
-    # This temporarily changes the offset that we're reading from, runs the
-    # given block, then changes it back. This is used internally while
-    # unpacking names.
+    ##
+    # Temporarily changes the offset that we're reading from, runs the given
+    # block, then changes it back. This is used internally while unpacking names.
+    ##
     private
     def _with_offset(offset)
       old_offset = @offset
@@ -76,11 +96,26 @@ module Nesser
       @offset = old_offset
     end
 
-    # Unpack a name from the packet. Names are special, because they're
-    # encoded as:
-    # * A series of length-prefixed blocks, each indicating a segment
-    # * Blocks with a length the starts with two '1' bits (11xxxxx...), which
-    #   contains a pointer to another name elsewhere in the packet
+    ##
+    # Unpack a name from the packet and convert it into a standard dotted name
+    # that we all understand.
+    #
+    # At the simplest, names are encoded as length-prefixed blocks. For example,
+    # "google.com" is encoded as "\x06google\x03com\x00".
+    #
+    # More complex, however, is that all or part of a name can be replaced with
+    # "\xc0" followed by an offset into the packet where the remainder of the
+    # name (or the full name) can be found. For example, if
+    # "\x06google\x03com\x00" is found at index 0x0c (which it frequently is),
+    # then "www.google.com" can be encoded as "\x03www\xc0\x0c". In other words,
+    # "www" followed by the rest of the name at offset 0x0c".
+    #
+    # The point of this class is that that situation is handled as cleanly as
+    # possible.
+    #
+    # The `depth` argument is used internally for recursion, the default value
+    # of 0 should be used externally.
+    ##
     public
     def unpack_name(depth:0)
       segments = []

data/lib/nesser/transaction.rb

@@ -6,27 +6,40 @@
 #
 # See: LICENSE.md
 #
-# When a request comes in, a transaction is created and sent to the callback.
-# The transaction can be used to respond to the request at any point in the
-# future.
+# When a request comes in, a transaction is created to represent it. The
+# transaction can be used to respond to the request at any point in the
+# future - the trn_id and socket and stuff are all set up. Though, keep in
+# mind, most clients will only wait like 3 seconds, so responding at *any*
+# point, while technically true, isn't really a useful distinction.
 #
-# Any methods with a bang ('!') in front will send the response back to the
+# Any methods with a bang ('!') in their name will send the response back to the
 # requester. Only one bang method can be called, any subsequent calls will
 # throw an exception.
+#
+# You'll almost always want to use either `transaction.answer!()` or
+# `transaction.error!()`. While it's possible to change and/or add to
+# `transaction.response` and send it with `transaction.reply!()`, that's more
+# complex and generally not needed.
 ##
+
 module Nesser
   class Transaction
-    attr_reader :request_packet, :response_packet, :sent
+    attr_reader :request, :sent
+    attr_accessor :response
 
+    ##
+    # Create a new instance of Transaction. This is used internally - it's
+    # unlikely you'll ever need to create an instance.
+    ##
     public
-    def initialize(s:, request_packet:, host:, port:)
+    def initialize(s:, request:, host:, port:)
       @s = s
-      @request_packet = request_packet
+      @request = request
       @host = host
       @port = port
       @sent = false
 
-      @response_packet = request_packet.answer()
+      @response = request.answer()
     end
 
     private
@@ -36,25 +49,41 @@ module Nesser
       end
     end
 
+    ##
+    # Check whether or not the transaction has been sent already.
+    ##
     public
     def open?()
       return !@sent
     end
 
+    ##
+    # Reply with zero or more answers, specified in the array.
+    #
+    # Only one "bang function" can be called per transaction, subsequent calls
+    # will throw an exception.
+    ##
     public
     def answer!(answers=[])
       answers.each do |answer|
-        @response_packet.add_answer(answer)
+        @response.add_answer(answer)
       end
 
       reply!()
     end
 
+    ##
+    # Reply with an error defined by rcode (you can find a full list in
+    # packets/constants.rb).
+    #
+    # Only one "bang function" can be called per transaction, subsequent calls
+    # will throw an exception.
+    ##
     public
     def error!(rcode)
       not_sent!()
 
-      @response_packet.rcode = rcode
+      @response.rcode = rcode
       reply!()
     end
 
@@ -88,11 +117,19 @@ module Nesser
 #      @sent = true
 #    end
 
-    private
+    ##
+    # Reply with the response packet, in whatever state it's in. While this is
+    # public and gives you find control over the packet being sent back,
+    # realistically answer!() and error!() are probably all you'll need. Only
+    # use this is those won't work for whatever reason.
+    #
+    # Only one "bang function" can be called per transaction, subsequent calls
+    # will throw an exception.
+    public
     def reply!()
       not_sent!()
 
-      @s.send(@response_packet.to_bytes(), 0, @host, @port)
+      @s.send(@response.to_bytes(), 0, @host, @port)
       @sent = true
     end
 
@@ -102,13 +139,14 @@ module Nesser
 
       result << '== Nesser (DNS) Transaction =='
       result << '-- Request --'
-      result << @request_packet.to_s()
+      result << @request.to_s()
       if !sent()
         result << '-- Response [not sent yet] --'
       else
         result << '-- Response [sent] --'
       end
-      result << @response_packet.to_s()
+      result << @response.to_s()
+      result << ''
 
       return result.join("\n")
     end

data/lib/nesser/version.rb

@@ -1,3 +1,3 @@
 module Nesser
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nesser
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - iagox86
@@ -76,6 +76,7 @@ files:
 - ".gitignore"
 - ".travis.yml"
 - Gemfile
+- LICENSE.md
 - README.md
 - Rakefile
 - bin/console