powerdns_pipe 1.0

data/README.rdoc

@@ -0,0 +1,149 @@
+= Ruby PowerDNS Pipe Backend Abstraction
+
+powerdns_pipe is a Ruby library for developing
+{PowerDNS}[http://www.powerdns.com] pipe backend resolvers.
+
+More information on the PowerDNS pipe backend {can be found
+here}[http://doc.powerdns.com/backends-detail.html].
+
+== Installation
+
+  sudo gem install powerdns_pipe
+
+== Documentation
+
+PowerDNS::Pipe works by handling all the communication with PowerDNS
+for you.  It handles the <tt>HELO</tt> and <tt>PING</tt> and stuff,
+but calls a block when a query or axfr request is made.  The block has
+access to a <tt>question</tt> object which has information about the
+query from PowerDNS, and the <tt>answer</tt> method, which provides
+responses to PowerDNS.
+
+<tt>PowerDNS::Pipe.new</tt> takes a hash of options, all are optional
+and the defaults are usually all you need:
+
+[:input] The IO object to read requests from PowerDNS. Defaults to
+         STDIN
+
+[:output] The IO object to write responses to PowerDNS. Defaults to
+          STDOUT
+
+[:err] The IO object to write debugging information. Defaults to
+       STDERR, but is rarely used.
+
+[:version_range] A Range instance representing the Pipe protocol
+                 versions this backend supports.  Defaults to 1..2
+
+[:banner] A string used in response to HELO requests from PowerDNS, is
+          logged to the PowerDNS logs. Defaults to "Ruby PowerDNS::Pipe"
+
+=== question object
+
+The <tt>question</tt> object provides information about the query from
+the server:
+
+[<tt>name</tt>] The record being requested, e.g: <tt>www.example.com</tt>
+
+[<tt>qtype</tt>] The request type, such as <tt>A</tt> or
+                 <tt>MX</tt>. PowerDNS often uses <tt>ANY</tt>, to
+                 which you should return all valid records for the
+                 name and PowerDNS worries about returning the right
+                 one to the client. You <em>must</em> support this
+                 type.
+
+[<tt>qclass</tt>] The request class, this is always <tt>IN</tt>.
+
+[<tt>remote_ip_address</tt>] The IP address of the host making the
+                             dns request.  You could use this to
+                             return different records for different
+                             geographic regions.
+
+[<tt>local_ip_address</tt>] The server IP address the request came
+                            into. Useful if your PowerDNS server is
+                            listening on multiple IPs and you want to
+                            consider that in your answers.
+
+[<tt>id</tt>] The id of the last answer to this question provided to
+              PowerDNS by this backend for this.  This might be
+              useful to you to speed up subsequent lookups. -1 by
+              default and can be ignored.
+
+[<tt>query?</tt>] Returns true if this is a normal Q query.
+
+[<tt>axfr?</tt>] Returns true if this is an axfr query.
+
+=== answer method
+
+The <tt>answer</tt> method is used to return records to PowerDNS.  It
+can be called multiple times to return multiple records.  Any
+exceptions are caught for you so garbage is not returned to PowerDNS.
+If you have nothing to return, just don't call answer at all.
+
+It takes the following options:
+
+[<tt>:name</tt>] The record name, e.g: <tt>www.example.com</tt>. Can
+                 usually just be set to <tt>question.name</tt>
+
+[<tt>:ttl</tt>] Time to Live in seconds. Defaults to 3600
+
+[<tt>:content</tt>] The content of the response, so an IP address
+                    string for <tt>A</tt> answers, or arbitrary text
+                    for <tt>TXT</tt> answers.  For records with a
+                    priority (like MX records) put the priority first
+                    and then a space and then the content, e.g: <tt>10
+                    mail.example.com</tt>
+
+[<tt>:id</tt>] An integer id for this answer. PowerDNS will remember
+               this and pass it back for subsequent requests for the
+               same record.  You might use this to pass around a
+               primary key or something to speed up subsequent
+               lookups.  Defaults to -1 and can be ignored.
+
+[<tt>:class</tt>] The class of this answer, defaults to <tt>IN</tt>
+                  and shouldn't be changed.
+
+== Basic example
+
+Return an <tt>A</tt> record of <tt>1.2.3.4</tt> for all queries:
+
+  require 'powerdns_pipe'
+  PowerDNS::Pipe.new.run! do
+    answer :name => question.name, :type => 'A', :ttl => 60, :content => '1.2.3.4'
+  end
+
+== Advanced example
+
+Return the HTTP Server header as a TXT record for the host requested.
+
+Example usage:
+
+  $ host -t txt www.ubuntu.com.example.com
+  ubuntu.com.example.com descriptive text "Apache/2.2.8 (Ubuntu) mod_python/3.3.1"
+
+Code:
+
+  require 'powerdns_pipe'
+  require 'net/http'
+  re = Regexp.new("^(.+)\.example\.com$")
+  pipe = PowerDNS::Pipe.new :banner => 'HTTP Server Header TXT Pipe'
+  pipe.run! do
+    if m = re.match(question.name)
+      domain = m[1]
+      case question.qtype
+      when "TXT", "ANY"
+        res = Net::HTTP.get_response(URI.parse("http://" + domain))
+        answer :name => question.name , :type => 'TXT', :ttl => 3600, 
+          :content => res['Server']
+      end
+    end
+  end
+  
+= More Info
+
+Author::  John Leach  (mailto:john@johnleach.co.uk)
+Copyright:: Copyright (c) 2010 John Leach
+License:: MIT
+Github:: http://github.com/johnl/powerdns_pipe/tree/master
+
+See also the {ruby-pdns library}[http://code.google.com/p/ruby-pdns/]
+which does things differently, with some limitations.

data/lib/powerdns_pipe.rb

@@ -0,0 +1,127 @@
+module PowerDNS
+
+  # DnsPipe is an abstraction of the Powerdns pipe backend protocol.
+  # http://doc.powerdns.com/backends-detail.html
+  #
+  # It's dead simple to use, see the README for examples
+  #
+  # Written by John Leach <john@johnleach.co.uk>
+  #
+  class Pipe
+    attr_reader :input, :output, :err, :version_range, :banner
+
+    # Answer object is just used to wrap the block that handles answering
+    # queries
+    class Answer
+      attr_reader :question
+
+      def initialize(pipe, question)
+        @pipe = pipe
+        @question = question
+      end
+
+      def answer(*args)
+        @pipe.answer *args
+      end
+
+    end
+
+    # Question wraps any type of question line from the server
+    class Question < Struct.new(:tag, :name, :qclass, :qtype, :id, :remote_ip_address, :local_ip_address)
+
+      def to_s
+        [tag, name, qclass, qtype, id, remote_ip_address, local_ip_address].join("\t")
+      end
+
+      def query?
+        tag == "Q"
+      end
+
+      def axfr?
+        tag == "AXFR"
+      end
+    end
+
+    def initialize(options = {})
+      options = { 
+        :input => STDIN,
+        :output => STDOUT,
+        :err => STDERR,
+        :version_range => 1..2,
+        :banner => "Ruby PowerDNS::Pipe"
+      }.merge options
+
+      @input = options[:input]
+      @output = options[:output]
+      @err = options[:err]
+      @version_range = options[:version_range]
+      @banner = options[:banner]
+    end
+
+    def run!(&query_processor)
+      while (line = input.readline) do
+        process_line line, query_processor
+      end
+    rescue EOFError
+      err.write "EOF, terminating loop\n"
+    end
+
+    def answer(options = {})
+      options = {
+        :ttl => 3600,
+        :id => -1,
+        :class => 'IN'
+      }.merge options
+
+      respond "DATA", options[:name], options[:class], options[:type], options[:ttl], options[:content]
+    end
+
+    private
+
+    def process_line(line, query_processor)
+      q = Question.new *line.chomp.split("\t")
+      qtypes = { 
+        "HELO" => :process_helo,
+        "Q" => :process_query,
+        "AXFR" => :process_query,
+        "PING" => :process_ping
+      }
+
+      self.send(qtypes.fetch(q.tag, :process_unknown), q, query_processor)
+    end
+
+    def process_helo(q, query_processor)
+      if version_range === (q.name.to_i rescue -1)
+        respond "OK", banner
+      else
+        respond "FAIL", banner
+      end
+    end
+
+    def process_query(q, query_processor)
+      answer = Answer.new(self, q)
+      begin
+        answer.instance_eval &query_processor
+        respond "END"
+      rescue StandardError => e
+        respond "LOG", "Error: #{e.class}: #{e.message}"
+        respond "FAIL"
+      end
+
+    end
+
+    def process_unknown(q, query_processor)
+      respond "LOG", "Unknown Question received: #{q}"
+      respond "FAIL"
+    end
+
+    def process_ping(q, query_processor)
+      respond "END"
+    end
+
+    def respond(*args)
+      output.write(args.join("\t") + "\n")
+      output.flush
+    end
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: powerdns_pipe
+version: !ruby/object:Gem::Version 
+  hash: 15
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  version: "1.0"
+platform: ruby
+authors: 
+- John Leach
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-16 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: A library to allow easy development of powerdns pipe backend resolvers in Ruby
+email: john@johnleach.co.uk
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/powerdns_pipe.rb
+- README.rdoc
+has_rdoc: true
+homepage: http://github.com/johnl/powerdns_pipe/tree/master
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --title
+- PowerDNS Pipe
+- --main
+- README.rdoc
+- --line-numbers
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A Ruby abstraction of the PowerDNS pipe backend protocol
+test_files: []
+