netdot-restclient 1.4 → 2.0.0

data/README.md

@@ -50,6 +50,8 @@ The Netdot user manual at:
 
     http://netdot.uoregon.edu
 
+See the sample/sample.rb for sample usage of the Host and Ipblock classes.
+
 ## Contributing
 
 1. Fork it ( https://github.com/cvicente/netdot-restclient/fork )

data/Rakefile

@@ -1,2 +1,8 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'yard'
 
+YARD::Rake::YardocTask.new do |_t|
+  # t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
+  # t.options = ['--any', '--extra', '--opts'] # optional
+  # t.stats_options = ['--list-undoc']         # optional
+end

data/lib/netdot.rb

@@ -1,16 +1,17 @@
 require 'logger'
 
+# Netdot
 module Netdot
-
   class << self
     attr_accessor :logger
   end
 
+  # NullLogger
   class NullLogger < Logger
-    def initialize(*args)
+    def initialize(*_args)
     end
 
-    def add(*args, &block)
+    def add(*_args, &_block)
     end
   end
 
@@ -19,4 +20,4 @@ end
 
 require 'netdot/restclient'
 require 'netdot/host'
-require 'netdot/subnet'
+require 'netdot/ipblock'

data/lib/netdot/host.rb

@@ -1,61 +1,68 @@
+# Netdot
 module Netdot
+  # Manage Host objects.
   class Host
     attr_accessor :connection
 
+    # Constructor
+    # @param :connection [Hash] a Netdot::RestClient object
     def initialize(argv = {})
       [:connection].each do |k|
-        raise ArgumentError, "Missing required argument '#{k}'" unless argv[k]
+        fail ArgumentError, "Missing required argument '#{k}'" unless argv[k]
       end
 
-      argv.each { |k,v| instance_variable_set("@#{k}", v) }
+      argv.each { |k, v| instance_variable_set("@#{k}", v) }
     end
 
-    ##############################################################
-    # Find RR and Ipblock records with flexible arguments
-    # Handle exceptions
+    # Finds all RR and Ipblock records, given a flexible set of arguments.
+    # Handles NOT FOUND exceptions.
+    # @param param [String] a generic parameter
+    # @param value [String] a generic value
     def find(param, value)
       begin
-        host = @connection.get("/host?#{param.to_s}=#{value}");
-      rescue Exception => e
+        host = @connection.get("/host?#{param}=#{value}")
+      rescue => e
         # Not Found is ok, otherwise re-raise
-        raise unless (e.message =~ /404/)
+        raise unless e.message =~ /404/
       end
       # Return what we got
       host
     end
 
-    ##############################################################
-    # Find RR and Ipblock records associated with given name
+    # Finds all RR and Ipblock records associated with the specified name.
+    # @param name [String]
     def find_by_name(name)
       find(:name, name)
     end
 
-    ##############################################################
-    # Find RR and Ipblock records associated with this IP
+    # Finds all RR and Ipblock records associated with the specified IP.
+    # @param ip [String]
     def find_by_ip(ip)
       find(:address, ip)
     end
 
-    ##############################################################
-    # Create A record for given name and IP
-    # Will also create PTR record if .arpa zone exists
+    # Creates a DNS A record for the specified name and IP.
+    # Will also create PTR record if .arpa zone exists.
+    # @param name [String]
+    # @param ip [String]
     def create(name, ip)
-      Netdot.logger.debug("Creating new DNS records with name:#{name} and ip:#{ip}")
-      @connection.post('host', {'name' => name, 'address' => ip})
+      Netdot.logger.debug("Creating new DNS records with name:#{name}" \
+      " and ip:#{ip}")
+      @connection.post('host', 'name' => name, 'address' => ip)
     end
 
-    ##############################################################
-    # Update A record for given name and IP
-    # Will also create PTR record if .arpa zone exists
+    # Updates the DNS A record for the sepcified name and IP.
+    # Will also create PTR record if .arpa zone exists.
+    # @param name [String]
+    # @param ip [String]
     def update(name, ip)
       Netdot.logger.debug("Updating DNS records with name:#{name} and ip:#{ip}")
       delete(name)
-      #delete_by_ip(ip)
       create(name, ip)
     end
 
-    ##############################################################
-    # Delete A record for given name
+    # Deletes the DNS A record for the specified name.
+    # @param name [String]
     def delete(name)
       host = find_by_name(name)
       return unless host
@@ -65,12 +72,11 @@ module Netdot
       host['Ipblock'].keys.each do |id|
         begin
           @connection.delete("host?ipid=#{id}")
-        rescue Exception => e
+        rescue => e
           # Not Found is ok, otherwise re-raise
-          raise unless (e.message =~ /404/)
+          raise unless e.message =~ /404/
         end
       end
     end
-
   end
 end

data/lib/netdot/ipblock.rb

@@ -0,0 +1,118 @@
+# Netdot
+module Netdot
+  # Manage Ipblock objects.
+  class Ipblock
+    attr_accessor :connection
+
+    # Constructor
+    # @param :connection [Hash] a Netdot::RestClient object
+    def initialize(argv = {})
+      [:connection].each do |k|
+        fail ArgumentError, "Missing required argument '#{k}'" unless argv[k]
+      end
+
+      argv.each { |k, v| instance_variable_set("@#{k}", v) }
+    end
+
+    # Gets the next available Ipblock in the specified container.
+    # @param container [String] address
+    # @param prefix [Fixnum]
+    # @param description [String] (optional)
+    # @return [String] new Ipblock id, or nil
+    def allocate(container, prefix = 24, description = nil)
+      # Netdot currently only supports /24 prefixes
+      fail ArgumentError,
+           "Prefix size #{prefix} is not currently supported (must be 24)" \
+        unless prefix == 24
+
+      # Search for container and get its ID
+      cont_id = find_by_addr(container)
+
+      # Get container's children blocks
+      begin
+        resp = @connection.get("Ipblock?parent=#{cont_id}")
+      rescue => e
+        # Not Found is ok, otherwise re-raise
+        raise unless e.message =~ /404/
+      end
+
+      # store existing Ipblocks in hash (if any)
+      ipblocks = {}
+      if resp
+        resp.values.each do |b|
+          b.each do |_k, v|
+            address = v['address']
+            ipblocks[address] = 1
+          end
+        end
+      end
+
+      # Iterate over all possible Ipblocks
+      # This assumes that Ipblocks are /24
+      spref = container.split('/')[0]
+      spref.gsub!(/(\d+\.\d+)\..*/, '\1')
+
+      (1..255).each do |n|
+        spref.dup
+        saddr = spref + ".#{n}.0"
+        if !ipblocks.empty? && ipblocks.key?(saddr)
+          next # Ipblock exists
+        end
+
+        # Create Ipblock
+        args = {
+          'address' => saddr,
+          'prefix' => prefix.to_s,
+          'status' => 'Subnet'
+        }
+        args['description'] = description unless description.nil?
+        resp = @connection.post('Ipblock', args)
+        return resp['address'] + '/' + resp['prefix']
+      end
+
+      fail "Could not allocate Ipblock in #{container}"
+    end
+
+    # Deletes an Ipblock (and optionally, all its children), for the specified
+    # address or CIDR.
+    # @param ipblock [String] address or CIDR
+    # @return (Truth)
+    def delete(ipblock, recursive = false)
+      if recursive
+        resp = @connection.get("host?subnet=#{ipblock}")
+        unless resp.empty?
+          resp['Ipblock'].keys.each do |id|
+            @connection.delete("Ipblock/#{id}")
+          end
+        end
+      end
+
+      sid = find_by_addr(ipblock)
+      @connection.delete("Ipblock/#{sid}")
+    end
+
+    # Gets the matching Ipblock id for the specified address (in CIDR format).
+    # @param cidr [String]
+    # @return [Ipblock]
+    def find_by_addr(cidr)
+      (address, prefix) = cidr.split('/')
+      prefix ||= '24'
+      begin
+        @connection.get("Ipblock?address=#{address}&prefix=#{prefix}")[
+          'Ipblock'].keys[0]
+      rescue => e
+        raise unless e.message =~ /404/
+      end
+    end
+
+    # Gets an array of matching Ipblock ids for the specified description
+    # (name).
+    # @param descr [String]
+    # @return [Array<Ipblock>]
+    def find_by_descr(descr)
+      @connection.get("Ipblock?description=#{descr}")['Ipblock']
+      rescue => e
+        raise unless e.message =~ /404/
+    end
+  end
+end

data/lib/netdot/restclient.rb

@@ -2,92 +2,83 @@ require 'netdot/restclient/version'
 
 require 'httpclient'
 
+# Netdot
 module Netdot
-  class RestClient    
+  # Manage RestClient objects.
+  class RestClient
     attr_accessor :format, :base_url, :ua, :xs
 
     # Constructor and login method
-    #
-    # Arguments (hash):
-    #
-    # server          - Netdot server URL
-    # username        - Netdot Username
-    # password        - Netdot password
-    # retries         - Number of attempts
-    # timeout         - Timeout in seconds
-    # format          - Content format <xml>
-    # ssl_version     - Specify version of SSL (see httpclient)
-    # ssl_verify      - Verify server cert (default: yes)
-    # ssl_ca_file     - Path to SSL CA cert file 
-    # ssl_ca_dir      - Path to SSL CA cert directory
-    # cookie_file     - Cookie filename
-    #
-    # Returns:
-    #   Netdot::RestClient object
-    # Example:
-    #   Netdot::Restclient.new(args)
-    #
+    # @param :server [String] Netdot server URL
+    # @param :username [String] Netdot Username
+    # @param :password [String] Netdot password
+    # @param :retries [String] (optional) Number of attempts
+    # @param :timeout [String] (optional) Timeout in seconds
+    # @param :format [String] (optional) Content format <xml>
+    # @param :ssl_version [String] (optional) Specify version of SSL;
+    #   see HTTPClient
+    # @param :ssl_verify [String] (optional) Verify server cert (default: yes)
+    # @param :ssl_ca_file [String] (optional) Path to SSL CA cert file
+    # @param :ssl_ca_dir [String] (optional) Path to SSL CA cert directory
+    # @param :cookie_file [String] (optional) Cookie filename
     def initialize(argv = {})
-      
       [:server, :username, :password].each do |k|
-        raise ArgumentError, "Missing required argument '#{k}'" unless argv[k]
+        fail ArgumentError, "Missing required argument '#{k}'" unless argv[k]
       end
-      
-      argv.each { |k,v| instance_variable_set("@#{k}", v) }
-      
-      @timeout     ||= 10
-      @retries     ||= 3
-      @format      ||= 'xml'
+
+      argv.each { |k, v| instance_variable_set("@#{k}", v) }
+
+      @timeout ||= 10
+      @retries ||= 3
+      @format ||= 'xml'
       @cookie_file ||= './cookie.dat'
-      defined?(@ssl_verify) or @ssl_verify = true
+      defined?(@ssl_verify) || @ssl_verify = true
 
-      if ( @format == 'xml' ) 
+      if (@format == 'xml')
         begin
           require 'xmlsimple'
-        rescue LoadError => e
-          raise LoadError, "Cannot load XML library. Try running 'gem install xml-simple'"
+        rescue LoadError
+          raise LoadError,
+                "Cannot load XML library. Try running 'gem install xml-simple'"
         end
-        xs = XmlSimple.new({ 'ForceArray' => true, 'KeyAttr' => 'id'})
+        xs = XmlSimple.new('ForceArray' => true, 'KeyAttr' => 'id')
         @xs = xs
       else
-        raise ArgumentError, "Only XML formatting supported at this time"
+        fail ArgumentError, 'Only XML formatting supported at this time'
       end
 
-      ua = HTTPClient.new(:agent_name => "Netdot::RestClient/#{self.version}")
+      ua = HTTPClient.new(agent_name: "Netdot::RestClient/#{version}")
       ua.set_cookie_store("#{@cookie_file}")
 
       # SSL stuff
-      if ( @ssl_verify )
-        if ( @ssl_ca_dir )
+      if @ssl_verify
+        if @ssl_ca_dir
           # We are told to add a certs path
           # We'll want to clear the default cert store first
           ua.ssl_config.clear_cert_store
           ua.ssl_config.set_trust_ca(@ssl_ca_dir)
-        elsif ( @ssl_ca_file )
-          ua.ssl_config.set_trust_ca(@ssl_ca_file)            
+        elsif @ssl_ca_file
+          ua.ssl_config.set_trust_ca(@ssl_ca_file)
         end
       else
         ua.ssl_config.verify_mode = OpenSSL::SSL::VERIFY_NONE
       end
 
       # If version given, set it
-      if ( @ssl_version )
-        ua.ssl_config.ssl_version = @ssl_version
-      end
+      ua.ssl_config.ssl_version = @ssl_version if @ssl_version
 
       login_url = @server + '/NetdotLogin'
-      
+
       resp = nil
 
       @retries.times do
-        resp = ua.post login_url, {
-          'destination'       => 'index.html',
-          'credential_0'      => @username,
-          'credential_1'      => @password,
-          'permanent_session' => 1,
-        }
-
-        if ( resp.status == 302 )
+        resp = ua.post login_url,
+                       'destination'       => 'index.html',
+                       'credential_0'      => @username,
+                       'credential_1'      => @password,
+                       'permanent_session' => 1
+
+        if (resp.status == 302)
           ua.save_cookie_store
           @ua = ua
           @base_url = @server + '/rest'
@@ -97,82 +88,61 @@ module Netdot
         end
       end
 
-      unless ( resp.status == 302 )
-        raise "Could not log into #{@server}. Status Code: '#{resp.status}'"
-      end
-
+      return if (resp.status == 302)
+      fail "Could not log into #{@server}. Status Code: '#{resp.status}'"
     end
-    
 
-    # Build the Extra headers
-    #
+    # Builds the Extra headers.
     def extheader
-      { 'Accept' => 'text/' + self.format + '; version=1.0' }
+      { 'Accept' => 'text/' + format + '; version=1.0' }
     end
 
-    # Build URL given a resource
-    #
+    # Builds a URL for the specified resource.
+    # @param [String] resource a URI
     def build_url(resource)
-      self.base_url + '/' + resource
+      base_url + '/' + resource
     end
 
-    # Get a resource
-    #
-    # Arguments:
-    #   resource - A URI
-    # Returns:
-    #   hash when successful
-    #   exception when not
+    # Gets a resource.
+    # @param [String] resource a URI
+    # @return [Hash] hash when successful; exception when not
     def get(resource)
-      url = self.build_url(resource)
-      resp = self.ua.get(url, nil, self.extheader)
-      if ( resp.status == 200 )
-        self.xs.xml_in(resp.content)
+      url = build_url(resource)
+      resp = ua.get(url, nil, extheader)
+      if (resp.status == 200)
+        xs.xml_in(resp.content)
       else
-        raise "Could not get #{url}: #{resp.status}" 
+        fail "Could not get #{url}: #{resp.status}"
       end
     end
 
-
-    # Update or create a resource
-    # 
-    # Arguments:
-    #   resource - A URI
-    #   data     - Hash with key/values
-    # Returns:
-    #   new or modified record hash when successful
-    #   exception when not
+    # Updates or creates a resource.
+    # @param [String] resource a URI
+    # @param [Hash] data
+    # @return [Hash] new or modified record hash when successful; exception
+    #   when not
     def post(resource, data)
-      url = self.build_url(resource)
-      raise ArgumentError, "Data must be hash" unless data.is_a?(Hash)
-      resp = self.ua.post(url, data, self.extheader)
-      if ( resp.status == 200 )
-        self.xs.xml_in(resp.content)
+      url = build_url(resource)
+      fail ArgumentError, 'Data must be hash' unless data.is_a?(Hash)
+      resp = ua.post(url, data, extheader)
+      if (resp.status == 200)
+        xs.xml_in(resp.content)
       else
-        raise "Could not post to #{url}: #{resp.status}"
+        fail "Could not post to #{url}: #{resp.status}"
       end
     end
 
-
-    # Delete a resource
-    # 
-    # Arguments:
-    #   resource - A URI
-    #   
-    # Returns:
-    #   true when successful
-    #   exception when not
-    #
+    # Deletes a resource.
+    # @param [String] resource a URI
+    # @return [Truth] true when successful; exception when not
     def delete(resource)
-      url = self.build_url(resource)
-      resp = self.ua.delete(url, nil, self.extheader)
-      if ( resp.status == 200 )
+      url = build_url(resource)
+      resp = ua.delete(url, nil, extheader)
+      if (resp.status == 200)
         return true
       else
-        raise "Could not delete #{url}: #{resp.status}"
+        fail "Could not delete #{url}: #{resp.status}"
       end
-
     end
-
   end
 end