mongo 2.22.0 → 2.24.0

data/lib/mongo/retryable/write_worker.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 # Copyright (C) 2015-2023 MongoDB Inc.
 #
@@ -19,7 +18,6 @@ require 'mongo/retryable/base_worker'
 
 module Mongo
   module Retryable
-
     # Implements the logic around retrying write operations.
     #
     # @api private
@@ -62,7 +60,7 @@ module Mongo
       # @return [ Result ] The result of the operation.
       #
       # @since 2.1.0
-      def write_with_retry(write_concern, ending_transaction: false, context:, &block)
+      def write_with_retry(write_concern, context:, ending_transaction: false, &block)
         session = context.session
 
         ensure_valid_state!(ending_transaction, session)
@@ -104,19 +102,46 @@ module Mongo
       #   write should be sent.
       # @yieldparam [ nil ] txn_num nil as transaction number.
       # @yieldparam [ Operation::Context ] context The operation context.
-      def nro_write_with_retry(write_concern, context:, &block)
+      def nro_write_with_retry(_write_concern, context:, &block)
         session = context.session
         server = select_server(cluster, ServerSelector.primary, session)
         options = session&.client&.options || {}
 
         if options[:retry_writes]
+          error_count = 0
+          error_to_raise = nil
           begin
             server.with_connection(connection_global_id: context.connection_global_id) do |connection|
               yield connection, nil, context
             end
+          rescue Error::TimeoutError
+            raise
           rescue *retryable_exceptions, Error::PoolError, Error::OperationFailure::Family => e
-            e.add_note('retries disabled')
-            raise e
+            if retryable_overload_error?(e)
+              error_count += 1
+              error_to_raise ||= e
+              unless e.respond_to?(:label?) && e.label?('NoWritesPerformed')
+                error_to_raise = e
+              end
+              delay = retry_policy.backoff_delay(error_count)
+              raise error_to_raise unless retry_policy.should_retry_overload?(error_count, delay, context: context)
+
+              log_retry(e, message: 'Write retry (overload backoff)')
+              sleep(delay)
+              begin
+                server = select_server(
+                  cluster, ServerSelector.primary, session, server,
+                  error: e, timeout: context.remaining_timeout_sec
+                )
+              rescue Error, Error::AuthError => select_err
+                error_to_raise.add_note("later retry failed: #{select_err.class}: #{select_err}")
+                raise error_to_raise
+              end
+              retry
+            else
+              e.add_note('retries disabled')
+              raise e
+            end
           end
         else
           legacy_write_with_retry(server, context: context, &block)
@@ -134,11 +159,7 @@ module Mongo
       def retry_write_allowed?(session, write_concern)
         return false unless session&.retry_writes?
 
-        if write_concern.nil?
-          true
-        else
-          WriteConcern.get(write_concern).acknowledged?
-        end
+        write_concern.nil? || WriteConcern.get(write_concern).acknowledged?
       end
 
       private
@@ -150,9 +171,9 @@ module Mongo
       # @param [ nil | Mongo::Session ] session The session that the operation
       #   is being run on (if any).
       def ensure_valid_state!(ending_transaction, session)
-        if ending_transaction && !session
-          raise ArgumentError, 'Cannot end a transaction without a session'
-        end
+        return unless ending_transaction && !session
+
+        raise ArgumentError, 'Cannot end a transaction without a session'
       end
 
       # Implements legacy write retrying functionality by yielding to the passed
@@ -199,16 +220,13 @@ module Mongo
           e.add_note('legacy retry')
           e.add_note("attempt #{attempt}")
           server = nil
-          if attempt > client.max_write_retries
-            raise e
-          end
-          if e.label?('RetryableWriteError')
-            log_retry(e, message: 'Legacy write retry')
-            cluster.scan!(false)
-            retry
-          else
-            raise e
-          end
+          raise e if attempt > client.max_write_retries
+
+          raise e unless e.label?('RetryableWriteError')
+
+          log_retry(e, message: 'Legacy write retry')
+          cluster.scan!(false)
+          retry
         end
       end
 
@@ -232,6 +250,7 @@ module Mongo
       def modern_write_with_retry(session, server, context, &block)
         txn_num = nil
         connection_succeeded = false
