snmp4em 0.2.1 → 0.3

data/lib/snmp4em/requests/snmp_getnext_request.rb

@@ -1,60 +1,32 @@
 module SNMP4EM
 
-  # Returned from SNMP4EM::SNMPv1.getnext(). This implements EM::Deferrable, so you can hang a callback()
-  # or errback() to retrieve the results.
+  # This implements EM::Deferrable, so you can hang a callback() or errback() to retrieve the results.
 
   class SnmpGetNextRequest < SnmpRequest
-    attr_reader :snmp_id
+    attr_accessor :snmp_id
 
     # For an SNMP-GETNEXT request, @pending_oids will be a ruby array of SNMP::ObjectNames that need to be fetched. As
     # responses come back from the agent, this array will be pruned of any error-producing OIDs. Once no errors
     # are returned, the @responses hash will be populated and returned. The values of the hash will consist of a
     # two-element array, in the form of [OID, VALUE], showing the next oid & value.
-
-    def initialize(sender, oids, args = {}) #:nodoc:
-      @sender = sender
-      
-      @timeout_timer = nil
-      @timeout_retries = @sender.retries
-      @error_retries = oids.size
-      
-      @return_raw = args[:return_raw] || false
-      
-      @responses = Hash.new
-      @pending_oids = SNMP::VarBindList.new(oids).collect{|r| r.name}
-
-      init_callbacks
-      send
-    end
     
     def handle_response(response) #:nodoc:
-      if (response.error_status == :noError)
+      if response.error_status == :noError
         # No errors, populate the @responses object so it can be returned
         response.each_varbind do |vb|
           request_oid = @pending_oids.shift
-          @responses[request_oid.to_s] = [vb.name, vb.value]
+          value = @return_raw || !vb.value.respond_to?(:rubify) ? vb.value : vb.value.rubify
+          @responses[request_oid.to_s] = [vb.name.to_s, value]
         end
-      
       else
         # Got an error, remove that oid from @pending_oids so we can try again
         error_oid = @pending_oids.delete_at(response.error_index - 1)
         @responses[error_oid.to_s] = SNMP::ResponseError.new(response.error_status)
       end
-      
-      if (@pending_oids.empty? || @error_retries.zero?)
-        until @pending_oids.empty?
-          error_oid = @pending_oids.shift
-          @responses[error_oid.to_s] = SNMP::ResponseError.new(:genErr)
-        end
 
-        @responses.each_pair do |oid, value|
-          if value.is_a? Array
-            @responses[oid][1] = value[1].rubify if (!@return_raw && value[1].respond_to?(:rubify))
-          else
-            @responses[oid] = value.rubify if (!@return_raw && value.respond_to?(:rubify))
-          end
-        end
-        
+      if @error_retries < 0
+        fail "exhausted all retries"
+      elsif @pending_oids.empty?
         # Send the @responses back to the requester, we're done!
         succeed @responses
       else
@@ -66,13 +38,13 @@ module SNMP4EM
     private
     
     def send #:nodoc:
-      # Send the contents of @pending_oids
+      Manager.track_request(self)
 
-      @snmp_id = generate_snmp_id
+      # Send the contents of @pending_oids
 
       vb_list = SNMP::VarBindList.new(@pending_oids)
       request = SNMP::GetNextRequest.new(@snmp_id, vb_list)
-      message = SNMP::Message.new(:SNMPv1, @sender.community_ro, request)
+      message = SNMP::Message.new(@sender.version, @sender.community_ro, request)
       
       super(message)
     end

data/lib/snmp4em/requests/snmp_set_request.rb

@@ -4,7 +4,7 @@ module SNMP4EM
   # or errback() to retrieve the results.
 
   class SnmpSetRequest < SnmpRequest
-    attr_reader :snmp_id
+    attr_accessor :snmp_id
 
     # For an SNMP-SET request, @pending_varbinds will by an SNMP::VarBindList, initially populated from the
     # provided oids hash. Variables can be passed as specific types from the SNMP library (i.e. SNMP::IpAddress)
