mongo 2.19.2 → 2.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 455d5b9685fd2cefa18a1c37e81ddb97a177ac8e40b9298945e4f126ac9ce093
-  data.tar.gz: fab0630edde803ab5125536159e8fbd12d3f0bac233e87d40ea1e414287145ac
+  metadata.gz: 281c66c9e5d92b0eb8040c342bb0dfcf554c9b5420ec803bc68748472d74a1ae
+  data.tar.gz: 423f31b24accb3ce674ea28a7aa8fcaf028730eb1370187c23f5304ba30698f6
 SHA512:
-  metadata.gz: f3db945520bf825c31fcd7a21295b03257b1ee01d3d2eb6903f69ae6dfdbb0834516c8214227196702f88e087754780a876941eb5a3ac8f0861bff40a3e55a07
-  data.tar.gz: 73ea3f0a4fc86ba9922c1054f925db03eab8ac3da47bd9b9daae5006af1f32299c3d1a45104623126db5c89e41bf3ddbfe82dd641ea77dce6d8936a5297a1880
+  metadata.gz: 4f414d30bf15f7c32ac9181e25e707caa80447975690fc6c0eb9d8fa37a784f8c4d21125b385d5a6d7efdb4bd751ee2c9c4bea313adbf78d20de3b019c25ac8a
+  data.tar.gz: 7a83ba71f6a36d886769d755fb5ea45e6d1fae37bd92b490c58e9f643f51c25d5a489ed79928d67975f067d258c738f54cc3e5caecca6eb0bad2e2bf49d81613

data/Rakefile

@@ -119,6 +119,32 @@ end
 
 task :release => ['release:check_private_key', 'release:do']
 
+desc 'Build and validate the evergreen config'
+task eg: %w[ eg:build eg:validate ]
+
+# 'eg' == 'evergreen', but evergreen is too many letters for convenience
+namespace :eg do
+  desc 'Builds the .evergreen/config.yml file from the templates'
+  task :build do
+    ruby '.evergreen/update-evergreen-configs'
+  end
+
+  desc 'Validates the .evergreen/config.yml file'
+  task :validate do
+    system 'evergreen validate --project mongo-ruby-driver .evergreen/config.yml'
+  end
+
+  desc 'Updates the evergreen executable to the latest available version'
+  task :update do
+    system 'evergreen get-update --install'
+  end
+
+  desc 'Runs the current branch as an evergreen patch'
+  task :patch do
+    system 'evergreen patch --uncommitted --project mongo-ruby-driver --browse --auto-description --yes'
+  end
+end
+
 desc "Generate all documentation"
 task :docs => 'docs:yard'
 
@@ -131,157 +157,4 @@ namespace :docs do
   end
 end
 