+        was_starting = false
 
         server.with_connection(
           connection_global_id: context.connection_global_id,
@@ -241,6 +260,7 @@ module Mongo
 
           session.materialize_if_needed
           txn_num = session.in_transaction? ? session.txn_num : session.next_txn_num
+          was_starting = session.starting_transaction?
 
           # The context needs to be duplicated here because we will be using
           # it later for the retry as well.
@@ -249,15 +269,28 @@ module Mongo
       rescue *retryable_exceptions, Error::PoolError, Auth::Unauthorized, Error::OperationFailure::Family => e
         e.add_notes('modern retry', 'attempt 1')
 
-        if e.is_a?(Error::OperationFailure::Family)
-          ensure_retryable!(e)
-        else
-          ensure_labeled_retryable!(e, connection_succeeded, session)
+        is_overload = retryable_overload_error?(e)
+        unless is_overload
+          if e.is_a?(Error::OperationFailure::Family)
+            ensure_retryable!(e)
+          else
+            ensure_labeled_retryable!(e, connection_succeeded, session)
+          end
         end
 
-        # Context#with creates a new context, which is not necessary here
-        # but the API is less prone to misuse this way.
-        retry_write(e, txn_num, context: context.with(is_retry: true), failed_server: server, &block)
+        retry_context = context.with(is_retry: true)
+
+        if is_overload
+          overload_write_retry(e, session, txn_num,
+                               context: retry_context.with(overload_only_retry: true),
+                               failed_server: server, error_count: 1,
+                               was_starting_transaction: was_starting,
+                               &block)
+        else
+          # Context#with creates a new context, which is not necessary here
+          # but the API is less prone to misuse this way.
+          retry_write(e, txn_num, context: retry_context, failed_server: server, &block)
+        end
       end
 
       # Called after a failed write, this will retry the write no more than
@@ -272,6 +305,7 @@ module Mongo
       #
       # @return [ Result ] The result of the operation.
       def retry_write(original_error, txn_num, context:, failed_server: nil, &block)
+        failed_error ||= original_error
         context&.check_timeout!
 
         session = context.session
@@ -286,6 +320,7 @@ module Mongo
           ServerSelector.primary,
           session,
           failed_server,
+          error: failed_error,
           timeout: context.remaining_timeout_sec
         )
 
@@ -296,7 +331,7 @@ module Mongo
 
           # When we want to raise the original error, we must not run the
           # rescue blocks below that add diagnostics because the diagnostics
-          # added would either be rendundant (e.g. modern retry note) or wrong
+          # added would either be redundant (e.g. modern retry note) or wrong
           # (e.g. "attempt 2", we are raising the exception produced in the
           # first attempt and haven't attempted the second time). Use the
           # special marker class to bypass the ordinarily applicable rescues.
@@ -309,12 +344,24 @@ module Mongo
           yield(connection, txn_num, context)
         end
       rescue *retryable_exceptions, Error::PoolError => e
+        if retryable_overload_error?(e)
+          e.add_notes('modern retry', "attempt #{attempt}")
+          return overload_write_retry(e, context.session, txn_num,
+                                      context: context, failed_server: server, error_count: attempt, was_starting_transaction: false, &block)
+        end
         maybe_fail_on_retryable(e, original_error, context, attempt)
         failed_server = server
+        failed_error = e
         retry
       rescue Error::OperationFailure::Family => e
+        if retryable_overload_error?(e)
+          e.add_notes('modern retry', "attempt #{attempt}")
+          return overload_write_retry(e, context.session, txn_num,
+                                      context: context, failed_server: server, error_count: attempt, was_starting_transaction: false, &block)
+        end
         maybe_fail_on_operation_failure(e, original_error, context, attempt)
         failed_server = server
+        failed_error = e
         retry
       rescue Mongo::Error::TimeoutError
         raise
@@ -324,41 +371,93 @@ module Mongo
         raise original_error
       end
 