@@ -13,22 +13,26 @@ module SNMP4EM
     # are produced, the @responses object is populated and returned.
 
     def initialize(sender, oids, args = {}) #:nodoc:
+      _oids = [*oids]
+
       @sender = sender
       
       @timeout_timer = nil
       @timeout_retries = @sender.retries
-      @error_retries = oids.size
+      @error_retries = _oids.size
       
       @return_raw = args[:return_raw] || false
       
       @responses = Hash.new
       @pending_varbinds = SNMP::VarBindList.new()
       
-      oids.each_pair do |oid,value|
+      _oids.each do |oid,value|
         if value.is_a? Integer
           snmp_value = SNMP::Integer.new(value)
         elsif value.is_a? String
           snmp_value = SNMP::OctetString.new(value)
+        else
+          snmp_value = value
         end
         
         @pending_varbinds << SNMP::VarBind.new(oid,snmp_value)
@@ -76,13 +80,13 @@ module SNMP4EM
     private
     
     def send
+      Manager.track_request(self)
+
       # Send the contents of @pending_varbinds
-      
-      @snmp_id = generate_snmp_id
 
       vb_list = SNMP::VarBindList.new(@pending_varbinds)
       request = SNMP::SetRequest.new(@snmp_id, vb_list)
-      message = SNMP::Message.new(:SNMPv1, @sender.community_rw, request)
+      message = SNMP::Message.new(@sender.version, @sender.community_ro, request)
       
       super(message)
     end

data/lib/snmp4em/requests/snmp_walk_request.rb

@@ -1,74 +1,47 @@
 module SNMP4EM
 
-  # Returned from SNMP4EM::SNMPv1.walk(). This implements EM::Deferrable, so you can hang a callback()
-  # or errback() to retrieve the results.
+  # This implements EM::Deferrable, so you can hang a callback() or errback() to retrieve the results.
 
   class SnmpWalkRequest < SnmpRequest
-    attr_reader :snmp_id
+    attr_accessor :snmp_id
 
-    # For an SNMP-WALK request, @pending_oids will be a ruby array of SNMP::ObjectNames that need to be walked.
-    # Note that this library supports walking multiple OIDs in parallel. Once any error-producing OIDs are removed,
-    # a series of SNMP-GETNEXT requests are sent. Each response OID is checked to see if it begins with the walk OID.
-    # If so, the incoming OID/value pair is appended to the @response hash, and will be used in subsequent GETNEXT
-    # requests. Once an OID is returned that does not begin with the walk OID, that walk OID is removed from the
-    # @pending_oids array.
-
-    def initialize(sender, oids, args = {}) #:nodoc:
-      @sender = sender
-      
-      @timeout_timer = nil
-      @timeout_retries = @sender.retries
-      @error_retries = oids.size
-      
-      @return_raw    = args[:return_raw]    || false
-      @max_results   = args[:max_results]   || nil
-      
-      @responses = Hash.new
-      @pending_oids = SNMP::VarBindList.new(oids).collect{|r| r.name}
-
-      init_callbacks
-      send
-    end
-    
+    # SNMP-WALK is faked using GETNEXT queries until the returned OID isn't a subtree of the walk OID.
+    #
+    # @next_oids is a hash that maps the base walk OID to the next OID to be queried.
+    #
+    # @query_indexes simply tracks the order in which the next_oids were packaged up, in order to
+    # determine which query left the subtree
+    #
+    # Note that this library supports walking multiple base OIDs in parallel, and that the walk fails
+    # atomically with a list of OIDS that failed to gather.
+    #
     def handle_response(response) #:nodoc:
-      oids_to_delete = []
+      if response.error_status == :noError
 
-      if (response.error_status == :noError)
         response.varbind_list.each_index do |i|
-          walk_oid = @pending_oids[i]
           response_vb = response.varbind_list[i]
