net-ldap 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1e84cd86cc0974d9380b18caa917cfa8d8f3e8f2
-  data.tar.gz: 6e6783c3b458b1c5b3abd72745a0e56b4e749d35
+  metadata.gz: 487807bc08da7baeb4941090020468a8e60fe14a
+  data.tar.gz: 047ccb6638a81c96eb1bfca1a684726a71bfc1a8
 SHA512:
-  metadata.gz: 5c3b405a5086b6f33522fe611cff02ca6e325498db1b54b9d4415222c870eedae5466a3e9c65ba9d16cfc6db89392eafbbcee4537a0b70a79a6651a92695e9d6
-  data.tar.gz: 81ce6fa1369f1a5bcbacd35efc939a8f9aa97ada21ef122314c029b9c0b3a32d6dddb8c9b43a3d2cf25d9fffad7d2fe97b992cd92c5597f8b26b72ceeacf1dc1
+  metadata.gz: 6d02d5a7af488a5f7ee8b8050c5d281d6e76b7c40baeb1a1275a18b103d2f76cf0fea8dfa865efe2ce243d92b87c3d6abdfa1b47615cf95fb5cd5e9b9806e70a
+  data.tar.gz: 380cc5961a9a85a1d196203b6712061b5c8b8a4c1008dcfcee67556029269e264d2d7463e2e98572c06020dbae44dbb8ace34f06d584d33a9f1b5f6169f90d9d

data/.travis.yml

@@ -4,4 +4,7 @@ rvm:
   - 2.0.0
   - jruby-19mode
   - rbx-19mode
+matrix:
+  allow_failures:
+    - rvm: jruby-19mode
 script: bundle exec rake spec

data/Hacking.rdoc

@@ -25,7 +25,7 @@ patches being accepted, we recommend that you follow the guidelines below:
 
 == Documentation
 