-      # Retry writes on MMAPv1 should raise an actionable error; append actionable
-      # information to the error message and preserve the backtrace.
-      def raise_unsupported_error(e)
-        new_error = Error::OperationFailure.new("#{e.class}: #{e} "\
-          "This MongoDB deployment does not support retryable writes. Please add "\
-          "retryWrites=false to your connection string or use the retry_writes: false Ruby client option")
-        new_error.set_backtrace(e.backtrace)
-        raise new_error
+      # Retry loop for overload write errors with exponential backoff.
+      #
+      # Per the client-backpressure spec, backoff is applied if and only
+      # if the error triggering the retry is an overload error. Non-overload
+      # retryable errors that occur within this loop are retried immediately
+      # (without backoff) but still count toward MAX_RETRIES.
+      def overload_write_retry(last_error, session, txn_num, context:, failed_server:, error_count:,
+                               was_starting_transaction: false)
+        # Track the error to return per the NoWritesPerformed spec rules:
+        # - first error is always saved
+        # - only update when a new error does NOT have NoWritesPerformed
+        error_to_raise = last_error
+        last_was_overload = true
+
+        loop do
+          delay = last_was_overload ? retry_policy.backoff_delay(error_count) : 0
+          raise error_to_raise unless retry_policy.should_retry_overload?(error_count, delay, context: context)
+
+          log_retry(last_error, message: 'Write retry (overload backoff)')
+          sleep(delay) if last_was_overload
+
+          begin
+            server = select_server(
+              cluster, ServerSelector.primary, session, failed_server,
+              error: last_error,
+              timeout: context.remaining_timeout_sec
+            )
+          rescue Error, Error::AuthError => e
+            error_to_raise.add_note("later retry failed: #{e.class}: #{e}")
+            raise error_to_raise
+          end
+
+          unless server.retry_writes?
+            error_to_raise.add_note('did not retry because server does not support retryable writes')
+            raise error_to_raise
+          end
+
+          begin
+            session.revert_to_starting_transaction! if was_starting_transaction
+            context.check_timeout!
+            result = server.with_connection(connection_global_id: context.connection_global_id) do |connection|
+              yield connection, txn_num, context
+            end
+            return result
+          rescue Error::TimeoutError
+            raise
+          rescue *retryable_exceptions, Error::PoolError, Error::OperationFailure::Family => e
+            error_count += 1
+            e.add_notes('modern retry', "attempt #{error_count}")
+            is_overload = retryable_overload_error?(e)
+            if e.is_a?(Error::OperationFailure::Family)
+              raise e unless is_overload || (e.label?('RetryableWriteError') && !e.label?('NoWritesPerformed'))
+            else
+              raise e unless is_overload || e.write_retryable?
+            end
+            unless e.respond_to?(:label?) && e.label?('NoWritesPerformed')
+              error_to_raise = e
+            end
+            last_was_overload = is_overload
+            context = context.with(overload_only_retry: false) unless is_overload
+            failed_server = server
+            last_error = e
+          rescue Error, Error::AuthError => e
+            error_to_raise.add_note("later retry failed: #{e.class}: #{e}")
+            raise error_to_raise
+          end
+        end
       end
 
       # Make sure the exception object is labeled 'RetryableWriteError'. If it
       # isn't, and should not be, re-raise the exception.
       def ensure_labeled_retryable!(e, connection_succeeded, session)
-        if !e.label?('RetryableWriteError')
-          # If there was an error before the connection was successfully
-          # checked out and connected, there was no connection present to use
-          # for adding labels. Therefore, we should check if it is retryable,
-          # and if it is, add the label and retry it.
-          if !connection_succeeded && !session.in_transaction? && e.write_retryable?
-            e.add_label('RetryableWriteError')
-          else
-            raise e
-          end
-        end
+        return if e.label?('RetryableWriteError')
+        # If there was an error before the connection was successfully
+        # checked out and connected, there was no connection present to use
+        # for adding labels. Therefore, we should check if it is retryable,
+        # and if it is, add the label and retry it.
+        raise e unless !connection_succeeded && !session.in_transaction? && e.write_retryable?
+
+        e.add_label('RetryableWriteError')
       end
 
       # Make sure the exception object supports retryable writes. If it does,
       # make sure it has been appropriately labeled. If either condition fails,
       # raise an exception.
       def ensure_retryable!(e)