-          
-          # Initialize the responses array if necessary
-          @responses[walk_oid.to_s] ||= Array.new
-          
-          # If the incoming response-oid begins with the walk-oid, then append the pairing
-          # to the @response array. Otherwise, add it to the list of oids ready to delete
-          if (response_vb.name[0,walk_oid.length] == walk_oid)
-            @responses[walk_oid.to_s] << [response_vb.name, response_vb.value]
+          response_oid = response_vb.name
+          response_walk_oid = response_oid.dup; response_walk_oid.pop
+
+          if response_walk_oid.subtree_of?(@query_indexes[i])
+            value = @return_raw || !response_vb.value.respond_to?(:rubify) ? response_vb.value : response_vb.value.rubify
+            @responses[response_walk_oid.to_s][response_oid.dup.pop] = value
+            @next_oids[response_walk_oid] = response_oid
           else
-            # If we were to delete thid oid from @pending_oids now, it would mess up the
-            # @pending_oids[i] call above.
-            oids_to_delete << walk_oid
+            @next_oids.delete(@query_indexes[i])
           end
         end
       
         @max_results -= 1 unless @max_results.nil?
-      
       else
-        error_oid = @pending_oids[response.error_index - 1]
-        oids_to_delete << error_oid
-        
-        @responses[error_oid.to_s] = SNMP::ResponseError.new(response.error_status)
+        @errors ||= []
+        error_oid = response.varbind_list[response.error_index].name
+        @errors << SNMP::ResponseError.new("Couldn't gather: #{error_oid} -> #{response.error_status}")
+        fail @errors if @error_retries < 1 
         @error_retries -= 1
       end
-      
-      oids_to_delete.each{|oid| @pending_oids.delete oid}
-      
-      if (@pending_oids.empty? || (@error_retries < 0) || (@max_results.to_i < 0))
-        @responses.each_pair do |oid, value|
-          @responses[oid] = value.rubify if (!@return_raw && value.respond_to?(:rubify))
-        end
-        
+
+      if @next_oids.empty? || @max_results.to_i < 0
         # Send the @responses back to the requester, we're done!
         succeed @responses
       else
@@ -79,24 +52,35 @@ module SNMP4EM
     private
     
     def send
-      @snmp_id = generate_snmp_id
+      Manager.track_request(self)
 
-      # This oids array will consist of all the oids that need to be getnext'd
-      oids = Array.new
-      
-      @pending_oids.each do |oid|
-        # If there's already a response for this walk-oid, then use the last returned oid, otherwise
-        # start with the walk-oid.
-        if @responses.has_key?(oid.to_s)
-          oids << @responses[oid.to_s].last.first
-        else
-          oids << oid
+      #
+      # @next_oids maps the walk oid to its next getnext oid
+      #
+      unless @next_oids
+        @responses = {}
+        @next_oids = {}
+        @pending_oids.each do |walk_oid|
+          @next_oids[walk_oid] = walk_oid
+          @responses[walk_oid.to_s] = {}
         end
       end
+      
+      #
+      # @query_indexes maps the index of the requested oid to the walk oid
+      #
+      i = 0
+      @query_indexes = {}
+      query_oids = \
+        @next_oids.collect do |walk_oid, next_oid|
+          @query_indexes[i] = walk_oid
+          i += 1
+          next_oid
+        end
 
-      vb_list = SNMP::VarBindList.new(oids)
+      vb_list = SNMP::VarBindList.new(query_oids)
       request = SNMP::GetNextRequest.new(@snmp_id, vb_list)
-      message = SNMP::Message.new(:SNMPv1, @sender.community_ro, request)
+      message = SNMP::Message.new(@sender.version, @sender.community_ro, request)
       
       super(message)
     end

data/lib/snmp4em/snmp_request.rb

@@ -1,24 +1,35 @@
 module SNMP4EM
   class SnmpRequest #:nodoc:
     include EM::Deferrable
-    
-    def generate_snmp_id
-      begin
-        snmp_id = rand(1073741823)  # Largest Fixnum
-      end until (SnmpConnection.pending_requests.select{|r| r.snmp_id == snmp_id}.empty?)        
 
-      return snmp_id
-    end
+    attr_accessor :timeout_timer
+
+    def initialize(sender, oids, args = {}) #:nodoc:
+      _oids = [*oids]
+
+      @sender = sender
+      
+      @timeout_timer = nil
+      @timeout_retries = @sender.retries
+      @error_retries = _oids.size
+      
+      @return_raw = args[:return_raw] || false
+      
+      @responses = {}
+      @pending_oids = _oids.collect { |oid_str| SNMP::ObjectId.new(oid_str) }
 
