lom 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3a1b6204446324ec92c63443efc8c9578db7628aa4544f42c435a1605ec05aa
-  data.tar.gz: 7fa61741e1c85db00a5ab168d2814afcc0a21ba0ba2a914649f7e8ef6f6df815
+  metadata.gz: b7080950578c9a8cdcff8a1a6e527d2c53a2981fb05f32099e114ac3a73f9221
+  data.tar.gz: 49c5a2a4072773cf445f6ba30ee60acb59fb8745a78f927fda4eb987e60d4efe
 SHA512:
-  metadata.gz: 468294c000324a795a2a3cb67de0436c492e4d08caffea7d14bbc47486b81640fb2c352df233771aefa1cc136e71a1dbcc98efe24c49c7b79d6952f824e1787d
-  data.tar.gz: 4add52468b4bb244a215dfa2ac32244417f3b282d615c19f2dcc30cc97601bd9c678180047da6de881bd9952f6423f3d5ac743d0d575dd80079f9d6ddb3e5432
+  metadata.gz: dc64dfa9fcaa777ae4e9dd4dd65e0b3527f2bfa1482389aa83714c1d6bad346a4806a174886c2fc74c1ab3a235bbbbf548d13a978650bc6a1a580eb65d778f17
+  data.tar.gz: e79faf8dd9af3b388ccf6b7ee67a084832ad1eadab13bc955838492f6feb9cccbcc341f4dd526bb92fe145fcaffc08e9c1d85b12abe02370fd9c61b8aff0ab29

data/README.md

@@ -156,3 +156,46 @@ User.locked(true).manager('jdoe').list
 # Return list of users (as User instance)  without managers
 User.manager(false).all
 ~~~
+
+
+Threaded servers
+================
+
+A `Net::LDAP` handler is not thread safe: each operation stores its
+outcome in the handler itself, so two threads sharing a handler can
+read each other's result. When LOM is used from several threads
+(Puma, background jobs, ...), give it a callable instead of a
+handler: it is called once per thread (or fiber), and the handler it
+builds is reused by that thread.
+
+~~~ruby
+LH = -> { Net::LDAP.connect('ldap://127.0.0.1')
+                   .tap { it.auth 'uid=root,ou=Admins,dc=example,dc=com',
+                                  'foobar' } }
+~~~
+
+Without an opened connection, `Net::LDAP` connects and binds for each
+operation. `LOM.open` keeps a single connection for all the operations
+of its block; nested calls reuse it, and if the connection or bind
+fails the block still runs with one connection per operation. It only
+opens when the handler comes from a callable, as an opened connection
+must not be shared between threads.
+
+~~~ruby
+LOM.open { User.locked(true).all }
+~~~
+
+In a Rack application, a middleware gives one connection per request:
+
+~~~ruby
+class LDAPConnection
+    def initialize(app) = @app = app
+    def call(env)       = LOM.open { @app.call(env) }
+end
+
+use LDAPConnection
+~~~
+
+`LOM.open` only opens the handler of `LOM.lh`; a mapper given its own
+handler (`lh=` or its own `LH` constant) still uses one connection per
+operation.

data/lib/lom/handler.rb

@@ -4,6 +4,19 @@ class LOM
     using LDAP::Extensions
 
     
+    # Set the LDAP handler to use
+    #
+    # It can be a Net::LDAP handler, or a callable (proc, lambda, ...)
+    # building one. A Net::LDAP handler is not thread safe, so a
+    # callable is required as soon as LOM is used from several threads:
+    # it will be called once per thread (or fiber), and the resulting
+    # handler reused by that thread.
+    #
+    # ~~~
+    # LOM.lh = -> { Net::LDAP.connect('ldap://127.0.0.1')
+    #                        .tap { it.auth(dn, password) } }
+    # ~~~
+    #
     def self.lh=(lh)
         @lh = lh
     end
@@ -16,11 +29,131 @@ class LOM
     # * the LH constant in this scope or parent scope
     # * the one defined in $lh
     #
+    # If the handler is a callable, the handler built by it for the
+    # current thread is returned.
+    #
     def self.lh
-        @lh || const_get(:LH) || $lh
+        materialize_lh(lh_source)
     end   
 