-        if e.unsupported_retryable_write?
-          raise_unsupported_error(e)
-        elsif !e.label?('RetryableWriteError')
-          raise e
-        end
+        raise e unless e.label?('RetryableWriteError')
       end
 
       # Raise either e, or original_error, depending on whether e is

data/lib/mongo/retryable.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 # Copyright (C) 2015-2020 MongoDB Inc.
 #
@@ -15,11 +14,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require 'mongo/retryable/backpressure'
+require 'mongo/retryable/retry_policy'
 require 'mongo/retryable/read_worker'
 require 'mongo/retryable/write_worker'
 
 module Mongo
-
   # Defines basic behavior around retrying operations.
   #
   # @since 2.1.0
@@ -28,14 +28,14 @@ module Mongo
 
     # Delegate the public read_with_retry methods to the read_worker
     def_delegators :read_worker,
-      :read_with_retry_cursor,
-      :read_with_retry,
-      :read_with_one_retry
+                   :read_with_retry_cursor,
+                   :read_with_retry,
+                   :read_with_one_retry
 
     # Delegate the public write_with_retry methods to the write_worker
     def_delegators :write_worker,
-      :write_with_retry,
-      :nro_write_with_retry
+                   :write_with_retry,
+                   :nro_write_with_retry
 
     # This is a separate method to make it possible for the test suite to
     # assert that server selection is performed during retry attempts.
@@ -46,16 +46,37 @@ module Mongo
     # @api private
     #
     # @return [ Mongo::Server ] A server matching the server preference.
-    def select_server(cluster, server_selector, session, failed_server = nil, timeout: nil)
+    def select_server(cluster, server_selector, session, failed_server = nil, error: nil, timeout: nil)
+      deprioritized = if failed_server && deprioritize_server?(cluster, error)
+                        [ failed_server ]
+                      else
+                        []
+                      end
       server_selector.select_server(
         cluster,
         nil,
         session,
-        deprioritized: [failed_server].compact,
+        deprioritized: deprioritized,
         timeout: timeout
       )
     end
 
+    private
+
+    # Whether the failed server should be deprioritized during server
+    # selection for a retry attempt. For sharded and load-balanced
+    # topologies, servers are always deprioritized on any retryable error.
+    # For replica sets, servers are deprioritized on overload errors only
+    # when enableOverloadRetargeting is enabled.
+    def deprioritize_server?(cluster, error)
+      return true if cluster.sharded? || cluster.load_balanced?
+      return false unless client.options[:enable_overload_retargeting]
+
+      error.respond_to?(:label?) && error.label?('SystemOverloadedError')
+    end
+
+    public
+
     # Returns the read worker for handling retryable reads.
     #
     # @api private
@@ -75,5 +96,45 @@ module Mongo
     def write_worker
       @write_worker ||= WriteWorker.new(self)
     end
+
+    # Wraps an operation with overload retry logic. On overload errors
+    # (SystemOverloadedError + RetryableError), retries the block with
+    # exponential backoff up to MAX_RETRIES times.
+    #
+    # The block should include server selection so it is re-done on retry.
+    # For cursor operations (getMore), the same server is reused since the
+    # cursor is pinned.
+    #
+    # @param [ Operation::Context | nil ] context The operation context
+    #   for CSOT deadline checking.
+    # @param [ true | false ] retry_enabled Whether overload retries are
+    #   permitted. When false, overload errors are raised immediately
+    #   without retrying (used when retryReads/retryWrites is disabled).
+    #
+    # @return [ Object ] The result of the block.
+    #
+    # @api private
+    def with_overload_retry(context: nil, retry_enabled: true)
+      return yield unless retry_enabled
+
+      error_count = 0
+      loop do
+        result = yield
+
+        return result
+      rescue Error::TimeoutError
+        raise
+      rescue Error::OperationFailure::Family => e
+        raise e unless e.label?('SystemOverloadedError') && e.label?('RetryableError')
+
+        error_count += 1
+        policy = client.retry_policy
+        delay = policy.backoff_delay(error_count)
+        raise e unless policy.should_retry_overload?(error_count, delay, context: context)
+
+        Logger.logger.warn("Overload retry due to: #{e.class.name}: #{e.message}")
+        sleep(delay)
+      end
+    end
   end
 end