-require_relative "profile/benchmarking"
-
-# Some require data files, available from the drivers team. See the comments above each task for details."
-namespace :benchmark do
-  desc "Run the driver benchmark tests."
-
-  namespace :micro do
-    desc "Run the common driver micro benchmarking tests"
-
-    namespace :flat do
-      desc "Benchmarking for flat bson documents."
-
-      # Requirement: A file in Mongo::Benchmarking::DATA_PATH, called flat_bson.json.
-      task :encode do
-        puts "MICRO BENCHMARK:: FLAT:: ENCODE"
-        Mongo::Benchmarking::Micro.run(:flat, :encode)
-      end
-
-      # Requirement: A file in Mongo::Benchmarking::DATA_PATH, called flat_bson.json.
-      task :decode do
-        puts "MICRO BENCHMARK:: FLAT:: DECODE"
-        Mongo::Benchmarking::Micro.run(:flat, :decode)
-      end
-    end
-
-    namespace :deep do
-      desc "Benchmarking for deep bson documents."
-
-      # Requirement: A file in Mongo::Benchmarking::DATA_PATH, called deep_bson.json.
-      task :encode do
-        puts "MICRO BENCHMARK:: DEEP:: ENCODE"
-        Mongo::Benchmarking::Micro.run(:deep, :encode)
-      end
-
-      # Requirement: A file in Mongo::Benchmarking::DATA_PATH, called deep_bson.json.
-      task :decode do
-        puts "MICRO BENCHMARK:: DEEP:: DECODE"
-        Mongo::Benchmarking::Micro.run(:deep, :decode)
-      end
-    end
-
-    namespace :full do
-      desc "Benchmarking for full bson documents."
-
-      # Requirement: A file in Mongo::Benchmarking::DATA_PATH, called full_bson.json.
-      task :encode do
-        puts "MICRO BENCHMARK:: FULL:: ENCODE"
-        Mongo::Benchmarking::Micro.run(:full, :encode)
-      end
-
-      # Requirement: A file in Mongo::Benchmarking::DATA_PATH, called full_bson.json.
-      task :decode do
-        puts "MICRO BENCHMARK:: FULL:: DECODE"
-        Mongo::Benchmarking::Micro.run(:full, :decode)
-      end
-    end
-  end
-
-  namespace :single_doc do
-    desc "Run the common driver single-document benchmarking tests"
-    task :command do
-      puts "SINGLE DOC BENCHMARK:: COMMAND"
-      Mongo::Benchmarking::SingleDoc.run(:command)
-    end
-
-    # Requirement: A file in Mongo::Benchmarking::DATA_PATH, called TWEET.json.
-    task :find_one do
-      puts "SINGLE DOC BENCHMARK:: FIND ONE BY ID"
-      Mongo::Benchmarking::SingleDoc.run(:find_one)
-    end
-
-    # Requirement: A file in Mongo::Benchmarking::DATA_PATH, called SMALL_DOC.json.
-    task :insert_one_small do
-      puts "SINGLE DOC BENCHMARK:: INSERT ONE SMALL DOCUMENT"
-      Mongo::Benchmarking::SingleDoc.run(:insert_one_small)
-    end
-
-    # Requirement: A file in Mongo::Benchmarking::DATA_PATH, called LARGE_DOC.json.
-    task :insert_one_large do
-      puts "SINGLE DOC BENCHMARK:: INSERT ONE LARGE DOCUMENT"
-      Mongo::Benchmarking::SingleDoc.run(:insert_one_large)
-    end
-  end
-
-  namespace :multi_doc do
-    desc "Run the common driver multi-document benchmarking tests"
-
-    # Requirement: A file in Mongo::Benchmarking::DATA_PATH, called TWEET.json.
-    task :find_many do
-      puts "MULTI DOCUMENT BENCHMARK:: FIND MANY"
-      Mongo::Benchmarking::MultiDoc.run(:find_many)
-    end
-
-    # Requirement: A file in Mongo::Benchmarking::DATA_PATH, called SMALL_DOC.json.
-    task :bulk_insert_small do
-      puts "MULTI DOCUMENT BENCHMARK:: BULK INSERT SMALL"
-      Mongo::Benchmarking::MultiDoc.run(:bulk_insert_small)
-    end
-
-    # Requirement: A file in Mongo::Benchmarking::DATA_PATH, called LARGE_DOC.json.
-    task :bulk_insert_large do
-      puts "MULTI DOCUMENT BENCHMARK:: BULK INSERT LARGE"
-      Mongo::Benchmarking::MultiDoc.run(:bulk_insert_large)
-    end
-
-    # Requirement: A file in Mongo::Benchmarking::DATA_PATH, called GRIDFS_LARGE.
-    task :gridfs_upload do
-      puts "MULTI DOCUMENT BENCHMARK:: GRIDFS UPLOAD"
-      Mongo::Benchmarking::MultiDoc.run(:gridfs_upload)
-    end
-
-    # Requirement: A file in Mongo::Benchmarking::DATA_PATH, called GRIDFS_LARGE.
-    task :gridfs_download do
-      puts "MULTI DOCUMENT BENCHMARK:: GRIDFS DOWNLOAD"
-      Mongo::Benchmarking::MultiDoc.run(:gridfs_download)
-    end
-  end
-
-  namespace :parallel do
-    desc "Run the common driver paralell ETL benchmarking tests"
-
-    # Requirement: A directory in Mongo::Benchmarking::DATA_PATH, called LDJSON_MULTI,
-    # with the files used in this task.
-    task :import do
-      puts "PARALLEL ETL BENCHMARK:: IMPORT"
-      Mongo::Benchmarking::Parallel.run(:import)
-    end
-
-    # Requirement: A directory in Mongo::Benchmarking::DATA_PATH, called LDJSON_MULTI,
-    # with the files used in this task.
-    # Requirement: Another directory in "#{Mongo::Benchmarking::DATA_PATH}/LDJSON_MULTI"
-    # called 'output'.
-    task :export do
-      puts "PARALLEL ETL BENCHMARK:: EXPORT"
-      Mongo::Benchmarking::Parallel.run(:export)
-    end
-
-    # Requirement: A directory in Mongo::Benchmarking::DATA_PATH, called GRIDFS_MULTI,
-    # with the files used in this task.
-    task :gridfs_upload do
-      puts "PARALLEL ETL BENCHMARK:: GRIDFS UPLOAD"
-      Mongo::Benchmarking::Parallel.run(:gridfs_upload)
-    end
-
-    # Requirement: A directory in Mongo::Benchmarking::DATA_PATH, called GRIDFS_MULTI,
-    # with the files used in this task.
-    # Requirement: Another directory in "#{Mongo::Benchmarking::DATA_PATH}/GRIDFS_MULTI"
-    # called 'output'.
-    task :gridfs_download do
-      puts "PARALLEL ETL BENCHMARK:: GRIDFS DOWNLOAD"
-      Mongo::Benchmarking::Parallel.run(:gridfs_download)
-    end
-  end
-end
+load 'profile/driver_bench/rake/tasks.rake'