+    # Get the LDAP handler source (handler or callable), see lh
+    #
+    # @api private
+    #
+    def self.lh_source
+        @lh || (const_defined?(:LH) && const_get(:LH)) || $lh
+    end
+
+    # Resolve a handler source to a usable LDAP handler.
+    #
+    # A callable is called once per thread (or fiber) and its result
+    # cached for that thread, anything else is returned unchanged.
+    #
+    # @api private
+    #
+    def self.materialize_lh(src)
+        return src unless src.respond_to?(:call)
+        (Thread.current[:__lom_lh] ||= {}.compare_by_identity)[src] ||=
+            src.call
+    end
+
+    # Run the block with a single LDAP connection opened and bound,
+    # which is reused by all the LDAP operations of the block,
+    # instead of one connection per operation.
+    #
+    # This is only done if the handler is a callable (see lh=), as an
+    # opened connection must not be shared between threads, otherwise
+    # the block is simply run.
+    #
+    # If the connection or bind fails, the block is still run, falling
+    # back to one connection per operation.
+    #
+    # Nested calls reuse the already opened connection.
+    #
+    # @return the block value
+    #
+    def self.open
+        src = lh_source
+        return yield unless src.respond_to?(:call)
+
+        lh     = materialize_lh(src)
+        opened = (Thread.current[:__lom_opened] ||= {}.compare_by_identity)
+        return yield if opened[lh]
+
+        entered = false
+        result  = nil
+        begin
+            lh.open do
+                code = lh.get_operation_result.code
+                next unless code == Net::LDAP::ResultCodeSuccess
+                opened[lh] = { depth: 0, dirty: false }
+                entered    = true
+                begin
+                    result = yield
+                ensure
+                    opened.delete(lh)
+                end
+            end
+        rescue Net::LDAP::Error, SystemCallError, IOError
+            raise if entered
+        end
+        entered ? result : yield
+    end
+
+    # Run the block performing a search on the handler.
+    #
+    # If the handler connection was opened by LOM.open and the search
+    # is left before completion (break, exception, ...), the unread
+    # search results would be kept until the end of LOM.open, so the
+    # connection is replaced by a new one, once no other search is
+    # using it.
+    #
+    # @api private
+    #
+    def self.searching(lh)
+        state = Thread.current[:__lom_opened]&.[](lh)
+        return yield if state.nil?
+
+        state[:depth] += 1
+        done = false
+        begin
+            yield.tap { done = true }
+        ensure
+            state[:depth] -= 1
+            state[:dirty] ||= !done
+            reopen(lh, state) if state[:dirty] && state[:depth].zero?
+        end
+    end
+
+    # Replace the connection opened by LOM.open with a new one.
+    # If it can't be opened and bound, operations fall back to
+    # one connection per operation.
+    #
+    # @note relies on Net::LDAP internals (@open_connection, @auth,
+    #       #new_connection) as used by Net::LDAP#open
+    #
+    # @api private
+    #
+    def self.reopen(lh, state)
+        state[:dirty] = false
+        begin
+            lh.instance_variable_get(:@open_connection)&.close
+        rescue StandardError
+        end
+        lh.instance_variable_set(:@open_connection, nil)
 
+        conn = lh.send(:new_connection)
+        res  = conn.bind(lh.instance_variable_get(:@auth))
+        if res.result_code == Net::LDAP::ResultCodeSuccess
+            lh.instance_variable_set(:@open_connection, conn)
+        else
+            conn.close
+        end
+    rescue Net::LDAP::Error, SystemCallError, IOError
+        conn&.close rescue nil
+    end
+
+    
     # extend Forwardable
     #
     # def self.connect(*args)
@@ -38,6 +171,3 @@ class LOM
     # def_delegator :@lh, :delete
 
 end
-                 
-
-

data/lib/lom/mapper.rb

@@ -114,8 +114,12 @@ module Mapper
     # * the LH constant in this scope or parent scope
     # * the one provided by LOM.lh
     #
+    # If the handler is a callable, the handler built by it for the
+    # current thread is returned (see LOM.lh=).
+    #
     def lh
-        @__ldap_lh || const_get(:LH) || LOM.lh
+        LOM.materialize_lh(@__ldap_lh ||
+                           (const_defined?(:LH) && const_get(:LH)) || LOM.lh)
     end
 
     # Set the LDAP handler to use
@@ -275,23 +279,30 @@ module Mapper
                       end
         
         # Perform search
-        lh.search(:base       => _ldap_branch,
-                  :filter     => filter,
-                  :attributes => attributes,
-                  :scope      => _ldap_scope) {|entry|
-
-            if rawfilter && !rawfilter.call(entry)
-                next
-            elsif paged.nil?
-                yield(converter.(entry))
-            elsif skip > 0
-                skip -= 1
-            elsif count <= 0
-                break
-            else
-                count -= 1
-                yield(converter.(entry))
-            end                
+        # Note: the search must not be left early (with break), as it
+        #       would leave unread results on a connection opened
+        #       by LOM.open; leaving it from the caller block is
+        #       handled by LOM.searching
+        h = lh
+        LOM.searching(h) {
+            h.search(:base       => _ldap_branch,
+                     :filter     => filter,
+                     :attributes => attributes,
+                     :scope      => _ldap_scope) {|entry|
+
+                if rawfilter && !rawfilter.call(entry)
+                    next
+                elsif paged.nil?
+                    yield(converter.(entry))
+                elsif skip > 0
+                    skip -= 1
+                elsif count <= 0
+                    next
+                else
+                    count -= 1
+                    yield(converter.(entry))
+                end                
+            }
         }
 
         # Return self

data/lib/lom/version.rb

@@ -1,3 +1,3 @@
 class LOM
-    VERSION = '0.11.0'
+    VERSION = '0.12.0'
 end

data/lom.gemspec

@@ -26,4 +26,5 @@ Gem::Specification.new do |s|
     s.add_dependency 'net-ldap'
     s.add_development_dependency 'yard', '~>0'
     s.add_development_dependency 'rake', '~>13'
+    s.add_development_dependency 'minitest', '~>5'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lom
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Stéphane D'Alu
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
 description: |2+
 
   Creation of mapping between ldap entry and ruby object.
@@ -92,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.21
 specification_version: 4
 summary: LDAP Object Mapper
 test_files: []