data/lib/mongo/search_index/view.rb

@@ -4,6 +4,7 @@ module Mongo
   module SearchIndex
     # A class representing a view of search indexes.
     class View
+      extend Forwardable
       include Enumerable
       include Retryable
       include Collection::Helpers
@@ -21,6 +22,8 @@ module Mongo
       #   when querying the available indexes.
       attr_reader :aggregate_options
 
+      def_delegators :@collection, :tracer
+
       # Create the new search index view.
       #
       # @param [ Collection ] collection The collection.
@@ -46,23 +49,33 @@ module Mongo
       #
       # @param [ Hash ] definition The definition of the search index.
       # @param [ nil | String ] name The name to give the new search index.
+      # @param [ String ] type The type of the search index. Possible values
+      #   are 'search' and 'vectorSearch'. The default is 'search'.
       #
       # @return [ String ] the name of the new search index.
       def create_one(definition, name: nil, type: 'search')
-        create_many([ { name: name, definition: definition, type: type } ]).first
+        spec = { definition: definition, type: type }.tap do |sp|
+          sp[:name] = name unless name.nil?
+        end
+        create_many([ spec ]).first
       end
 
       # Create multiple search indexes with a single command.
       #
       # @param [ Array<Hash> ] indexes The description of the indexes to
       #   create. Each element of the list must be a hash with a definition
-      #   key, and an optional name key.
+      #   key, an optional name key, and an optional type key. The type key
+      #   must be one of 'search' or 'vectorSearch'. The default is 'search'.
       #
       # @return [ Array<String> ] the names of the new search indexes.
       def create_many(indexes)
         spec = spec_with(indexes: indexes.map { |v| validate_search_index!(v) })
-        result = Operation::CreateSearchIndexes.new(spec).execute(next_primary, context: execution_context)
-        result.first['indexesCreated'].map { |idx| idx['name'] }
+        operation = Operation::CreateSearchIndexes.new(spec)
+        context = execution_context
+        tracer.trace_operation(operation, context, op_name: 'createSearchIndexes') do
+          result = operation.execute(next_primary, context: context)
+          result.first['indexesCreated'].map { |idx| idx['name'] }
+        end
       end
 
       # Drop the search index with the given id, or name. One or the other must
@@ -78,16 +91,19 @@ module Mongo
 
         spec = spec_with(index_id: id, index_name: name)
         op = Operation::DropSearchIndex.new(spec)
+        context = execution_context
 
-        # per the spec:
-        # Drivers MUST suppress NamespaceNotFound errors for the
-        # ``dropSearchIndex`` helper.  Drop operations should be idempotent.
-        do_drop(op, nil, execution_context)
+        tracer.trace_operation(op, context, op_name: 'dropSearchIndex') do
+          # per the spec:
+          # Drivers MUST suppress NamespaceNotFound errors for the
+          # ``dropSearchIndex`` helper.  Drop operations should be idempotent.
+          do_drop(op, nil, context)
+        end
       end
 
       # Iterate over the search indexes.
       #
-      # @param [ Proc ] block if given, each search index will be yieleded to
+      # @param [ Proc ] block if given, each search index will be yielded to
       #    the block.
       #
       # @return [ self | Enumerator ] if a block is given, self is returned.
@@ -124,7 +140,11 @@ module Mongo
         validate_id_or_name!(id, name)
 
         spec = spec_with(index_id: id, index_name: name, index: definition)
-        Operation::UpdateSearchIndex.new(spec).execute(next_primary, context: execution_context)
+        op = Operation::UpdateSearchIndex.new(spec)
+        context = execution_context
+        tracer.trace_operation(op, context, op_name: 'updateSearchIndex') do
+          op.execute(next_primary, context: context)
+        end
       end
 
       # The following methods are to make the view act more like an array,

data/lib/mongo/semaphore.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 # Copyright (C) 2018-2020 MongoDB Inc.
 #

data/lib/mongo/server/app_metadata/environment.rb

@@ -100,7 +100,7 @@ module Mongo
         # @return [ String | nil ] the error message explaining why a valid
         #   FaaS environment was not detected, or nil if no error occurred.
         #