+      init_callbacks
+      send
+    end
+    
     def init_callbacks
       self.callback do
-        SnmpConnection.pending_requests.delete_if {|r| r.snmp_id == @snmp_id}
-        @timeout_timer.cancel
+        Manager.pending_requests.delete(@snmp_id)
       end
       
       self.errback do
-        SnmpConnection.pending_requests.delete_if {|r| r.snmp_id == @snmp_id}
         @timeout_timer.cancel
+        Manager.pending_requests.delete(@snmp_id)
       end
     end
 
@@ -28,13 +39,13 @@ module SNMP4EM
       @timeout_timer.cancel if @timeout_timer.is_a?(EM::Timer)
 
       @timeout_timer = EM::Timer.new(@sender.timeout) do
-        if (@timeout_retries > 0)
+        if @timeout_retries > 0
           send
           @timeout_retries -= 1
         else
-          fail("timeout")
+          fail "exhausted all timeout retries"
         end
       end
     end
   end
-end
+end

data/lib/snmp4em/snmp_v2c_requests.rb

@@ -0,0 +1,25 @@
+# The SNMP4EM library 
+
+module SNMP4EM
+  module SNMPv2cRequests
+    # Sends an SNMPv2 GET-BULK request to fetch multiple OID-value pairings simultaneously. This produces similar results to an SNMP-WALK using a single
+    # request/response transaction (SNMP-WALK is actually an inefficient series of GET-NEXTs). Multiple OIDs can be passed into the _oids_ array. Two
+    # additional parameters control how this list is processed. Setting the parameter _nonrepeaters_ to value _N_ indicates that the first _N_ OIDs will
+    # fetch a single value. This is identical to running a single GET-NEXT for the OID. Any remaining OIDs will fetch multiple values. The number of values
+    # fetched is controlled by the parameter _maxrepetitions_. The function returns a SnmpGetBulkRequest object, which implements EM::Deferrable. From there,
+    # implement a callback/errback to fetch the result. On success, the result will be a hash, mapping requested OID prefixes to the returned value.
+    # Successful fetches will be mapped to an array of two-element arrays, each of which consists of [_oid_ , _value_]. Unsuccessful fetches will be mapped to a
+    # symbol representing the error.
+    
+    # For more information, see http://tools.ietf.org/html/rfc1905#section-4.2.3
+    
+    # Optional arguments can be passed into _args_, including:
+    # *  _return_raw_ - Return objects and errors as their raw SNMP types, such as SNMP::Integer instead of native Ruby integers, SNMP::OctetString instead of native Ruby strings, etc. (default: false)
+    # *  _nonrepeaters_ - Number of OIDs passed to which exactly one result will be returned (default is 0)
+    # *  _maxrepetitions_ - Number of OID-value pairs to be returned for each OID (default is 10)
+
+    def getbulk(oids, args = {})
+      SnmpGetBulkRequest.new(self, oids, args.merge(:version => @version))
+    end
+  end
+end

data/lib/snmp4em.rb

@@ -1,15 +1,19 @@
-$:.unshift File.expand_path(File.dirname(File.expand_path(__FILE__)))
+$:.unshift File.dirname(File.expand_path(__FILE__))
+
+gem "eventmachine", ">= 0.12.10"
+gem "snmp", ">= 1.0.2"
 
 require 'eventmachine'
 require 'snmp'
-require 'snmp4em/common'
+
+require 'snmp4em/extensions'
 require 'snmp4em/handler'
-require 'snmp4em/snmp_connection'
-require 'snmp4em/snmp_v1'
-require 'snmp4em/snmp_v2'
+require 'snmp4em/common_requests'
+require 'snmp4em/manager'
+require 'snmp4em/snmp_v2c_requests'
 require 'snmp4em/snmp_request'
 require 'snmp4em/requests/snmp_get_request'
 require 'snmp4em/requests/snmp_getbulk_request'
 require 'snmp4em/requests/snmp_getnext_request'
 require 'snmp4em/requests/snmp_set_request'
