snmp4em 0.2.1 → 0.3

data/Gemfile

@@ -0,0 +1,7 @@
+# Use `bundle install` in order to install these gems
+# Use `bundle exec rake` in order to run the specs using the bundle
+
+gem "eventmachine", "0.12.10"
+gem "snmp", ">= 1.0.2"
+
+gem "rspec", "1.3.0"

data/Manifest

@@ -1,16 +1,29 @@
-README
+Gemfile
+README.rdoc
 Rakefile
 lib/snmp4em.rb
-lib/snmp4em/common.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_connection.rb
 lib/snmp4em/snmp_request.rb
-lib/snmp4em/snmp_v1.rb
-lib/snmp4em/snmp_v2.rb
-snmp4em.gemspec
+lib/snmp4em/snmp_v2c_requests.rb
+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

data/{README → README.rdoc}

@@ -2,12 +2,12 @@
 
 == Summary
 
-This library extends the Ruby-SNMP[http://snmplib.rubyforge.org] to use the asynchronous EventMachine[http://rubyeventmachine.com] library for added performance and scalability. This allows code to scale monitoring applications to access a very high number of devices without the need for complex asynchronous I/O handling.
+This gem extends Ruby-SNMP[http://snmplib.rubyforge.org] to use the asynchronous EventMachine[http://rubyeventmachine.com] library for added performance and scalability. This allows code to scale monitoring applications to access a very high number of devices without the need for complex asynchronous I/O handling.
 
 
 == Features
 
-The initial version 0.1.0 of this software supports:
+Version 0.2.1 supports:
 
 * SNMP v1 and v2 only
 * SNMP Get, GetNext, GetBulk (v2 only), Set, and Walk requests.
@@ -38,27 +38,27 @@ A few definitions:
 
 A simple SNMP-GET:
 
-  EM::run do
-	  snmp = SNMP4EM::SNMPv1.new(:host => "192.168.1.1")
+  EM.run {
+    snmp = SNMP4EM::Manager.new(:host => "192.168.1.1", :version => :SNMPv1)
   
-	  request = snmp.get([OID_SYSNAME, OID_SYSLOCATION])
+    request = snmp.get([OID_SYSNAME, OID_SYSLOCATION])
   
-	  request.callback do |response|
-	    puts "System name = #{response[OID_SYSNAME]}"
-	    puts "System location = #{response[OID_SYSLOCATION]}"
-	  end
+    request.callback do |response|
+      puts "System name = #{response[OID_SYSNAME]}"
+      puts "System location = #{response[OID_SYSLOCATION]}"
+    end
   
-	  request.errback do |error|
-	    puts "GET got error #{error}"
-	  end
-	end
+    request.errback do |error|
+      puts "GET got error #{error}"
+    end
+  }
 
 A simple SNMP-GETNEXT:
 
-  EM::run do
-    snmp = SNMP4EM::SNMPv1.new(:host => "192.168.1.1")
+  EM.run {
+    snmp = SNMP4EM::Manager.new(:host => "192.168.1.1")
 
-    request = snmp.getnext([OID_SYSNAME])
+    request = snmp.getnext(OID_SYSNAME)
 
     request.callback do |response|
       r = response[OID_SYSNAME]
@@ -66,14 +66,14 @@ A simple SNMP-GETNEXT:
     end
 
     request.errback do |error|
-      puts "GET got error #{error}"
+      puts "GETNEXT got error #{error}"
     end
-  end
+  }
 
 A simple SNMP-SET:
 
-  EM::run do
-    snmp = SNMP4EM::SNMPv1.new(:host => "192.168.1.1")
+  EM.run {
+    snmp = SNMP4EM::Manager.new(:host => "192.168.1.1")
 
     request = snmp.set({OID_SYSNAME => "My System Name", OID_SYSLOCATION => "My System Location"})
 
@@ -92,16 +92,16 @@ A simple SNMP-SET:
     end
 
     request.errback do |error|
-      puts "GET got error #{error}"
+      puts "SET got error #{error}"
     end
-  end
+  }
 
 A simple SNMP-WALK:
 
-  EM::run do
-    snmp = SNMP4EM::SNMPv1.new(:host => "192.168.1.1")
+  EM.run {
+    snmp = SNMP4EM::Manager.new(:host => "192.168.1.1")
 
-    request = snmp.walk([OID_SYSTEM])
+    request = snmp.walk(OID_SYSTEM)
 
     request.callback do |response|
       if (response[OID_SYSTEM].is_a? Array)
@@ -114,16 +114,16 @@ A simple SNMP-WALK:
     end
 
     request.errback do |error|
-      puts "GET got error #{error}"
+      puts "WALK got error #{error}"
     end
-  end
+  }
 
 A simple SNMP-GET-BULK:
 
-  EM::run do
-    snmp = SNMP4EM::SNMPv2.new(:host => "192.168.1.1")
+  EM.run {
+    snmp = SNMP4EM::Manager.new(:host => "192.168.1.1")
 
-    request = snmp.getbulk([OID_SYSTEM])
+    request = snmp.getbulk(OID_SYSTEM)
 
     request.callback do |response|
       if (response[OID_SYSTEM].is_a? Array)
@@ -136,21 +136,24 @@ A simple SNMP-GET-BULK:
     end
 
     request.errback do |error|
-      puts "GET got error #{error}"
+      puts "GET-BULK got error #{error}"
     end
-  end
+  }
 
 == Change Log
 
-Version 0.1.0:
+Version 0.2.1:
 
-* Initial deployment, ability to run get/getnext/set/walk requests in parallel
+* Code cleanups, speed boosts
 
 Version 0.2.0:
 
 * Added support for SNMPv2, including GET-BULK operations
 
-== Developer Contact Information
+Version 0.1.0:
+
+* Initial deployment, ability to run get/getnext/set/walk requests in parallel
+
+== Credits
 
-Norman Elton
-normelton@gmail.com
+Author: Norman Elton  normelton@gmail.com

data/Rakefile

@@ -0,0 +1,17 @@
+require "rubygems"
+require "rake"
+require "echoe"
+
+gem "rspec", "1.3.0"
+
+require "spec/rake/spectask"
+
+Echoe.new("snmp4em", "0.2.1") do |p|
+  p.description              = "A high-performance SNMP engine built on EventMachine and Ruby-SNMP"
+  p.url                      = "http://github.com/normelton/snmp4em"
+  p.author                   = "Norman Elton"
+  p.email                    = "normelton@gmail.com"
+  p.development_dependencies = []
+  p.rdoc_pattern             = ["lib", "README.rdoc"]
+  p.dependencies             = ["snmp"]
+end

data/lib/snmp4em/{snmp_v1.rb → common_requests.rb}

@@ -1,25 +1,7 @@
 # The SNMP4EM library 
 
 module SNMP4EM
-  class SNMPv1 < SnmpConnection
-    attr_reader :community_ro, :community_rw
-    
-    # Creates a new object to communicate with SNMPv1 agents. Optionally pass in the following parameters:
-    # *  _host_ - IP/hostname of remote agent (default: 127.0.0.1)
-    # *  _port_ - UDP port on remote agent (default: 161)
-    # *  _community_ - Community string to use (default: public)
-    # *  _community_ro_ - Read-only community string to use for get/getnext/walk operations (default: public)
-    # *  _community_rw_ - Read-write community string to use for set operations (default: public)
-    # *  _timeout_ - Number of seconds to wait before a request times out (default: 1)
-    # *  _retries_ - Number of retries before failing (default: 3)
-    
-    def initialize(args = {})
-      super(args)
-      
-      @community_ro = args[:community_ro] || args[:community] || "public"
-      @community_rw = args[:community_rw] || args[:community] || "public"
-    end
-    
+  module CommonRequests
     # Sends an SNMP-GET request to the remote agent for all OIDs specified in the _oids_ array. Returns a SnmpGetRequest 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 values to results.
@@ -28,9 +10,7 @@ module SNMP4EM
     # *  _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)
  
     def get(oids, args = {})
-      request = SnmpGetRequest.new(self, oids, args.merge(:version => :SNMPv1))
-      SnmpConnection.pending_requests << request
-      return request
+      SnmpGetRequest.new(self, oids, args.merge(:version => @version))
     end
 
     # Sends an SNMP-GETNEXT request to the remote agent for all OIDs specified in the _oids_ array. Returns a SnmpGetRequest object,
@@ -42,9 +22,7 @@ module SNMP4EM
     # *  _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)
 
     def getnext(oids, args = {})
-      request = SnmpGetNextRequest.new(self, oids, args.merge(:version => :SNMPv1))
-      SnmpConnection.pending_requests << request
-      return request
+      SnmpGetNextRequest.new(self, oids, args.merge(:version => @version))
     end
 
     # Sends an SNMP-SET request to the remote agent for all OIDs specified in the _oids_ hash. The hash must map OID values to requested
@@ -57,9 +35,7 @@ module SNMP4EM
     # *  _return_raw_ - Return error objects as SNMP::ResponseError instead of a symbol
 
     def set(oids, args = {})
-      request = SnmpSetRequest.new(self, oids, args.merge(:version => :SNMPv1))
-      SnmpConnection.pending_requests << request
-      return request
+      SnmpSetRequest.new(self, oids, args.merge(:version => @version))
     end
 
     # Sends a series of SNMP-GETNEXT requests to simulate an SNMP "walk" operation. Given an OID prefix, the library will keep requesting the
@@ -74,9 +50,7 @@ module SNMP4EM
     # *  _max_results_ - Maximum number of results to be returned for any single OID prefix (default: nil = unlimited)
 
     def walk(oids, args = {})
-      request = SnmpWalkRequest.new(self, oids, args.merge(:version => :SNMPv1))
-      SnmpConnection.pending_requests << request
-      return request
+      SnmpWalkRequest.new(self, oids, args.merge(:version => @version))
     end
   end
-end
+end

data/lib/snmp4em/extensions/snmp/integer.rb

@@ -0,0 +1,7 @@
+module SNMP #:nodoc:
+
+  class Integer #:nodoc:
+    alias :rubify :to_i
+  end
+
+end

data/lib/snmp4em/extensions/snmp/ip_address.rb

@@ -0,0 +1,7 @@
+module SNMP #:nodoc:
+
+  class IpAddress #:nodoc:
+    alias :rubify :to_s
+  end
+
+end

data/lib/snmp4em/extensions/snmp/null.rb

@@ -0,0 +1,11 @@
+module SNMP #:nodoc:
+
+  class Null #:nodoc:
+    class << self
+      def rubify
+        nil
+      end
+    end
+  end
+
+end

data/lib/snmp4em/extensions/snmp/object_id.rb

@@ -0,0 +1,7 @@
+module SNMP #:nodoc:
+
+  class ObjectId #:nodoc:
+    alias :rubify :to_s
+  end
+
+end

data/lib/snmp4em/extensions/snmp/octet_string.rb

@@ -0,0 +1,7 @@
+module SNMP #:nodoc:
+
+  class OctetString #:nodoc:
+    alias :rubify :to_s
+  end
+
+end

data/lib/snmp4em/extensions/snmp/response_error.rb

@@ -0,0 +1,17 @@
+module SNMP #:nodoc:
+
+  class ResponseError
+    attr_reader :error_status
+    alias :rubify :error_status #:nodoc:
+    
+    def initialize(error_status) #:nodoc:
+      @error_status = error_status
+    end
+    
+    # String representation of this error
+    def to_s
+      @error_status.to_s
+    end
+  end
+
+end

data/lib/snmp4em/extensions.rb

@@ -0,0 +1,6 @@
+require "snmp4em/extensions/snmp/integer.rb"
+require "snmp4em/extensions/snmp/ip_address.rb"
+require "snmp4em/extensions/snmp/null.rb"
+require "snmp4em/extensions/snmp/object_id.rb"
+require "snmp4em/extensions/snmp/octet_string.rb"
+require "snmp4em/extensions/snmp/response_error.rb"

data/lib/snmp4em/handler.rb

@@ -1,18 +1,27 @@
 module SNMP4EM
-  module Handler #:nodoc:
+  class Handler < EventMachine::Connection #:nodoc:
     def receive_data(data)
       begin
         message = SNMP::Message.decode(data)
       rescue Exception => err
+        # the request that this malformed response corresponds to
+        # will timeout and retry
         return
       end
       
       response = message.pdu
-      request_id = response.request_id
-      
-      if (request = SnmpConnection.pending_requests.select{|r| r.snmp_id == request_id}.first)
+      request = Manager.pending_requests[response.request_id]
+
+      #
+      # in the event of a timeout retry, the request will have been 
+      # pruned from the Manager, so the response is to an expired
+      # request, ignore it.
+      #
+
+      if request
+        request.timeout_timer.cancel
         request.handle_response(response)
       end
     end
   end
-end
+end

data/lib/snmp4em/manager.rb

@@ -0,0 +1,69 @@
+# The SNMP4EM library 
+
+module SNMP4EM
+  class Manager
+    include SNMP4EM::CommonRequests
+
+    #
+    # @pending_requests maps a request's id to its SnmpRequest
+    #
+    @pending_requests = {}
+    @socket = nil
+    
+    class << self
+      attr_reader :pending_requests
+      attr_reader :socket
+      
+      def init_socket #:nodoc:
+        # When the socket is in error state, close the socket and re-open a new one.
+        if !@socket.nil? && @socket.error?
+                @socket.close_connection
+                @socket = nil
+        end
+
+        @socket ||= EM::open_datagram_socket("0.0.0.0", 0, Handler)
+      end
+
+      def track_request(request)
+        @pending_requests.delete(request.snmp_id)
+
+        begin
+          request.snmp_id = rand(2**31)  # Largest SNMP Signed INTEGER
+        end while @pending_requests[request.snmp_id]
+
+        @pending_requests[request.snmp_id] = request
+      end
+    end
+    
+    attr_reader :host, :port, :timeout, :retries, :version, :community_ro, :community_rw
+    
+    # Creates a new object to communicate with SNMPv1 agents. Optionally pass in the following parameters:
+    # *  _host_ - IP/hostname of remote agent (default: 127.0.0.1)
+    # *  _port_ - UDP port on remote agent (default: 161)
+    # *  _community_ - Community string to use (default: public)
+    # *  _community_ro_ - Read-only community string to use for get/getnext/walk operations (default: public)
+    # *  _community_rw_ - Read-write community string to use for set operations (default: public)
+    # *  _timeout_ - Number of seconds to wait before a request times out (default: 1)
+    # *  _retries_ - Number of retries before failing (default: 3)
+    
+    def initialize(args = {})
+      @host    = args[:host]    || "127.0.0.1"
+      @port    = args[:port]    || 161
+      @timeout = args[:timeout] || 1
+      @retries = args[:retries] || 3
+      @version = args[:version] || :SNMPv2c
+
+      self.extend SNMPv2cRequests if @version == :SNMPv2c
+
+      @community_ro = args[:community_ro] || args[:community] || "public"
+      @community_rw = args[:community_rw] || args[:community] || "public"
+      
+      self.class.init_socket
+    end
+    
+    def send(message) #:nodoc:
+      self.class.socket.send_datagram message.encode, @host, @port
+    end
+
+  end
+end

data/lib/snmp4em/requests/snmp_get_request.rb

@@ -1,38 +1,22 @@
 module SNMP4EM
   
-  # Returned from SNMP4EM::SNMPv1.get(). 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 SnmpGetRequest < SnmpRequest
-    attr_reader :snmp_id
+    attr_accessor :snmp_id
 
     # For an SNMP-GET 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.
 
-    def initialize(sender, oids, args = {}) #:nodoc:
-      @sender = sender
-      
-      @timeout_timer = nil
-      @timeout_retries = @sender.retries
-      @error_retries = oids.size
-      
-      @version = args[:version] || :SNMPv1
-      @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.value
+          value = @return_raw || !vb.value.respond_to?(:rubify) ? vb.value : vb.value.rubify
+
+          @responses[request_oid.to_s] = value
         end
       
       else
@@ -40,17 +24,10 @@ module SNMP4EM
         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|
-          @responses[oid] = value.rubify if (!@return_raw && value.respond_to?(:rubify))
-        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
@@ -62,13 +39,13 @@ module SNMP4EM
     private
 
     def send
-      # 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::GetRequest.new(@snmp_id, vb_list)
-      message = SNMP::Message.new(@version, @sender.community_ro, request)
+      message = SNMP::Message.new(@sender.version, @sender.community_ro, request)
 
       super(message)
     end

data/lib/snmp4em/requests/snmp_getbulk_request.rb

@@ -1,37 +1,23 @@
 module SNMP4EM
   
-  # Returned from SNMP4EM::SNMPv1.get(). 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 SnmpGetBulkRequest < SnmpRequest
-    attr_reader :snmp_id
+    attr_accessor :snmp_id
 
     # For an SNMP-GETBULK 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.
 
     def initialize(sender, oids, args = {}) #:nodoc:
-      @sender = sender
-      
-      @timeout_timer = nil
-      @timeout_retries = @sender.retries
-      @error_retries = oids.size
-      
-      @version = args[:version] || :SNMPv2c
-      @return_raw = args[:return_raw] || false
-      
       @nonrepeaters = args[:nonrepeaters] || 0
       @maxrepetitions = args[:maxrepetitions] || 10
       
-      @responses = Hash.new
-      @pending_oids = SNMP::VarBindList.new(oids).collect{|r| r.name}
-
-      init_callbacks
-      send
+      super
     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
 
         @nonrepeaters.times do |i|
@@ -85,9 +71,9 @@ module SNMP4EM
     private
 
     def send
-      # 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::GetBulkRequest.new(@snmp_id, vb_list)
@@ -95,7 +81,7 @@ module SNMP4EM
       request.max_repetitions = @maxrepetitions
       request.non_repeaters = @nonrepeaters
       
-      message = SNMP::Message.new(@version, @sender.community_ro, request)
+      message = SNMP::Message.new(@sender.version, @sender.community_ro, request)
 
       super(message)
     end