-        # @note These error messagess are not to be propogated to the
+        # @note These error messages are not to be propagated to the
         #   user; they are intended only for troubleshooting and debugging.)
         attr_reader :error
 
@@ -194,7 +194,7 @@ module Mongo
 
         private
 
-        # Searches the DESCRIMINATORS list to see which (if any) apply to
+        # Searches the DISCRIMINATORS list to see which (if any) apply to
         # the current environment.
         #
         # @return [ String | nil ] the name of the detected FaaS provider.
@@ -248,7 +248,7 @@ module Mongo
         end
 
         # Determines whether the named environment variable exists, and (if
-        # a pattern has been declared for that descriminator) whether the
+        # a pattern has been declared for that discriminator) whether the
         # pattern matches the value of the variable.
         #
         # @param [ String ] var the name of the environment variable

data/lib/mongo/server/app_metadata/platform.rb

@@ -34,21 +34,34 @@ module Mongo
           @metadata = metadata
         end
 
+        # Queries whether the current runtime is Ruby MRI or not.
+        #
+        # @return [ true | false ] whether the runtime is Ruby MRI or not.
+        def mri?
+          RUBY_ENGINE == 'ruby'
+        end
+
         # Queries whether the current runtime is JRuby or not.
         #
         # @return [ true | false ] whether the runtime is JRuby or not.
         def jruby?
-          BSON::Environment.jruby?
+          RUBY_ENGINE == 'jruby'
+        end
+
+        ENGINE_NAMES = { 'jruby' => 'JRuby', 'truffleruby' => 'TruffleRuby' }.freeze
+
+        def engine_name
+          ENGINE_NAMES[RUBY_ENGINE] || RUBY_ENGINE
         end
 
         # Returns the list of Ruby versions that identify this runtime.
         #
         # @return [ Array<String> ] the list of ruby versions
         def ruby_versions
-          if jruby?
-            [ "JRuby #{JRUBY_VERSION}", "like Ruby #{RUBY_VERSION}" ]
-          else
+          if mri?
             [ "Ruby #{RUBY_VERSION}" ]
+          else
+            [ "#{engine_name} #{RUBY_ENGINE_VERSION}", "like Ruby #{RUBY_VERSION}" ]
           end
         end
 

data/lib/mongo/server/app_metadata.rb

@@ -46,8 +46,7 @@ module Mongo
       #
       # @param [ Hash ] options Metadata options.
       # @option options [ String, Symbol ] :app_name Application name that is
-      #   printed to the mongod logs upon establishing a connection in server
-      #   versions >= 3.4.
+      #   printed to the mongod logs upon establishing a connection
       # @option options [ Symbol ] :auth_mech The authentication mechanism to
       #   use. One of :mongodb_cr, :mongodb_x509, :plain, :scram, :scram256
       # @option options [ String ] :auth_source The source to authenticate from.
@@ -57,7 +56,6 @@ module Mongo
       #   driver only supports 'zstd', 'snappy' and 'zlib'.
       # @option options [ String ] :platform Platform information to include in
       #   the metadata printed to the mongod logs upon establishing a connection
-      #   in server versions >= 3.4.
       # @option options [ Symbol ] :purpose The purpose of this connection.
       # @option options [ Hash ] :server_api The requested server API version.
       #   This hash can have the following items:
@@ -97,7 +95,7 @@ module Mongo
 
       # @return [ Hash | nil ] The requested server API version.
       #
-      #   Thes hash can have the following items:
+      #   This hash can have the following items:
       #   - *:version* -- string
       #   - *:strict* -- boolean
       #   - *:deprecation_errors* -- boolean
@@ -132,6 +130,7 @@ module Mongo
             doc[:driver] = driver_doc
             doc[:os] = os_doc
             doc[:platform] = platform_string
+            doc[:backpressure] = true
             env_doc.tap { |env| doc[:env] = env if env }
           end
       end
@@ -139,7 +138,7 @@ module Mongo
       private
 
       # Check whether it is possible to build a valid app metadata document
-      # with params provided on intialization.
+      # with params provided on initialization.
       #
       # @raise [ Error::InvalidApplicationName ] When the metadata are invalid.
       def validate!