data/lib/mongo/cluster/topology/base.rb

@@ -211,6 +211,22 @@ module Mongo
           end
         end
 
+        # Compares each server address against the list of patterns.
+        #
+        # @param [ Array<String> ] patterns the URL suffixes to compare
+        #   each server against.
+        #
+        # @return [ true | false ] whether any of the addresses match any of
+        #   the patterns or not.
+        #
+        # @api private
+        def server_hosts_match_any?(patterns)
+          server_descriptions.any? do |addr_spec, _desc|
+            addr, _port = addr_spec.split(/:/)
+            patterns.any? { |pattern| addr.end_with?(pattern) }
+          end
+        end
+
         private
 
         # Validates and/or transforms options as necessary for the topology.

data/lib/mongo/cluster.rb

@@ -157,7 +157,7 @@ module Mongo
       # @sdam_flow_lock covers just the sdam flow. Note it does not apply
       # to @topology replacements which are done under @update_lock.
       @sdam_flow_lock = Mutex.new
-      Session::SessionPool.create(self)
+      @session_pool = Session::SessionPool.new(self)
 
       if seeds.empty? && load_balanced?
         raise ArgumentError, 'Load-balanced clusters with no seeds are prohibited'
@@ -186,6 +186,8 @@ module Mongo
         recreate_topology(topology, opening_topology)
       end
 
+      possibly_warn_about_compatibility!
+
       if load_balanced?
         # We are required by the specifications to produce certain SDAM events
         # when in load-balanced topology.
@@ -1082,6 +1084,30 @@ module Mongo
         Monitoring::Event::TopologyChanged.new(previous_topology, @topology)
       )
     end
+
+    COSMOSDB_HOST_PATTERNS = %w[ .cosmos.azure.com ]
+    COSMOSDB_LOG_MESSAGE = 'You appear to be connected to a CosmosDB cluster. ' \
+      'For more information regarding feature compatibility and support please visit ' \
+      'https://www.mongodb.com/supportability/cosmosdb'
+
+    DOCUMENTDB_HOST_PATTERNS = %w[ .docdb.amazonaws.com .docdb-elastic.amazonaws.com ]
+    DOCUMENTDB_LOG_MESSAGE = 'You appear to be connected to a DocumentDB cluster. ' \
+      'For more information regarding feature compatibility and support please visit ' \
+      'https://www.mongodb.com/supportability/documentdb'
+
+    # Compares the server hosts with address suffixes of known services
+    # that provide limited MongoDB API compatibility, and warns about them.
+    def possibly_warn_about_compatibility!
+      if topology.server_hosts_match_any?(COSMOSDB_HOST_PATTERNS)
+        log_info COSMOSDB_LOG_MESSAGE
+        return
+      end
+
+      if topology.server_hosts_match_any?(DOCUMENTDB_HOST_PATTERNS)
+        log_info DOCUMENTDB_LOG_MESSAGE
+        return
+      end
+    end
   end
 end
 