-* Documentation: {net-ldap}[http://net-ldap.rubyforge.org/]
+* Documentation: {net-ldap}[http://rubydoc.info/gems/net-ldap]
 
 It is very important that, if you add new methods or objects, your code is
 well-documented. The purpose of the changes should be clearly described so that
@@ -63,6 +63,5 @@ installed using RubyGems.
 
 == Participation
 
-* RubyForge: {net-ldap}[http://rubyforge.org/projects/net-ldap]
 * GitHub: {ruby-ldap/ruby-net-ldap}[https://github.com/ruby-ldap/ruby-net-ldap/]
 * Group: {ruby-ldap}[http://groups.google.com/group/ruby-ldap]

data/Manifest.txt

@@ -25,6 +25,7 @@ lib/net/ldap/dataset.rb
 lib/net/ldap/dn.rb
 lib/net/ldap/entry.rb
 lib/net/ldap/filter.rb
+lib/net/ldap/instrumentation.rb
 lib/net/ldap/password.rb
 lib/net/ldap/pdu.rb
 lib/net/ldap/version.rb

data/README.rdoc

@@ -1,4 +1,4 @@
-= Net::LDAP for Ruby {<img src="https://travis-ci.org/ruby-ldap/ruby-net-ldap.png" />}[https://travis-ci.org/ruby-ldap/ruby-net-ldap]
+= Net::LDAP for Ruby {<img src="https://travis-ci.org/github/ruby-net-ldap.png" />}[https://travis-ci.org/github/ruby-net-ldap]
 
 == Description
 

data/lib/net/ber/ber_parser.rb

@@ -148,6 +148,9 @@ module Net::BER::BERParser
   # implemented on the including object and that it returns a Fixnum value.
   # Also requires #read(bytes) to work.
   #
+  # Yields the object type `id` and the data `content_length` if a block is
+  # given. This is namely to support instrumentation.
+  #
   # This does not work with non-blocking I/O.
   def read_ber(syntax = nil)
     # TODO: clean this up so it works properly with partial packets coming
@@ -157,6 +160,8 @@ module Net::BER::BERParser
     id = getbyte or return nil  # don't trash this value, we'll use it later
     content_length = read_ber_length
 
+    yield id, content_length if block_given?
+
     if -1 == content_length
       raise Net::BER::BerError, "Indeterminite BER content length not implemented."
     else

data/lib/net/ldap.rb

@@ -23,6 +23,7 @@ require 'net/ldap/filter'
 require 'net/ldap/dataset'
 require 'net/ldap/password'
 require 'net/ldap/entry'
+require 'net/ldap/instrumentation'
 require 'net/ldap/version'
 
 # == Quick-start for the Impatient
@@ -242,6 +243,7 @@ require 'net/ldap/version'
 # and then keeps it open while it executes a user-supplied block.
 # Net::LDAP#open closes the connection on completion of the block.
 class Net::LDAP
+  include Net::LDAP::Instrumentation
 
   class LdapError < StandardError; end
 
@@ -256,7 +258,7 @@ class Net::LDAP
   DerefAliases_Find = 2
   DerefAliases_Always = 3
   DerefAliasesArray = [ DerefAliases_Never, DerefAliases_Search, DerefAliases_Find, DerefAliases_Always ]
-  
+
   primitive = { 2 => :null } # UnbindRequest body
   constructed = {
     0 => :array, # BindRequest
@@ -383,6 +385,8 @@ class Net::LDAP
   #   #encryption for details.
   # * :force_no_page => Set to true to prevent paged results even if your
   #   server says it supports them. This is a fix for MS Active Directory
+  # * :instrumentation_service => An object responsible for instrumenting
+  #   operations, compatible with ActiveSupport::Notifications' public API.
   #
   # Instantiating a Net::LDAP object does <i>not</i> result in network
   # traffic to the LDAP server. It simply stores the connection and binding
@@ -400,6 +404,8 @@ class Net::LDAP
       @auth[:password] = pr.call
     end
 
+    @instrumentation_service = args[:instrumentation_service]
+
     # This variable is only set when we are created with LDAP::open. All of
     # our internal methods will connect using it, or else they will create
     # their own.
@@ -571,16 +577,21 @@ class Net::LDAP
     # all generate auth failures if the bind was unsuccessful.
     raise Net::LDAP::LdapError, "Open already in progress" if @open_connection
 
-    begin
-      @open_connection = Net::LDAP::Connection.new(:host => @host,
-                                                   :port => @port,
-                                                   :encryption =>
-                                                   @encryption)
-      @open_connection.bind(@auth)
-      yield self
-    ensure
-      @open_connection.close if @open_connection
-      @open_connection = nil
+    instrument "open.net_ldap" do |payload|
+      begin
+        @open_connection =
+          Net::LDAP::Connection.new \
+            :host                    => @host,
+            :port                    => @port,
+            :encryption              => @encryption,
+            :instrumentation_service => @instrumentation_service
+        payload[:connection] = @open_connection
+        payload[:bind]       = @open_connection.bind(@auth)
+        yield self
+      ensure
+        @open_connection.close if @open_connection
+        @open_connection = nil
+      end
     end
   end
 
@@ -641,30 +652,35 @@ class Net::LDAP
     return_result_set = args[:return_result] != false
     result_set = return_result_set ? [] : nil
 
-    if @open_connection
-      @result = @open_connection.search(args) { |entry|
-        result_set << entry if result_set
-        yield entry if block_given?
-      }
-    else
-      begin
-        conn = Net::LDAP::Connection.new(:host => @host, :port => @port,
-                                         :encryption => @encryption)
-        if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
-          @result = conn.search(args) { |entry|
-            result_set << entry if result_set
-            yield entry if block_given?
-          }
+    instrument "search.net_ldap", args do |payload|
+      if @open_connection
+        @result = @open_connection.search(args) { |entry|
+          result_set << entry if result_set
+          yield entry if block_given?
+        }
+      else
+        begin
+          conn = Net::LDAP::Connection.new \
+            :host                    => @host,
+            :port                    => @port,
+            :encryption              => @encryption,
+            :instrumentation_service => @instrumentation_service
+          if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
+            @result = conn.search(args) { |entry|
+              result_set << entry if result_set
+              yield entry if block_given?
+            }
+          end
+        ensure
+          conn.close if conn
         end
-      ensure
-        conn.close if conn
       end
-    end
 
-    if return_result_set
-      (!@result.nil? && @result.result_code == 0) ? result_set : nil
-    else
-      @result.success?
+      if return_result_set
+        (!@result.nil? && @result.result_code == 0) ? result_set : nil
+      else
+        @result.success?
+      end
     end
   end
 
@@ -726,19 +742,26 @@ class Net::LDAP
   # the documentation for #auth, the password parameter can be a Ruby Proc
   # instead of a String.
   def bind(auth = @auth)
-    if @open_connection
-      @result = @open_connection.bind(auth)
-    else
-      begin
-        conn = Connection.new(:host => @host, :port => @port,
-                              :encryption => @encryption)
-        @result = conn.bind(auth)
-      ensure
-        conn.close if conn
+    instrument "bind.net_ldap" do |payload|
+      if @open_connection
+        payload[:connection] = @open_connection
+        payload[:bind]       = @result = @open_connection.bind(auth)
+      else
+        begin
+          conn = Connection.new \
+            :host                    => @host,
+            :port                    => @port,
+            :encryption              => @encryption,
+            :instrumentation_service => @instrumentation_service
+          payload[:connection] = conn
+          payload[:bind]       = @result = conn.bind(auth)
+        ensure
+          conn.close if conn
+        end
       end
-    end
 
-    @result.success?
+      @result.success?
+    end
   end
 
   # #bind_as is for testing authentication credentials.
@@ -826,21 +849,26 @@ class Net::LDAP
   #    ldap.add(:dn => dn, :attributes => attr)
   #  end
   def add(args)
-    if @open_connection
-      @result = @open_connection.add(args)
-    else
-      @result = 0
-      begin
-        conn = Connection.new(:host => @host, :port => @port,
-                              :encryption => @encryption)
-        if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
-          @result = conn.add(args)
+    instrument "add.net_ldap", args do |payload|
+      if @open_connection
+        @result = @open_connection.add(args)
+      else
+        @result = 0
+        begin
+          conn = Connection.new \
+            :host                    => @host,
+            :port                    => @port,
+            :encryption              => @encryption,
+            :instrumentation_service => @instrumentation_service
+          if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
+            @result = conn.add(args)
+          end
+        ensure
+          conn.close if conn
         end
-      ensure
-        conn.close if conn
       end
+      @result.success?
     end
-    @result.success?
   end
 
   # Modifies the attribute values of a particular entry on the LDAP
@@ -858,7 +886,7 @@ class Net::LDAP
   # The LDAP protocol provides a full and well thought-out set of operations
   # for changing the values of attributes, but they are necessarily somewhat
   # complex and not always intuitive. If these instructions are confusing or
-  # incomplete, please send us email or create a bug report on rubyforge.
+  # incomplete, please send us email or create an issue on GitHub.
   #
   # The :operations parameter to #modify takes an array of
   # operation-descriptors. Each individual operation is specified in one
@@ -924,22 +952,27 @@ class Net::LDAP
   # simultaneously by the server. It bears repeating that this concurrency
   # does _not_ imply transactional atomicity, which LDAP does not provide.
   def modify(args)
-    if @open_connection
-      @result = @open_connection.modify(args)
-    else
-      @result = 0
-      begin
-        conn = Connection.new(:host => @host, :port => @port,
-                              :encryption => @encryption)
-        if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
-          @result = conn.modify(args)
+    instrument "modify.net_ldap", args do |payload|
+      if @open_connection
+        @result = @open_connection.modify(args)
+      else
+        @result = 0
+        begin
+          conn = Connection.new \
+            :host                    => @host,
+            :port                    => @port,
+            :encryption              => @encryption,
+            :instrumentation_service => @instrumentation_service
+          if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
+            @result = conn.modify(args)
+          end
+        ensure
+          conn.close if conn
         end
-      ensure
-        conn.close if conn
       end
-    end
 
-    @result.success?
+      @result.success?
+    end
   end
 
   # Add a value to an attribute. Takes the full DN of the entry to modify,
@@ -996,21 +1029,26 @@ class Net::LDAP
   #
   # _Documentation_ _stub_
   def rename(args)
-    if @open_connection
-      @result = @open_connection.rename(args)
-    else
-      @result = 0
-      begin
-        conn = Connection.new(:host => @host, :port => @port,
-                              :encryption => @encryption)
-        if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
-          @result = conn.rename(args)
+    instrument "rename.net_ldap", args do |payload|
+      if @open_connection
+        @result = @open_connection.rename(args)
+      else
+        @result = 0
+        begin
+          conn = Connection.new \
+            :host                    => @host,
+            :port                    => @port,
+            :encryption              => @encryption,
+            :instrumentation_service => @instrumentation_service
+          if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
+            @result = conn.rename(args)
+          end
+        ensure
+          conn.close if conn
         end
-      ensure
-        conn.close if conn
       end
+      @result.success?
     end
-    @result.success?
   end
   alias_method :modify_rdn, :rename
 
@@ -1024,21 +1062,26 @@ class Net::LDAP
   #  dn = "mail=deleteme@example.com, ou=people, dc=example, dc=com"
   #  ldap.delete :dn => dn
   def delete(args)
-    if @open_connection
-      @result = @open_connection.delete(args)
-    else
-      @result = 0
-      begin
-        conn = Connection.new(:host => @host, :port => @port,
-                              :encryption => @encryption)
-        if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
-          @result = conn.delete(args)
+    instrument "delete.net_ldap", args do |payload|
+      if @open_connection
+        @result = @open_connection.delete(args)
+      else
+        @result = 0
+        begin
+          conn = Connection.new \
+            :host                    => @host,
+            :port                    => @port,
+            :encryption              => @encryption,
+            :instrumentation_service => @instrumentation_service
+          if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
+            @result = conn.delete(args)
+          end
+        ensure
+          conn.close
         end
-      ensure
-        conn.close
       end
+      @result.success?
     end
-    @result.success?
   end
 
   # Delete an entry from the LDAP directory along with all subordinate entries.
@@ -1125,7 +1168,7 @@ class Net::LDAP
   def paged_searches_supported?
 		# active directory returns that it supports paged results. However
 		# it returns binary data in the rfc2696_cookie which throws an
-		# encoding exception breaking searching.		
+		# encoding exception breaking searching.
 		return false if @force_no_page
     @server_caps ||= search_root_dse
     @server_caps[:supportedcontrol].include?(Net::LDAP::LDAPControls::PAGED_RESULTS)
@@ -1135,10 +1178,14 @@ end # class LDAP
 # This is a private class used internally by the library. It should not
 # be called by user code.
 class Net::LDAP::Connection #:nodoc:
+  include Net::LDAP::Instrumentation
+
   LdapVersion = 3
   MaxSaslChallenges = 10
 
   def initialize(server)
+    @instrumentation_service = server[:instrumentation_service]
+
     begin
       @conn = TCPSocket.new(server[:host], server[:port])
     rescue SocketError
@@ -1218,8 +1265,8 @@ class Net::LDAP::Connection #:nodoc:
       msgid = next_msgid.to_ber
       request = [Net::LDAP::StartTlsOid.to_ber_contextspecific(0)].to_ber_appsequence(Net::LDAP::PDU::ExtendedRequest)
       request_pkt = [msgid, request].to_ber_sequence
-      @conn.write request_pkt
-      be = @conn.read_ber(Net::LDAP::AsnSyntax)
+      write request_pkt
+      be = read
       raise Net::LDAP::LdapError, "no start_tls result" if be.nil?
       pdu = Net::LDAP::PDU.new(be)
       raise Net::LDAP::LdapError, "no start_tls result" if pdu.nil?
@@ -1243,21 +1290,51 @@ class Net::LDAP::Connection #:nodoc:
     @conn = nil
   end
 
+  # Internal: Reads and parses data from the configured connection.
+  #
+  # - syntax: the BER syntax to use to parse the read data with
+  #
+  # Returns basic BER objects.
+  def read(syntax = Net::LDAP::AsnSyntax)
+    instrument "read.net_ldap_connection", :syntax => syntax do |payload|
+      @conn.read_ber(syntax) do |id, content_length|
+        payload[:object_type_id] = id
+        payload[:content_length] = content_length
+      end
+    end
+  end
+  private :read
+
+  # Internal: Writes the given packet to the configured connection.
+  #
+  # - packet: the BER data packet to write on the socket.
+  #
+  # Returns the return value from writing to the connection, which in some
+  # cases is the Integer number of bytes written to the socket.
+  def write(packet)
+    instrument "write.net_ldap_connection" do |payload|
+      payload[:content_length] = @conn.write(packet)
+    end
+  end
+  private :write
+
   def next_msgid
     @msgid ||= 0
     @msgid += 1
   end
 
   def bind(auth)
-    meth = auth[:method]
-    if [:simple, :anonymous, :anon].include?(meth)
-      bind_simple auth
-    elsif meth == :sasl
-      bind_sasl(auth)
-    elsif meth == :gss_spnego
-      bind_gss_spnego(auth)
-    else
-      raise Net::LDAP::LdapError, "Unsupported auth method (#{meth})"
+    instrument "bind.net_ldap_connection" do |payload|
+      payload[:method] = meth = auth[:method]
+      if [:simple, :anonymous, :anon].include?(meth)
+        bind_simple auth
+      elsif meth == :sasl
+        bind_sasl(auth)
+      elsif meth == :gss_spnego
+        bind_gss_spnego(auth)
+      else
+        raise Net::LDAP::LdapError, "Unsupported auth method (#{meth})"
+      end
     end
   end
 
@@ -1278,9 +1355,9 @@ class Net::LDAP::Connection #:nodoc:
     request = [LdapVersion.to_ber, user.to_ber,
       psw.to_ber_contextspecific(0)].to_ber_appsequence(0)
     request_pkt = [msgid, request].to_ber_sequence
-    @conn.write request_pkt
+    write request_pkt
 
-    (be = @conn.read_ber(Net::LDAP::AsnSyntax) and pdu = Net::LDAP::PDU.new(be)) or raise Net::LDAP::LdapError, "no bind result"
+    (be = read and pdu = Net::LDAP::PDU.new(be)) or raise Net::LDAP::LdapError, "no bind result"
 
     pdu
   end
@@ -1317,9 +1394,9 @@ class Net::LDAP::Connection #:nodoc:
       sasl = [mech.to_ber, cred.to_ber].to_ber_contextspecific(3)
       request = [LdapVersion.to_ber, "".to_ber, sasl].to_ber_appsequence(0)
       request_pkt = [msgid, request].to_ber_sequence
-      @conn.write request_pkt
+      write request_pkt
 
-      (be = @conn.read_ber(Net::LDAP::AsnSyntax) and pdu = Net::LDAP::PDU.new(be)) or raise Net::LDAP::LdapError, "no bind result"
+      (be = read and pdu = Net::LDAP::PDU.new(be)) or raise Net::LDAP::LdapError, "no bind result"
       return pdu unless pdu.result_code == 14 # saslBindInProgress
       raise Net::LDAP::LdapError, "sasl-challenge overflow" if ((n += 1) > MaxSaslChallenges)
 
@@ -1419,7 +1496,7 @@ class Net::LDAP::Connection #:nodoc:
 	deref = args[:deref] || Net::LDAP::DerefAliases_Never
 	raise Net::LDAP::LdapError.new( "invalid alias dereferencing value" ) unless Net::LDAP::DerefAliasesArray.include?(deref)
 
-	
+
     # An interesting value for the size limit would be close to A/D's
     # built-in page limit of 1000 records, but openLDAP newer than version
     # 2.2.0 chokes on anything bigger than 126. You get a silent error that
@@ -1444,110 +1521,127 @@ class Net::LDAP::Connection #:nodoc:
     result_pdu = nil
     n_results = 0
 
-    loop {
-      # should collect this into a private helper to clarify the structure
-      query_limit = 0
-      if sizelimit > 0
-        if paged_searches_supported
-          query_limit = (((sizelimit - n_results) < 126) ? (sizelimit -
-                                                            n_results) : 0)
-        else
-          query_limit = sizelimit
+    instrument "search.net_ldap_connection",
+               :filter     => search_filter,
+               :base       => search_base,
+               :scope      => scope,
+               :limit      => sizelimit,
+               :sort       => sort_control,
+               :referrals  => return_referrals,
+               :deref      => deref,
+               :attributes => search_attributes do |payload|
+      loop do
+        # should collect this into a private helper to clarify the structure
+        query_limit = 0
+        if sizelimit > 0
+          if paged_searches_supported
+            query_limit = (((sizelimit - n_results) < 126) ? (sizelimit -
+                                                              n_results) : 0)
+          else
+            query_limit = sizelimit
+          end
         end
-      end
 
-      request = [
-        search_base.to_ber,
-        scope.to_ber_enumerated,
-        deref.to_ber_enumerated,
-        query_limit.to_ber, # size limit
-        0.to_ber,
-        attributes_only.to_ber,
-        search_filter.to_ber,
-        search_attributes.to_ber_sequence
-      ].to_ber_appsequence(3)
-
-			# rfc2696_cookie sometimes contains binary data from Microsoft Active Directory
-			# this breaks when calling to_ber. (Can't force binary data to UTF-8)
-			# we have to disable paging (even though server supports it) to get around this...
-
-      controls = []
-      controls <<
-        [
-          Net::LDAP::LDAPControls::PAGED_RESULTS.to_ber,
-          # Criticality MUST be false to interoperate with normal LDAPs.
-          false.to_ber,
-          rfc2696_cookie.map{ |v| v.to_ber}.to_ber_sequence.to_s.to_ber
-        ].to_ber_sequence if paged_searches_supported
-      controls << sort_control if sort_control
-      controls = controls.empty? ? nil : controls.to_ber_contextspecific(0)
-
-      pkt = [next_msgid.to_ber, request, controls].compact.to_ber_sequence
-      @conn.write pkt
-
-      result_pdu = nil
-      controls = []
-
-      while (be = @conn.read_ber(Net::LDAP::AsnSyntax)) && (pdu = Net::LDAP::PDU.new(be))
-        case pdu.app_tag
-        when 4 # search-data
-          n_results += 1
-          yield pdu.search_entry if block_given?
-        when 19 # search-referral
-          if return_referrals
-            if block_given?
-              se = Net::LDAP::Entry.new
-              se[:search_referrals] = (pdu.search_referrals || [])
-              yield se
+        request = [
+          search_base.to_ber,
+          scope.to_ber_enumerated,
+          deref.to_ber_enumerated,
+          query_limit.to_ber, # size limit
+          0.to_ber,
+          attributes_only.to_ber,
+          search_filter.to_ber,
+          search_attributes.to_ber_sequence
+        ].to_ber_appsequence(3)
+
+  			# rfc2696_cookie sometimes contains binary data from Microsoft Active Directory
+  			# this breaks when calling to_ber. (Can't force binary data to UTF-8)
+  			# we have to disable paging (even though server supports it) to get around this...
+
+        controls = []
+        controls <<
+          [
+            Net::LDAP::LDAPControls::PAGED_RESULTS.to_ber,
+            # Criticality MUST be false to interoperate with normal LDAPs.
+            false.to_ber,
+            rfc2696_cookie.map{ |v| v.to_ber}.to_ber_sequence.to_s.to_ber
+          ].to_ber_sequence if paged_searches_supported
+        controls << sort_control if sort_control
+        controls = controls.empty? ? nil : controls.to_ber_contextspecific(0)
+
+        pkt = [next_msgid.to_ber, request, controls].compact.to_ber_sequence
+        write pkt
+
+        result_pdu = nil
+        controls = []
+
+        while (be = read) && (pdu = Net::LDAP::PDU.new(be))
+          case pdu.app_tag
+          when Net::LDAP::PDU::SearchReturnedData
+            n_results += 1
+            yield pdu.search_entry if block_given?
+          when Net::LDAP::PDU::SearchResultReferral
+            if return_referrals
+              if block_given?
+                se = Net::LDAP::Entry.new
+                se[:search_referrals] = (pdu.search_referrals || [])
+                yield se
+              end
             end
-          end
-        when 5 # search-result
-          result_pdu = pdu
-          controls = pdu.result_controls
-          if return_referrals && pdu.result_code == 10
-            if block_given?
-              se = Net::LDAP::Entry.new
-              se[:search_referrals] = (pdu.search_referrals || [])
-              yield se
+          when Net::LDAP::PDU::SearchResult
+            result_pdu = pdu
+            controls = pdu.result_controls
+            if return_referrals && pdu.result_code == 10
+              if block_given?
+                se = Net::LDAP::Entry.new
+                se[:search_referrals] = (pdu.search_referrals || [])
+                yield se
+              end
             end
+            break
+          else
+            raise Net::LDAP::LdapError, "invalid response-type in search: #{pdu.app_tag}"
           end
-          break
-        else
-          raise Net::LDAP::LdapError, "invalid response-type in search: #{pdu.app_tag}"
         end
-      end
 
-      # When we get here, we have seen a type-5 response. If there is no
-      # error AND there is an RFC-2696 cookie, then query again for the next
-      # page of results. If not, we're done. Don't screw this up or we'll
-      # break every search we do.
-      #
-      # Noticed 02Sep06, look at the read_ber call in this loop, shouldn't
-      # that have a parameter of AsnSyntax? Does this just accidentally
-      # work? According to RFC-2696, the value expected in this position is
-      # of type OCTET STRING, covered in the default syntax supported by
-      # read_ber, so I guess we're ok.
-      more_pages = false
-      if result_pdu.result_code == 0 and controls
-        controls.each do |c|
-          if c.oid == Net::LDAP::LDAPControls::PAGED_RESULTS
-            # just in case some bogus server sends us more than 1 of these.
-            more_pages = false
-            if c.value and c.value.length > 0
-              cookie = c.value.read_ber[1]
-              if cookie and cookie.length > 0
-                rfc2696_cookie[1] = cookie
-                more_pages = true
+        # count number of pages of results
+        payload[:page_count] ||= 0
+        payload[:page_count]  += 1
+
+        # When we get here, we have seen a type-5 response. If there is no
+        # error AND there is an RFC-2696 cookie, then query again for the next
+        # page of results. If not, we're done. Don't screw this up or we'll
+        # break every search we do.
+        #
+        # Noticed 02Sep06, look at the read_ber call in this loop, shouldn't
+        # that have a parameter of AsnSyntax? Does this just accidentally
+        # work? According to RFC-2696, the value expected in this position is
+        # of type OCTET STRING, covered in the default syntax supported by
+        # read_ber, so I guess we're ok.
+        more_pages = false
+        if result_pdu.result_code == 0 and controls
+          controls.each do |c|
+            if c.oid == Net::LDAP::LDAPControls::PAGED_RESULTS
+              # just in case some bogus server sends us more than 1 of these.
+              more_pages = false
+              if c.value and c.value.length > 0
+                cookie = c.value.read_ber[1]
+                if cookie and cookie.length > 0
+                  rfc2696_cookie[1] = cookie
+                  more_pages = true
+                end
               end
             end
           end
         end
-      end
 
-      break unless more_pages
-    } # loop
+        break unless more_pages
+      end # loop
+
+      # track total result count
+      payload[:result_count] = n_results
 
-    result_pdu || OpenStruct.new(:status => :failure, :result_code => 1, :message => "Invalid search")
+      result_pdu || OpenStruct.new(:status => :failure, :result_code => 1, :message => "Invalid search")
+    end # instrument
   end
 
   MODIFY_OPERATIONS = { #:nodoc:
@@ -1584,9 +1678,9 @@ class Net::LDAP::Connection #:nodoc:
     request = [ modify_dn.to_ber,
       ops.to_ber_sequence ].to_ber_appsequence(6)
     pkt = [ next_msgid.to_ber, request ].to_ber_sequence
-    @conn.write pkt
+    write pkt
 
-    (be = @conn.read_ber(Net::LDAP::AsnSyntax)) && (pdu = Net::LDAP::PDU.new(be)) && (pdu.app_tag == 7) or raise Net::LDAP::LdapError, "response missing or invalid"
+    (be = read) && (pdu = Net::LDAP::PDU.new(be)) && (pdu.app_tag == Net::LDAP::PDU::ModifyResponse) or raise Net::LDAP::LdapError, "response missing or invalid"
 
     pdu
   end
@@ -1607,11 +1701,11 @@ class Net::LDAP::Connection #:nodoc:
 
     request = [add_dn.to_ber, add_attrs.to_ber_sequence].to_ber_appsequence(8)
     pkt = [next_msgid.to_ber, request].to_ber_sequence
-    @conn.write pkt
+    write pkt
 
-    (be = @conn.read_ber(Net::LDAP::AsnSyntax)) &&
+    (be = read) &&
       (pdu = Net::LDAP::PDU.new(be)) &&
-      (pdu.app_tag == 9) or
+      (pdu.app_tag == Net::LDAP::PDU::AddResponse) or
       raise Net::LDAP::LdapError, "response missing or invalid"
 
     pdu
@@ -1630,10 +1724,10 @@ class Net::LDAP::Connection #:nodoc:
     request << new_superior.to_ber_contextspecific(0) unless new_superior == nil
 
     pkt = [next_msgid.to_ber, request.to_ber_appsequence(12)].to_ber_sequence
-    @conn.write pkt
+    write pkt
 
-    (be = @conn.read_ber(Net::LDAP::AsnSyntax)) &&
-    (pdu = Net::LDAP::PDU.new( be )) && (pdu.app_tag == 13) or
+    (be = read) &&
+    (pdu = Net::LDAP::PDU.new( be )) && (pdu.app_tag == Net::LDAP::PDU::ModifyRDNResponse) or
     raise Net::LDAP::LdapError.new( "response missing or invalid" )
 
     pdu
@@ -1647,9 +1741,9 @@ class Net::LDAP::Connection #:nodoc:
     controls = args.include?(:control_codes) ? args[:control_codes].to_ber_control : nil #use nil so we can compact later
     request = dn.to_s.to_ber_application_string(10)
     pkt = [next_msgid.to_ber, request, controls].compact.to_ber_sequence
-    @conn.write pkt
+    write pkt
 
-    (be = @conn.read_ber(Net::LDAP::AsnSyntax)) && (pdu = Net::LDAP::PDU.new(be)) && (pdu.app_tag == 11) or raise Net::LDAP::LdapError, "response missing or invalid"
+    (be = read) && (pdu = Net::LDAP::PDU.new(be)) && (pdu.app_tag == Net::LDAP::PDU::DeleteResponse) or raise Net::LDAP::LdapError, "response missing or invalid"
 
     pdu
   end

data/lib/net/ldap/instrumentation.rb

@@ -0,0 +1,23 @@
+module Net::LDAP::Instrumentation
+  attr_reader :instrumentation_service
+  private     :instrumentation_service
+
+  # Internal: Instrument a block with the defined instrumentation service.
+  #
+  # Yields the event payload if a block is given.
+  #
+  # Skips instrumentation if no service is set.
+  #
+  # Returns the return value of the block.
+  def instrument(event, payload = {})
+    payload = (payload || {}).dup
+    if instrumentation_service
+      instrumentation_service.instrument(event, payload) do |payload|
+        payload[:result] = yield(payload) if block_given?
+      end
+    else
+      yield(payload) if block_given?
+    end
+  end
+  private :instrument
+end

data/lib/net/ldap/version.rb

@@ -1,5 +1,5 @@
 module Net
   class LDAP
-    VERSION = "0.7.0"
+    VERSION = "0.8.0"
   end
 end

data/net-ldap.gemspec

@@ -24,7 +24,7 @@ Our roadmap for Net::LDAP 1.0 is to gain full <em>client</em> compliance with
 the most recent LDAP RFCs (4510-4519, plutions of 4520-4532).}
   s.email = ["blackhedd@rubyforge.org", "gemiel@gmail.com", "rory.ocon@gmail.com", "kaspar.schiess@absurd.li", "austin@rubyforge.org"]
   s.extra_rdoc_files = ["Manifest.txt", "Contributors.rdoc", "Hacking.rdoc", "History.rdoc", "License.rdoc", "README.rdoc"]
-  s.files = [".autotest", ".rspec", "Contributors.rdoc", "Hacking.rdoc", "History.rdoc", "License.rdoc", "Manifest.txt", "README.rdoc", "Rakefile", "autotest/discover.rb", "lib/net-ldap.rb", "lib/net/ber.rb", "lib/net/ber/ber_parser.rb", "lib/net/ber/core_ext.rb", "lib/net/ber/core_ext/array.rb", "lib/net/ber/core_ext/bignum.rb", "lib/net/ber/core_ext/false_class.rb", "lib/net/ber/core_ext/fixnum.rb", "lib/net/ber/core_ext/string.rb", "lib/net/ber/core_ext/true_class.rb", "lib/net/ldap.rb", "lib/net/ldap/dataset.rb", "lib/net/ldap/dn.rb", "lib/net/ldap/entry.rb", "lib/net/ldap/filter.rb", "lib/net/ldap/password.rb", "lib/net/ldap/pdu.rb", "lib/net/snmp.rb", "net-ldap.gemspec", "spec/integration/ssl_ber_spec.rb", "spec/spec.opts", "spec/spec_helper.rb", "spec/unit/ber/ber_spec.rb", "spec/unit/ber/core_ext/string_spec.rb", "spec/unit/ldap/dn_spec.rb", "spec/unit/ldap/entry_spec.rb", "spec/unit/ldap/filter_spec.rb", "spec/unit/ldap_spec.rb", "test/common.rb", "test/test_entry.rb", "test/test_filter.rb", "test/test_ldap_connection.rb", "test/test_ldif.rb", "test/test_password.rb", "test/test_rename.rb", "test/test_snmp.rb", "test/testdata.ldif", "testserver/ldapserver.rb", "testserver/testdata.ldif", "lib/net/ldap/version.rb"]
+  s.files = [".autotest", ".rspec", "Contributors.rdoc", "Hacking.rdoc", "History.rdoc", "License.rdoc", "Manifest.txt", "README.rdoc", "Rakefile", "autotest/discover.rb", "lib/net-ldap.rb", "lib/net/ber.rb", "lib/net/ber/ber_parser.rb", "lib/net/ber/core_ext.rb", "lib/net/ber/core_ext/array.rb", "lib/net/ber/core_ext/bignum.rb", "lib/net/ber/core_ext/false_class.rb", "lib/net/ber/core_ext/fixnum.rb", "lib/net/ber/core_ext/string.rb", "lib/net/ber/core_ext/true_class.rb", "lib/net/ldap.rb", "lib/net/ldap/dataset.rb", "lib/net/ldap/dn.rb", "lib/net/ldap/entry.rb", "lib/net/ldap/filter.rb", "lib/net/ldap/instrumentation.rb", "lib/net/ldap/password.rb", "lib/net/ldap/pdu.rb", "lib/net/snmp.rb", "net-ldap.gemspec", "spec/integration/ssl_ber_spec.rb", "spec/spec.opts", "spec/spec_helper.rb", "spec/unit/ber/ber_spec.rb", "spec/unit/ber/core_ext/string_spec.rb", "spec/unit/ldap/dn_spec.rb", "spec/unit/ldap/entry_spec.rb", "spec/unit/ldap/filter_spec.rb", "spec/unit/ldap_spec.rb", "test/common.rb", "test/test_entry.rb", "test/test_filter.rb", "test/test_ldap_connection.rb", "test/test_ldif.rb", "test/test_password.rb", "test/test_rename.rb", "test/test_snmp.rb", "test/testdata.ldif", "testserver/ldapserver.rb", "testserver/testdata.ldif", "lib/net/ldap/version.rb"]
   s.homepage = %q{http://github.com/ruby-ldap/ruby-net-ldap}
   s.rdoc_options = ["--main", "README.rdoc"]
   s.require_paths = ["lib"]

data/spec/spec_helper.rb

@@ -8,3 +8,21 @@ RSpec.configure do |config|
     s.respond_to?(:b) ? s.b : s
   end
 end
+
+class MockInstrumentationService
+  def initialize
+    @events = {}
+  end
+
+  def instrument(event, payload)
+    result = yield(payload)
+    @events[event] ||= []
+    @events[event] << [payload, result]
+    result
+  end
+
+  def subscribe(event)
+    @events[event] ||= []
+    @events[event]
+  end
+end

data/spec/unit/ldap/search_spec.rb

@@ -8,7 +8,8 @@ describe Net::LDAP, "search method" do
   end
 
   before(:each) do
-    @connection = Net::LDAP.new
+    @service = MockInstrumentationService.new
+    @connection = Net::LDAP.new :instrumentation_service => @service
     @connection.instance_variable_set(:@open_connection, FakeConnection.new)
   end
 
@@ -32,4 +33,17 @@ describe Net::LDAP, "search method" do
       result_set.should be_nil
     end
   end
+
+  context "when instrumentation_service is configured" do
+    it "should publish a search.net_ldap event" do
+      events = @service.subscribe "search.net_ldap"
+
+      @connection.search :filter => "test"
+
+      payload, result = events.pop
+      payload.should have_key(:result)
+      payload.should have_key(:filter)
+      payload[:filter].should == "test"
+    end
+  end
 end

data/spec/unit/ldap_spec.rb

@@ -1,5 +1,54 @@
 require 'spec_helper'
 
+describe Net::LDAP do
+  describe "initialize" do
+    context "when instrumentation is configured" do
+      before do
+        @connection = flexmock(:connection, :close => true)
+        flexmock(Net::LDAP::Connection).should_receive(:new).and_return(@connection)
+
+        @service = MockInstrumentationService.new
+      end
+
+      subject do
+        Net::LDAP.new \
+          :server => "test.mocked.com", :port => 636,
+          :force_no_page => true, # so server capabilities are not queried
+          :instrumentation_service => @service
+      end
+
+      it "should instrument bind" do
+        events = @service.subscribe "bind.net_ldap"
+
+        bind_result = flexmock(:bind_result, :success? => true)
+        @connection.should_receive(:bind).with(Hash).and_return(bind_result)
+
+        subject.bind.should be_true
+
+        payload, result = events.pop
+        result.should be_true
+        payload[:bind].should == bind_result
+      end
+
+      it "should instrument search" do
+        events = @service.subscribe "search.net_ldap"
+
+        @connection.should_receive(:bind).and_return(flexmock(:bind_result, :result_code => 0))
+        @connection.should_receive(:search).with(Hash, Proc).
+                    yields(entry = Net::LDAP::Entry.new("uid=user1,ou=users,dc=example,dc=com")).
+                    and_return(flexmock(:search_result, :success? => true, :result_code => 0))
+
+        subject.search(:filter => "(uid=user1)").should be_true
+
+        payload, result = events.pop
+        result.should == [entry]
+        payload[:result].should == [entry]
+        payload[:filter].should == "(uid=user1)"
+      end
+    end
+  end
+end
+
 describe Net::LDAP::Connection do
   describe "initialize" do
     context "when host is not responding" do
@@ -57,7 +106,7 @@ describe Net::LDAP::Connection do
 
     it "should get back error messages if operation fails" do
       ber = Net::BER::BerIdentifiedArray.new([53, "", "The provided password value was rejected by a password validator:  The provided password did not contain enough characters from the character set 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.  The minimum number of characters from that set that must be present in user passwords is 1"])
-      ber.ber_identifier = 7
+      ber.ber_identifier = Net::LDAP::PDU::ModifyResponse
       @tcp_socket.should_receive(:read_ber).and_return([2, ber])
 
       result = subject.modify(:dn => "1", :operations => [[:replace, "mail", "something@sothsdkf.com"]])
@@ -67,7 +116,7 @@ describe Net::LDAP::Connection do
 
     it "shouldn't get back error messages if operation succeeds" do
       ber = Net::BER::BerIdentifiedArray.new([0, "", ""])
-      ber.ber_identifier = 7
+      ber.ber_identifier = Net::LDAP::PDU::ModifyResponse
       @tcp_socket.should_receive(:read_ber).and_return([2, ber])
 
       result = subject.modify(:dn => "1", :operations => [[:replace, "mail", "something@sothsdkf.com"]])
@@ -75,4 +124,100 @@ describe Net::LDAP::Connection do
       result.error_message.should == ""
     end
   end
+
+  context "instrumentation" do
+    before do
+      @tcp_socket = flexmock(:connection)
+      # handle write
+      @tcp_socket.should_receive(:write)
+      # return this mock
+      flexmock(TCPSocket).should_receive(:new).and_return(@tcp_socket)
+
+      @service = MockInstrumentationService.new
+    end
+
+    subject do
+      Net::LDAP::Connection.new(:server => 'test.mocked.com', :port => 636,
+                                :instrumentation_service => @service)
+    end
+
+    it "should publish a write.net_ldap_connection event" do
+      ber = Net::BER::BerIdentifiedArray.new([0, "", ""])
+      ber.ber_identifier = Net::LDAP::PDU::BindResult
+      read_result = [2, ber]
+      @tcp_socket.should_receive(:read_ber).and_return(read_result)
+
+      events = @service.subscribe "write.net_ldap_connection"
+
+      result = subject.bind(method: :anon)
+      result.should be_success
+
+      # a write event
+      payload, result = events.pop
+      payload.should have_key(:result)
+      payload.should have_key(:content_length)
+    end
+
+    it "should publish a read.net_ldap_connection event" do
+      ber = Net::BER::BerIdentifiedArray.new([0, "", ""])
+      ber.ber_identifier = Net::LDAP::PDU::BindResult
+      read_result = [2, ber]
+      @tcp_socket.should_receive(:read_ber).and_return(read_result)
+
+      events = @service.subscribe "read.net_ldap_connection"
+
+      result = subject.bind(method: :anon)
+      result.should be_success
+
+      # a read event
+      payload, result = events.pop
+      payload.should have_key(:result)
+      result.should == read_result
+    end
+
+    it "should publish a bind.net_ldap_connection event" do
+      ber = Net::BER::BerIdentifiedArray.new([0, "", ""])
+      ber.ber_identifier = Net::LDAP::PDU::BindResult
+      bind_result = [2, ber]
+      @tcp_socket.should_receive(:read_ber).and_return(bind_result)
+
+      events = @service.subscribe "bind.net_ldap_connection"
+
+      result = subject.bind(method: :anon)
+      result.should be_success
+
+      # a read event
+      payload, result = events.pop
+      payload.should have_key(:result)
+      result.should be_success
+    end
+
+    it "should publish a search.net_ldap_connection event" do
+      # search data
+      search_data_ber = Net::BER::BerIdentifiedArray.new([2, [
+        "uid=user1,ou=OrgUnit2,ou=OrgUnitTop,dc=openldap,dc=ghe,dc=local",
+        [ ["uid", ["user1"]] ]
+      ]])
+      search_data_ber.ber_identifier = Net::LDAP::PDU::SearchReturnedData
+      search_data = [2, search_data_ber]
+      # search result (end of results)
+      search_result_ber = Net::BER::BerIdentifiedArray.new([0, "", ""])
+      search_result_ber.ber_identifier = Net::LDAP::PDU::SearchResult
+      search_result = [2, search_result_ber]
+      @tcp_socket.should_receive(:read_ber).and_return(search_data).
+                                            and_return(search_result)
+
+      events = @service.subscribe "search.net_ldap_connection"
+
+      result = subject.search(filter: "(uid=user1)")
+      result.should be_success
+
+      # a search event
+      payload, result = events.pop
+      payload.should have_key(:result)
+      payload.should have_key(:filter)
+      payload[:filter].to_s.should == "(uid=user1)"
+      result.should be_truthy
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-ldap
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Francis Cianfrocca
@@ -13,7 +13,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-04 00:00:00.000000000 Z
+date: 2014-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
@@ -170,6 +170,7 @@ files:
 - lib/net/ldap/dn.rb
 - lib/net/ldap/entry.rb
 - lib/net/ldap/filter.rb
+- lib/net/ldap/instrumentation.rb
 - lib/net/ldap/password.rb
 - lib/net/ldap/pdu.rb
 - lib/net/ldap/version.rb