nominet-epp 0.0.2

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Geoff Garside
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,17 @@
+= nominet-epp
+
+Description goes here.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Geoff Garside. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "nominet-epp"
+    gem.summary = %Q{Nominet EPP (Extensible Provisioning Protocol) Client}
+    gem.description = %Q{Client for communicating with the Nominet EPP}
+    gem.email = "geoff@geoffgarside.co.uk"
+    gem.homepage = "http://github.com/geoffgarside/nominet-epp"
+    gem.authors = ["Geoff Garside"]
+    gem.add_development_dependency "shoulda", ">= 0"
+    gem.add_development_dependency "yard", ">= 0"
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+    gem.add_dependency "epp-client", ">= 0"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.2

data/lib/nominet-epp.rb

@@ -0,0 +1,139 @@
+require 'epp-client'
+require 'time'
+
+require File.dirname(__FILE__) + '/nominet-epp/operations'
+require File.dirname(__FILE__) + '/nominet-epp/helpers'
+
+# Nominet EPP Module
+module NominetEPP
+  # Front end interface Client to the NominetEPP Service
+  class Client
+    # Default Nominet Service URNs
+    DEFAULT_SERVICES = %w(http://www.nominet.org.uk/epp/xml/nom-domain-2.0
+      http://www.nominet.org.uk/epp/xml/nom-notifications-2.0
+      urn:ietf:params:xml:ns:host-1.0)
+
+    # Create a new instance of NominetEPP::Client
+    #
+    # @param [String] tag Nominet TAG
+    # @param [String] passwd Nominet TAG EPP Password
+    # @param [String] server Nominet EPP Server address
+    def initialize(tag, passwd, server = 'epp.nominet.org.uk')
+      @tag, @server = tag, server
+      @client = EPP::Client.new(tag, passwd, server, :services => DEFAULT_SERVICES)
+    end
+
+    # @see Object#inspect
+    def inspect
+      "#<#{self.class} #{@tag}@#{@server}>"
+    end
+
+    # @return [Hash] Nominet Namespaces by prefixes
+    def namespaces
+      { :domain  => 'http://www.nominet.org.uk/epp/xml/nom-domain-2.0',
+        :account => 'http://www.nominet.org.uk/epp/xml/nom-account-2.0',
+        :contact => 'http://www.nominet.org.uk/epp/xml/nom-contact-2.0',
+        :tag     => 'http://www.nominet.org.uk/epp/xml/nom-tag-1.0',
+        :n       => 'http://www.nominet.org.uk/epp/xml/nom-notifications-2.0' }
+    end
+
+    # @return [Hash] Nominet Schema Locations by prefix
+    def schemaLocations
+      { :domain  => 'http://www.nominet.org.uk/epp/xml/nom-domain-2.0 nom-domain-2.0.xsd',
+        :account => 'http://www.nominet.org.uk/epp/xml/nom-account-2.0 nom-account-2.0.xsd',
+        :contact => 'http://www.nominet.org.uk/epp/xml/nom-contact-2.0 nom-contact-1.0.xsd',
+        :tag     => 'http://www.nominet.org.uk/epp/xml/nom-tag-1.0 nom-tag-1.0.xsd',
+        :n       => 'http://www.nominet.org.uk/epp/xml/nom-notifications-2.0  nom-notifications-2.0.xsd' }
+    end
+
+    include Helpers
+
+    include Operations::Check
+    include Operations::Create
+    include Operations::Delete
+    include Operations::Fork
+    include Operations::Hello
+    include Operations::Info
+    include Operations::List
+    include Operations::Lock
+    include Operations::Merge
+    include Operations::Poll
+    include Operations::Renew
+    include Operations::Transfer
+    include Operations::Unlock
+    include Operations::Unrenew
+    include Operations::Update
+
+    private
+      # @param [XML::Node] node XML Node to find the value from
+      # @param [String] xpath XPath Expression for the value
+      # @return [String] node value
+      def node_value(node, xpath)
+        n = node.find(xpath, namespaces).first
+        n && n.content.strip
+      end
+
+      # @param [String] name XML Element name
+      # @param [Symbol] ns_prefix Namespace Prefix
+      # @yield [node, ns] block to populate node
+      # @yieldparam [XML::Node] node XML Node to populate
+      # @yieldparam [XML::Namespace] ns XML Namespace of the node
+      # @return [XML::Node] newly created node
+      def new_node(name, ns_prefix, &block)
+        node = XML::Node.new(name)
+        node.namespaces.namespace = ns = XML::Namespace.new(node, ns_prefix.to_s, namespaces[ns_prefix])
+        node['xsi:schemaLocation'] = schemaLocations[ns_prefix]
+
+        case block.arity
+        when 0
+          yield
+        when 1
+          yield node
+        when 2
+          yield node, ns
+        end
+
+        node
+      end
+
+      # @param [String] node_name XML Element name
+      # @yield [node, ns] block to populate node
+      # @return [XML::Node] new node in :domain namespace
+      # @see new_node
+      def domain(node_name, &block)
+        new_node(node_name, :domain, &block)
+      end
+
+      # @param [String] node_name XML Element name
+      # @yield [node, ns] block to populate node
+      # @return [XML::Node] new node in :account namespace
+      # @see new_node
+      def account(node_name, &block)
+        new_node(node_name, :account, &block)
+      end
+
+      # @param [String] node_name XML Element name
+      # @yield [node, ns] block to populate node
+      # @return [XML::Node] new node in :contact namespace
+      # @see new_node
+      def contact(node_name, &block)
+        new_node(node_name, :contact, &block)
+      end
+
+      # @param [String] node_name XML Element name
+      # @yield [node, ns] block to populate node
+      # @return [XML::Node] new node in :tag namespace
+      # @see new_node
+      def tag(node_name, &block)
+        new_node(node_name, :tag, &block)
+      end
+
+      # @param [String] node_name XML Element name
+      # @yield [node, ns] block to populate node
+      # @return [XML::Node] new node in :notification namespace
+      # @see new_node
+      def notification(node_name, &block)
+        new_node(node_name, :n, &block)
+      end
+  end
+end