data/lib/mongo/collection/view/iterable.rb

@@ -162,6 +162,7 @@ module Mongo
             let: options[:let],
             limit: limit,
             allow_disk_use: options[:allow_disk_use],
+            allow_partial_results: options[:allow_partial_results],
             read: read,
             read_concern: options[:read_concern] || read_concern,
             batch_size: batch_size,

data/lib/mongo/collection.rb

@@ -339,7 +339,9 @@ module Mongo
     #     inserted or updated documents where the clustered index key value
     #     matches an existing value in the index.
     #   - *:name* -- Optional. A name that uniquely identifies the clustered index.
-    # @option opts [ Hash ] :collation The collation to use.
+    # @option opts [ Hash ] :collation The collation to use when creating the
+    #   collection. This option will not be sent to the server when calling
+    #   collection methods.
     # @option opts [ Hash ] :encrypted_fields Hash describing encrypted fields
     #   for queryable encryption.
     # @option opts [ Integer ] :expire_after Number indicating
@@ -725,13 +727,35 @@ module Mongo
     #
     # @option options [ Session ] :session The session to use.
     #
-    # @return [ View::Index ] The index view.
+    # @return [ Index::View ] The index view.
     #
     # @since 2.0.0
     def indexes(options = {})
       Index::View.new(self, options)
     end
 
+    # Get a view of all search indexes for this collection. Can be iterated or
+    # operated on directly. If id or name are given, the iterator will return
+    # only the indicated index. For all other operations, id and name are
+    # ignored.
+    #
+    # @note Only one of id or name may be given; it is an error to specify both,
+    #   although both may be omitted safely.
+    #
+    # @param [ Hash ] options The options to use to configure the view.
+    #
+    # @option options [ String ] :id The id of the specific index to query (optional)
+    # @option options [ String ] :name The name of the specific index to query (optional)
+    # @option options [ Hash ] :aggregate The options hash to pass to the
+    #    aggregate command (optional)
+    #
+    # @return [ SearchIndex::View ] The search index view.
+    #
+    # @since 2.0.0
+    def search_indexes(options = {})
+      SearchIndex::View.new(self, options)
+    end
+
     # Get a pretty printed string inspection for the collection.
     #
     # @example Inspect the collection.
@@ -766,7 +790,7 @@ module Mongo
     def insert_one(document, opts = {})
       QueryCache.clear_namespace(namespace)
 
-      client.send(:with_session, opts) do |session|
+      client.with_session(opts) do |session|
         write_concern = if opts[:write_concern]
           WriteConcern.get(opts[:write_concern])
         else

data/lib/mongo/error/transactions_not_supported.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2019-2020 MongoDB Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  class Error
+    # Transactions are not supported by the cluster. There might be the
+    # following reasons:
+    #  - topology is standalone
+    #  - topology is replica set and server version is < 4.0
+    #  - topology is sharded and server version is < 4.2
+    #
+    # @param [ String ] reason The reason why transactions are no supported.
+    #
+    # @since 2.7.0
+    class TransactionsNotSupported < Error
+      def initialize(reason)
+        super("Transactions are not supported for the cluster: #{reason}")
+      end
+    end
+  end
+end

data/lib/mongo/error.rb

@@ -217,6 +217,7 @@ require 'mongo/error/missing_service_id'
 require 'mongo/error/server_api_conflict'
 require 'mongo/error/server_api_not_supported'
 require 'mongo/error/server_not_usable'