-require 'snmp4em/requests/snmp_walk_request'
+require 'snmp4em/requests/snmp_walk_request'

data/snmp4em.gemspec

@@ -1,30 +1,23 @@
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
-  s.name = %q{snmp4em}
-  s.version = "0.2.1"
+  s.name = "snmp4em"
+  s.version = "0.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Norman Elton"]
-  s.date = %q{2010-05-17}
-  s.description = %q{A high-performance SNMP engine built on EventMachine and Ruby-SNMP, supporting SNMPv1 and SNMPv2 operations}
-  s.email = %q{normelton@gmail.com}
-  s.extra_rdoc_files = ["README"]
-  s.files = ["lib/snmp4em.rb", "lib/snmp4em/common.rb", "lib/snmp4em/handler.rb", "lib/snmp4em/requests/snmp_get_request.rb", "lib/snmp4em/requests/snmp_getbulk_request.rb", "lib/snmp4em/requests/snmp_getnext_request.rb", "lib/snmp4em/requests/snmp_set_request.rb", "lib/snmp4em/requests/snmp_walk_request.rb", "lib/snmp4em/snmp_request.rb", "lib/snmp4em/snmp_connection.rb", "lib/snmp4em/snmp_v1.rb", "lib/snmp4em/snmp_v2.rb", "snmp4em.gemspec", "Manifest"]
-  s.homepage = %q{http://github.com/normelton/snmp4em}
-  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Snmp4em", "--main", "README"]
+  s.date = "2012-02-23"
+  s.description = "A high-performance SNMP engine built on EventMachine and Ruby-SNMP"
+  s.email = "normelton@gmail.com"
+  s.extra_rdoc_files = ["README.rdoc"]
+  s.files = ["Gemfile", "README.rdoc", "Rakefile", "lib/snmp4em.rb", "lib/snmp4em/common_requests.rb", "lib/snmp4em/extensions.rb", "lib/snmp4em/extensions/snmp/integer.rb", "lib/snmp4em/extensions/snmp/ip_address.rb", "lib/snmp4em/extensions/snmp/null.rb", "lib/snmp4em/extensions/snmp/object_id.rb", "lib/snmp4em/extensions/snmp/octet_string.rb", "lib/snmp4em/extensions/snmp/response_error.rb", "lib/snmp4em/handler.rb", "lib/snmp4em/manager.rb", "lib/snmp4em/requests/snmp_get_request.rb", "lib/snmp4em/requests/snmp_getbulk_request.rb", "lib/snmp4em/requests/snmp_getnext_request.rb", "lib/snmp4em/requests/snmp_set_request.rb", "lib/snmp4em/requests/snmp_walk_request.rb", "lib/snmp4em/snmp_request.rb", "lib/snmp4em/snmp_v2c_requests.rb", "snmp4em.gemspec", "spec/models/test_message.rb", "spec/models/test_request.rb", "spec/models/test_response.rb", "spec/spec.opts", "spec/spec_helper.rb", "spec/unit/handler_spec.rb", "spec/unit/manager_spec.rb", "Manifest"]
+  s.homepage = "http://github.com/normelton/snmp4em"
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Snmp4em", "--main", "README.rdoc"]
   s.require_paths = ["lib"]
-  s.rubyforge_project = %q{snmp4em}
-  s.rubygems_version = %q{1.3.6}
-  s.summary = %q{A high-performance SNMP engine built on EventMachine and Ruby-SNMP}
-
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
-
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-    else
-    end
-  else
-  end
+  s.rubyforge_project = "snmp4em"
+  s.rubygems_version = "1.8.16"
+  s.summary = "A high-performance SNMP engine built on EventMachine and Ruby-SNMP"
+  s.add_runtime_dependency 'snmp', '>= 1.0.2'
+  s.add_runtime_dependency 'eventmachine', '>= 1.0.0'
+  
 end

data/spec/models/test_message.rb

@@ -0,0 +1,7 @@
+module SNMP4EM
+  class TestMessage
+
+    attr_accessor :pdu
+
+  end
+end

data/spec/models/test_request.rb

@@ -0,0 +1,10 @@
+module SNMP4EM
+  class TestRequest
+
+    attr_accessor :snmp_id
+
+    def handle_response(response)
+    end
+
+  end
+end

data/spec/models/test_response.rb

@@ -0,0 +1,7 @@
+module SNMP4EM
+  class TestResponse
+
+    attr_accessor :request_id
+
+  end
+end

data/spec/spec.opts

@@ -0,0 +1,3 @@
+--colour
+--format nested
+--drb

data/spec/spec_helper.rb

@@ -0,0 +1,18 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
+
+MODELS = File.join(File.dirname(__FILE__), "models")
+$LOAD_PATH.unshift(MODELS)
+Dir[ File.join(MODELS, "*.rb") ].sort.each { |file| require File.basename(file) }
+
+require 'rubygems'
+require "spec"
+require "snmp4em"
+
+def em
+  EM.run {
+    yield
+    EM.stop
+  }
+end
+

data/spec/unit/handler_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+
+describe SNMP4EM::Handler do
+
+  before do
+    SNMP4EM::Manager.class_eval do
+      @pending_requests = {}
+    end
+  end
+
+  describe "#receive_data" do
+
+    it "should match responses to requests" do
+      em do
+        response = SNMP4EM::TestResponse.new
+        response.request_id = 1
+
+        message = SNMP4EM::TestMessage.new
+        message.pdu = response
+        SNMP::Message.should_receive(:decode).and_return(message)
+
+        request = SNMP4EM::TestRequest.new
+        SNMP4EM::Manager.should_receive(:rand).and_return(1)
+        SNMP4EM::Manager.track_request(request)
+
+        request.should_receive(:handle_response).with(response)
+        SNMP4EM::Handler.new(nil).receive_data(nil)
+      end
+
+    end
+
+  end
+
+end

data/spec/unit/manager_spec.rb

@@ -0,0 +1,82 @@
+require 'spec_helper'
+
+describe SNMP4EM::Manager do
+
+  before do
+    SNMP4EM::Manager.class_eval do
+      @pending_requests = {}
+    end
+  end
+
+  describe "#track_request" do
+
+    it "should assign a random and unique id to each request" do
+      em do
+        request = SNMP4EM::TestRequest.new
+        other_request = SNMP4EM::TestRequest.new
+
+        SNMP4EM::Manager.should_receive(:rand).and_return(1, 1, 2)
+        SNMP4EM::Manager.track_request(request)
+        SNMP4EM::Manager.track_request(other_request)
+
+        request.snmp_id.should == 1
+        other_request.snmp_id.should == 2
+      end
+    end
+
+    it "should prune requests when their request id changes" do
+      em do
+        request = SNMP4EM::TestRequest.new
+
+        SNMP4EM::Manager.should_receive(:rand).and_return(1, 2)
+        SNMP4EM::Manager.track_request(request)
+        request.snmp_id.should == 1
+        SNMP4EM::Manager.pending_requests.size.should == 1
+
+        SNMP4EM::Manager.track_request(request)
+        request.snmp_id.should == 2
+        SNMP4EM::Manager.pending_requests.size.should == 1
+      end
+    end
+
+  end
+
+  describe "#initialize" do
+
+    it "should default to v2c" do
+      em do
+        SNMP4EM::Manager.new.version.should == :SNMPv2c
+      end
+    end
+
+    it "should create the class' UDP socket" do
+      em do
+        SNMP4EM::Manager.new
+        SNMP4EM::Manager.socket.should be_a EventMachine::Connection
+      end
+    end
+
+
+    context "when using v2c" do
+
+      it "should acquire the #getbulk method" do
+        em do
+          SNMP4EM::Manager.new.methods.should include :getbulk
+        end
+      end
+
+    end
+
+    context "when using v1" do
+
+      it "should not acquire the #getbulk method" do
+        em do
+          SNMP4EM::Manager.new(:version => :SNMPv1).methods.should_not include :getbulk
+        end
+      end
+
+    end
+
+  end
+
+end