data/lib/nominet-epp/helpers.rb

@@ -0,0 +1,83 @@
+module NominetEPP
+  # Helper methods
+  module Helpers
+    # @param [String, Array] nameservers Nameserver host name or array of host names or hashes
+    # @param [XML::Namespace] ns XML Namespace to create the elements with
+    # @return [XML::Node] +ns+ element of +host+ elements
+    # @see domain_host_xml
+    def domain_ns_xml(nameservers, ns)
+      ns_el = XML::Node.new('ns', nil, ns)
+
+      case nameservers.class
+      when String
+        ns_el << (XML::Node.new('host', nil, ns) << XML::Node.new('hostName', nameservers, ns))
+      when Array
+        nameservers.each do |nameserver|
+          ns_el << domain_host_xml(nameserver, ns)
+        end
+      else
+        raise ArgumentError, "nameservers must either be a string or array of strings"
+      end
+
+      ns_el
+    end
+
+    # @param [String, Hash] nameserver Nameserver host name or hash of +:name+ and +:v4+ or +:v6+ address
+    # @param [XML::Namespace] ns XML Namespace to create the elements with
+    # @return [XML::Node] +host+ element with +hostName+ and optionally +ip+ subelements
+    def domain_host_xml(nameserver, ns)
+      host = XML::Node.new('host', nil, ns)
+
+      case nameserver.class
+      when String
+        host << XML::Node.new('hostName', nameserver, ns)
+      when Hash
+        host << XML::Node.new('hostName', nameserver[:name], ns)
+        if nameserver[:v4]
+          n = XML::Node.new('hostAddr', nameserver[:v4], ns)
+          n['ip'] = 'v4'
+          host << n
+        end
+        if nameserver[:v6]
+          n = XML::Node.new('hostAddr', nameserver[:v6], ns)
+          n['ip'] = 'v6'
+          host << n
+        end
+      end
+
+      host
+    end
+
+    # Adds the attributes from the fields to the +node+.
+    #
+    # @param [Hash] fields Account attributes to marshal
+    # @param [XML::Node] node XML Node to add the attributes to
+    # @param [XML::Namespace] ns XML Namespace to create the elements under
+    def account_fields_xml(fields, node, ns)
+      fields.each do |k,v|
+        case k
+        when :contacts
+          v.each do |c|
+            node << (c_node = XML::Node.new('contact', nil, ns))
+            c_node['order'] = c.delete(:order)
+            c_node['type'] = 'admin'
+
+            c_node << contact(c.delete(:action) || 'create') do |cn, cns|
+              c.each do |l,w|
+                cn << XML::Node.new(l, w, cns)
+              end
+            end
+          end
+        when :addr  # Limitation, can only handle one addr at a time
+          node << (a_node = XML::Node.new('addr', nil, ns))
+          a_node['type'] = 'admin'
+          v.each do |l,w|
+            a_node << XML::Node.new(l, w, ns)
+          end
+        else
+          node << XML::Node.new(k.to_s.gsub('_', '-'), v, ns)
+        end
+      end
+    end
+  end
+end