+require 'mongo/error/transactions_not_supported'
 require 'mongo/error/unknown_payload_type'
 require 'mongo/error/unmet_dependency'
 require 'mongo/error/unsupported_option'

data/lib/mongo/grid/fs_bucket.rb

@@ -484,6 +484,12 @@ module Mongo
         end
       end
 
+      # Drop the collections that implement this bucket.
+      def drop
+        files_collection.drop
+        chunks_collection.drop
+      end
+
       private
 
       # @param [ Hash ] opts The options.

data/lib/mongo/monitoring/event/secure.rb

@@ -58,7 +58,7 @@ module Mongo
             # According to Command Monitoring spec,for hello/legacy hello commands
             # when speculativeAuthenticate is present, their commands AND replies
             # MUST be redacted from the events.
-            # See https://github.com/mongodb/specifications/blob/master/source/command-monitoring/command-monitoring.rst#security
+            # See https://github.com/mongodb/specifications/blob/master/source/command-logging-and-monitoring/command-logging-and-monitoring.rst#security
             true
           else
             false

data/lib/mongo/operation/create_search_indexes/op_msg.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Mongo
+  module Operation
+    class CreateSearchIndexes
+      # A MongoDB createSearchIndexes operation sent as an op message.
+      #
+      # @api private
+      class OpMsg < OpMsgBase
+        include ExecutableTransactionLabel
+
+        private
+
+        # Returns the command to send to the database, describing the
+        # desired createSearchIndexes operation.
+        #
+        # @param [ Mongo::Server ] _server the server that will receive the
+        #   command
+        #
+        # @return [ Hash ] the selector
+        def selector(_server)
+          {
+            createSearchIndexes: coll_name,
+            :$db => db_name,
+            indexes: indexes,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/mongo/operation/create_search_indexes.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'mongo/operation/create_search_indexes/op_msg'
+
+module Mongo
+  module Operation
+    # A MongoDB createSearchIndexes command operation.
+    #
+    # @api private
+    class CreateSearchIndexes
+      include Specifiable
+      include OpMsgExecutable
+    end
+  end
+end

data/lib/mongo/operation/drop_search_index/op_msg.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mongo
+  module Operation
+    class DropSearchIndex
+      # A MongoDB createSearchIndexes operation sent as an op message.
+      #
+      # @api private
+      class OpMsg < OpMsgBase
+        include ExecutableTransactionLabel
+
+        private
+
+        # Returns the command to send to the database, describing the
+        # desired dropSearchIndex operation.
+        #
+        # @param [ Mongo::Server ] _server the server that will receive the
+        #   command
+        #
+        # @return [ Hash ] the selector
+        def selector(_server)
+          {
+            dropSearchIndex: coll_name,
+            :$db => db_name,
+          }.tap do |sel|
+            sel[:id] = index_id if index_id
+            sel[:name] = index_name if index_name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongo/operation/drop_search_index.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'mongo/operation/drop_search_index/op_msg'
+
+module Mongo
+  module Operation
+    # A MongoDB dropSearchIndex command operation.
+    #
+    # @api private
+    class DropSearchIndex
+      include Specifiable
+      include OpMsgExecutable
+    end
+  end
+end

data/lib/mongo/operation/shared/executable.rb

@@ -15,6 +15,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require 'mongo/error'
+
 module Mongo
   module Operation
 
@@ -30,40 +32,42 @@ module Mongo
         session&.materialize_if_needed
         unpin_maybe(session, connection) do
           add_error_labels(connection, context) do
-            add_server_diagnostics(connection) do
-              get_result(connection, context, options).tap do |result|
-                if session
-                  if session.in_transaction? &&
-                    connection.description.load_balancer?
-                  then
-                    if session.pinned_connection_global_id
-                      unless session.pinned_connection_global_id == connection.global_id
-                        raise(
-                          Error::InternalDriverError,
-                          "Expected operation to use connection #{session.pinned_connection_global_id} but it used #{connection.global_id}"
-                        )
+            check_for_network_error do
+              add_server_diagnostics(connection) do
+                get_result(connection, context, options).tap do |result|
+                  if session
+                    if session.in_transaction? &&
+                      connection.description.load_balancer?
+                    then
+                      if session.pinned_connection_global_id
+                        unless session.pinned_connection_global_id == connection.global_id
+                          raise(
+                            Error::InternalDriverError,
+                            "Expected operation to use connection #{session.pinned_connection_global_id} but it used #{connection.global_id}"
+                          )
+                        end
+                      else
+                        session.pin_to_connection(connection.global_id)
+                        connection.pin
                       end
-                    else
-                      session.pin_to_connection(connection.global_id)
-                      connection.pin
                     end
-                  end
 
-                  if session.snapshot? && !session.snapshot_timestamp
-                    session.snapshot_timestamp = result.snapshot_timestamp
+                    if session.snapshot? && !session.snapshot_timestamp
+                      session.snapshot_timestamp = result.snapshot_timestamp
+                    end
                   end
-                end
 
-                if result.has_cursor_id? &&
-                  connection.description.load_balancer?
-                then
-                  if result.cursor_id == 0
-                    connection.unpin
-                  else
-                    connection.pin
+                  if result.has_cursor_id? &&
+                    connection.description.load_balancer?
+                  then
+                    if result.cursor_id == 0
+                      connection.unpin
+                    else
+                      connection.pin
+                    end
                   end
+                  process_result(result, connection)
                 end
-                process_result(result, connection)
               end
             end
           end
@@ -144,6 +148,18 @@ module Mongo
           connection.server.scan_semaphore.signal
         end
       end
+
+      NETWORK_ERRORS = [
+        Error::SocketError,
+        Error::SocketTimeoutError
+      ].freeze
+
+      def check_for_network_error
+        yield
+      rescue *NETWORK_ERRORS
+        session&.dirty!
+        raise
+      end
     end
   end
 end

data/lib/mongo/operation/shared/response_handling.rb

@@ -50,35 +50,33 @@ module Mongo
       #   the operation is performed.
       # @param [ Mongo::Operation::Context ] context The operation context.
       def add_error_labels(connection, context)
-        begin
-          yield
-        rescue Mongo::Error::SocketError => e
-          if context.in_transaction? && !context.committing_transaction?
-            e.add_label('TransientTransactionError')
-          end
-          if context.committing_transaction?
-            e.add_label('UnknownTransactionCommitResult')
-          end
+        yield
+      rescue Mongo::Error::SocketError => e
+        if context.in_transaction? && !context.committing_transaction?
+          e.add_label('TransientTransactionError')
+        end
+        if context.committing_transaction?
+          e.add_label('UnknownTransactionCommitResult')
+        end
 
-          maybe_add_retryable_write_error_label!(e, connection, context)
-
-          raise e
-        rescue Mongo::Error::SocketTimeoutError => e
-          maybe_add_retryable_write_error_label!(e, connection, context)
-          raise e
-        rescue Mongo::Error::OperationFailure => e
-          if context.committing_transaction?
-            if e.write_retryable? || e.wtimeout? || (e.write_concern_error? &&
-                !Session::UNLABELED_WRITE_CONCERN_CODES.include?(e.write_concern_error_code)
-            ) || e.max_time_ms_expired?
-              e.add_label('UnknownTransactionCommitResult')
-            end
+        maybe_add_retryable_write_error_label!(e, connection, context)
+
+        raise e
+      rescue Mongo::Error::SocketTimeoutError => e
+        maybe_add_retryable_write_error_label!(e, connection, context)
+        raise e
+      rescue Mongo::Error::OperationFailure => e
+        if context.committing_transaction?
+          if e.write_retryable? || e.wtimeout? || (e.write_concern_error? &&
+              !Session::UNLABELED_WRITE_CONCERN_CODES.include?(e.write_concern_error_code)
+          ) || e.max_time_ms_expired?
+            e.add_label('UnknownTransactionCommitResult')
           end
+        end
 
-          maybe_add_retryable_write_error_label!(e, connection, context)
+        maybe_add_retryable_write_error_label!(e, connection, context)
 
-          raise e
-        end
+        raise e
       end
 
       # Unpins the session and/or the connection if  the yielded to block