data/lib/nominet-epp/operations.rb

@@ -0,0 +1,20 @@
+module NominetEPP
+  # Module to enclose the Operations
+  module Operations
+    autoload :Check,    File.dirname(__FILE__) + '/operations/check.rb'
+    autoload :Create,   File.dirname(__FILE__) + '/operations/create.rb'
+    autoload :Delete,   File.dirname(__FILE__) + '/operations/delete.rb'
+    autoload :Fork,     File.dirname(__FILE__) + '/operations/fork.rb'
+    autoload :Hello,    File.dirname(__FILE__) + '/operations/hello.rb'
+    autoload :Info,     File.dirname(__FILE__) + '/operations/info.rb'
+    autoload :List,     File.dirname(__FILE__) + '/operations/list.rb'
+    autoload :Lock,     File.dirname(__FILE__) + '/operations/lock.rb'
+    autoload :Merge,    File.dirname(__FILE__) + '/operations/merge.rb'
+    autoload :Poll,     File.dirname(__FILE__) + '/operations/poll.rb'
+    autoload :Renew,    File.dirname(__FILE__) + '/operations/renew.rb'
+    autoload :Transfer, File.dirname(__FILE__) + '/operations/transfer.rb'
+    autoload :Unlock,   File.dirname(__FILE__) + '/operations/unlock.rb'
+    autoload :Unrenew,  File.dirname(__FILE__) + '/operations/unrenew.rb'
+    autoload :Update,   File.dirname(__FILE__) + '/operations/update.rb'
+  end
+end

data/lib/nominet-epp/operations/check.rb

@@ -0,0 +1,39 @@
+module NominetEPP
+  module Operations
+    # EPP Check Operation
+    module Check
+      # Check the availablity of one or more domain names
+      #
+      # @param [String, ...] *names List of names to check
+      # @return [false] request failed
+      # @return [true] the domain name is available
+      # @return [Hash<String,Boolean>] availability by domain name
+      def check(*names)
+        resp = @client.check do
+          domain('check') do |node, ns|
+            names.each do |name|
+              node << XML::Node.new('name', name, ns)
+            end
+          end
+        end
+
+        return false unless resp.success?
+
+        @check_limit = check_abuse_limit(resp.data)
+        results = resp.data.find('//domain:name', namespaces)
+        if results.size > 1
+          hash = {}
+          results.each {|node| hash[node.content.strip] = (node['avail'] == '1') }
+          hash
+        else
+          results.first['avail'] == '1'
+        end
+      end
+
+      protected
+        def check_abuse_limit(data)
+          data.find('//domain:chkData/@abuse-limit', namespaces).first.value.to_i
+        end
+    end
+  end
+end

data/lib/nominet-epp/operations/create.rb

@@ -0,0 +1,166 @@
+module NominetEPP
+  module Operations
+    # EPP Create Operation
+    module Create
+      # Register a domain name with Nominet.
+      #
+      # The returned hash has the following keys
+      # - (String) +:name+ --    Domain name registered
+      # - (Time) +:crDate+ --    Domain creation date
+      # - (Time) +:exDate+ --    Domain expiration date
+      # - (Hash) +:account+ --   Created account data (if returned)
+      #
+      # The +:account+ hash contains the following keys
+      # - (String) +:roid+ --    Account ID
+      # - (String) +:name+ --    Account Name
+      # - (Array) +:contacts+ -- Account contacts
+      #
+      # The +:contacts+ array contains hashes of the following keys
+      # - (String) +:roid+ --    Contact ID
+      # - (String) +:name+ --    Contact Name
+      # - (String) +:type+ --    Contact type if set
+      # - (Integer) +:order+ --  Contacts order in the list of contacts
+      #
+      # @param [String] name Domain name to register
+      # @param [String] acct
+      # @param [Array] nameservers Nameservers to set for the domain
+      # @param [Hash] options Registration options
+      # @option options [String] :period
+      # @option options [String] :first_bill
+      # @option options [String] :recur_bill
+      # @option options [String] :auto_bill
+      # @option options [String] :next_bill
+      # @option options [String] :notes
+      # @raise [ArgumentError] invalid option keys
+      # @return [false] registration failed
+      # @return [Hash] Domain creation data
+      def create(name, acct, nameservers, options = {})
+        raise ArgumentError, "options allowed keys are period, first_bill, recur_bill, auto_bill, next_bill, notes" unless (options.keys - [:period, :first_bill, :recur_bill, :auto_bill, :next_bill, :notes]).empty?
+
+        resp = @client.create do
+          domain('create') do |node, ns|
+            node << XML::Node.new('name', name, ns)
+
+            options[:period] && node << XML::Node.new('period', options.delete(:period), ns)
+
+            acct_xml = XML::Node.new('account', nil, ns)
+            acct_xml << create_account(acct, ns)
+            node << acct_xml
+
+            node << domain_ns_xml(nameservers, ns)
+
+            options.each do |key, value|
+              node << XML::Node.new(key.to_s.gsub('_', '-'), value, ns)
+            end
+          end
+        end
+
+        return false unless resp.success?
+
+        creData = resp.data.find('/domain:creData', namespaces).first
+        h = { :name => node_value(creData, 'domain:name'),
+          :crDate => Time.parse(node_value(creData, 'domain:crDate')),
+          :exDate => Time.parse(node_value(creData, 'domain:exDate')) }
+        unless creData.find('domain:account').first.nil?
+          h[:account] = created_account(creData.find('domain:account/account:creData', namespaces).first)
+        end
+        h
+      end
+      
+      private
+        # Create the account payload
+        #
+        # @param [String, Hash] acct Account ID or New account fields
+        # @param [XML::Namespace] domain_ns +:domain+ namespace
+        # @raise [ArgumentError] acct must be a String or a Hash of account fields
+        # @return [XML::Node]
+        def create_account(acct, domain_ns)
+          if acct.kind_of?(String)
+            XML::Node.new('account-id', acct, domain_ns)
+          elsif acct.kind_of?(Hash)
+            account('create') do |node, ns|
+              node << XML::Node.new('name', acct[:name], ns)
+              node << XML::Node.new('trad-name', acct[:trad_name], ns)
+              node << XML::Node.new('type', acct[:type], ns)
+              node << XML::Node.new('opt-out', acct[:opt_out], ns)
+
+              acct[:contacts].each_with_index do |cont, i|
+                c = XML::Node.new('contact', nil, ns)
+                c['order'] = i
+                node << (c << create_account_contact(cont))
+              end
+
+              node << create_account_address(acct[:addr], ns)
+            end
+          else
+            raise ArgumentError, "acct must be String or Hash"
+          end
+        end
+
+        # Create account contact payload
+        #
+        # @param [Hash] cont Contact fields
+        # @raise [ArgumentError] invalid contact fields
+        # @raise [ArgumentError] name or email key is missing
+        # @return [XML::Node]
+        def create_account_contact(cont)
+          raise ArgumentError, "Contact allowed keys are name, email, phone and mobile" unless (cont.keys -[:name, :email, :phone, :mobile]).empty?
+          raise ArgumentError, "Contact requires name and email keys" unless cont.has_key?(:name) && cont.has_key?(:email)
+
+          contact('create') do |node, ns|
+            cont.each do |key, value|
+              node << XML::Node.new(key, value, ns)
+            end
+          end
+        end
+
+        # Create contact address
+        #
+        # @param [Hash] addr Address fields
+        # @raise [ArgumentError] invalid keys in addr
+        # @return [XML::Node]
+        def create_account_address(addr, ns)
+          raise ArgumentError, "Address allowed keys are street, locality, city, county, postcode, country" unless (addr.keys - [:street, :locality, :city, :county, :postcode, :country]).empty?
+
+          addr = XML::Node.new('addr', nil, ns)
+          addr.each do |key, value|
+            addr << XML::Node.new(key, value, ns)
+          end
+
+          addr
+        end
+
+        # Collects created account information
+        #
+        # @param [XML::Node] creData XML
+        # @return [Hash]
+        def created_account(creData)
+          { :roid => node_value(creData, 'account:roid'),
+            :name => node_value(creData, 'account:name'),
+            :contacts => created_contacts(creData.find(
+              'account:contact', namespaces)) }
+        end
+
+        # Collects created account contacts
+        #
+        # @param [XML::Node] account_contacts Account contacts
+        # @return [Hash]
+        def created_contacts(account_contacts)
+          account_contacts.map do |cont|
+            { :type => cont['type'],
+              :order => cont['order'] }.merge(
+                created_contact(cont.find('contact:creData', namespaces).first))
+          end
+        end
+
+        # Collects create contact information
+        #
+        # @param [XML::Node] creData XML
+        # @return [Hash]
+        def created_contact(creData)
+          { :roid => node_value(creData, 'contact:roid'),
+            :name => node_value(creData, 'contact:name') }
+        end
+    end
+  end
+end