mongo 2.19.3 → 2.20.1

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

data/lib/mongo/retryable/base_worker.rb

@@ -49,7 +49,8 @@ module Mongo
 
       private
 
-      # Indicate which exception classes that are generally retryable. 
+      # Indicate which exception classes that are generally retryable
+      # when using modern retries mechanism.
       #
       # @return [ Array<Mongo:Error> ] Array of exception classes that are
       #   considered retryable.
@@ -58,18 +59,42 @@ module Mongo
           Error::ConnectionPerished,
           Error::ServerNotUsable,
           Error::SocketError,
-          Error::SocketTimeoutError
+          Error::SocketTimeoutError,
         ].freeze
       end
 
+      # Indicate which exception classes that are generally retryable
+      # when using legacy retries mechanism.
+      #
+      # @return [ Array<Mongo:Error> ] Array of exception classes that are
+      #   considered retryable.
+      def legacy_retryable_exceptions
+        [
+          Error::ConnectionPerished,
+          Error::ServerNotUsable,
+          Error::SocketError,
+          Error::SocketTimeoutError,
+          Error::PoolClearedError,
+          Error::PoolPausedError,
+        ].freeze
+      end
+
+
       # Tests to see if the given exception instance is of a type that can
-      # be retried.
+      # be retried with modern retry mechanism.
       #
       # @return [ true | false ] true if the exception is retryable.
       def is_retryable_exception?(e)
         retryable_exceptions.any? { |klass| klass === e }
       end
 
+      # Tests to see if the given exception instance is of a type that can
+      # be retried with legacy retry mechanism.
+      #
+      # @return [ true | false ] true if the exception is retryable.
+      def is_legacy_retryable_exception?(e)
+        legacy_retryable_exceptions.any? { |klass| klass === e }
+      end
       # Logs the given deprecation warning the first time it is called for a
       # given key; after that, it does nothing when given the same key.
       def deprecation_warning(key, warning)

data/lib/mongo/retryable/read_worker.rb

@@ -190,14 +190,15 @@ module Mongo
       #
       # @return [ Result ] The result of the operation.
       def modern_read_with_retry(session, server_selector, &block)
-        yield select_server(cluster, server_selector, session)
+        server = select_server(cluster, server_selector, session)
+        yield server
       rescue *retryable_exceptions, Error::OperationFailure, Auth::Unauthorized, Error::PoolError => e
         e.add_notes('modern retry', 'attempt 1')
         raise e if session.in_transaction?
         raise e if !is_retryable_exception?(e) && !e.write_retryable?
-        retry_read(e, session, server_selector, &block)
+        retry_read(e, session, server_selector, failed_server: server, &block)
       end
-  
+
       # Attempts to do a "legacy" read with retry. The operation will be
       # attempted multiple times, up to the client's `max_read_retries`
       # setting.
@@ -212,17 +213,18 @@ module Mongo
       def legacy_read_with_retry(session, server_selector, &block)
         attempt = attempt ? attempt + 1 : 1
         yield select_server(cluster, server_selector, session)
-      rescue *retryable_exceptions, Error::OperationFailure, Error::PoolError => e
+      rescue *legacy_retryable_exceptions, Error::OperationFailure => e
         e.add_notes('legacy retry', "attempt #{attempt}")
-        
-        if is_retryable_exception?(e)
+
+        if is_legacy_retryable_exception?(e)
+
           raise e if attempt > client.max_read_retries || session&.in_transaction?
         elsif e.retryable? && !session&.in_transaction?
           raise e if attempt > client.max_read_retries
         else
           raise e
         end
-        
+
         log_retry(e, message: 'Legacy read retry')
         sleep(client.read_retry_interval) unless is_retryable_exception?(e)
         retry
@@ -257,19 +259,21 @@ module Mongo
       #   being run on.
       # @param [ Mongo::ServerSelector::Selectable ] server_selector Server
       #   selector for the operation.
+      # @param [ Mongo::Server ] failed_server The server on which the original
+      #   operation failed.
       # @param [ Proc ] block The block to execute.
-      # 
+      #
       # @return [ Result ] The result of the operation.
-      def retry_read(original_error, session, server_selector, &block)
+      def retry_read(original_error, session, server_selector, failed_server: nil, &block)
         begin
-          server = select_server(cluster, server_selector, session)
+          server = select_server(cluster, server_selector, session, failed_server)
         rescue Error, Error::AuthError => e
           original_error.add_note("later retry failed: #{e.class}: #{e}")
           raise original_error
         end
-  
+
         log_retry(original_error, message: 'Read retry')
-  
+
         begin
           yield server, true
         rescue *retryable_exceptions => e
@@ -289,8 +293,6 @@ module Mongo
           raise original_error
         end
       end
-  
     end
-
   end
 end

data/lib/mongo/retryable/write_worker.rb

@@ -103,8 +103,9 @@ module Mongo
       def nro_write_with_retry(write_concern, context:, &block)
         session = context.session
         server = select_server(cluster, ServerSelector.primary, session)
-        
-        if session&.client.options[:retry_writes]
+        options = session&.client&.options || {}
+
+        if options[:retry_writes]
           begin
             server.with_connection(connection_global_id: context.connection_global_id) do |connection|
               yield connection, nil, context
@@ -218,7 +219,7 @@ module Mongo
       def modern_write_with_retry(session, server, context, &block)
         txn_num = nil
         connection_succeeded = false
-        
+
         server.with_connection(connection_global_id: context.connection_global_id) do |connection|
           connection_succeeded = true
 
@@ -240,7 +241,7 @@ module Mongo
 
         # 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), &block)
+        retry_write(e, txn_num, context: context.with(is_retry: true), failed_server: server, &block)
       end
 
       # Called after a failed write, this will retry the write no more than
@@ -250,9 +251,11 @@ module Mongo
       #   retry.
       # @param [ Number ] txn_num The transaction number.
       # @param [ Operation::Context ] context The context for the operation.
+      # @param [ Mongo::Server ] failed_server The server on which the original
+      #   operation failed.
       #
       # @return [ Result ] The result of the operation.
-      def retry_write(original_error, txn_num, context:, &block)
+      def retry_write(original_error, txn_num, context:, failed_server: nil, &block)
         session = context.session
 
         # We do not request a scan of the cluster here, because error handling
@@ -260,8 +263,8 @@ module Mongo
         # server description and/or topology as necessary (specifically,
         # a socket error or a not master error should have marked the respective
         # server unknown). Here we just need to wait for server selection.
-        server = select_server(cluster, ServerSelector.primary, session)
-        
+        server = select_server(cluster, ServerSelector.primary, session, failed_server)
+
         unless server.retry_writes?
           # Do not need to add "modern retry" here, it should already be on
           # the first exception.
@@ -275,7 +278,7 @@ module Mongo
           # special marker class to bypass the ordinarily applicable rescues.
           raise Error::RaiseOriginalError
         end
-        
+
         log_retry(original_error, message: 'Write retry')
         server.with_connection(connection_global_id: context.connection_global_id) do |connection|
           yield(connection, txn_num, context)

data/lib/mongo/retryable.rb

@@ -46,8 +46,8 @@ module Mongo
     # @api private
     #
     # @return [ Mongo::Server ] A server matching the server preference.
-    def select_server(cluster, server_selector, session)
-      server_selector.select_server(cluster, nil, session)
+    def select_server(cluster, server_selector, session, failed_server = nil)
+      server_selector.select_server(cluster, nil, session, deprioritized: [failed_server].compact)
     end
 
     # Returns the read worker for handling retryable reads.

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

@@ -18,9 +18,12 @@ module Mongo
   class Server
     class AppMetadata
       # Implements the logic from the handshake spec, for deducing and
-      # reporting the current FaaS environment in which the program is
+      # reporting the current environment in which the program is
       # executing.
       #
+      # This includes FaaS environment checks, as well as checks for the
+      # presence of a container (Docker) and/or orchestrator (Kubernetes).
+      #
       # @api private
       class Environment
         # Error class for reporting that too many discriminators were found
@@ -39,6 +42,10 @@ module Mongo
         # Error class for reporting that the value for a field is too long.
         class ValueTooLong < Mongo::Error; end
 
+        # The name and location of the .dockerenv file that will signal the
+        # presence of Docker.
+        DOCKERENV_PATH = '/.dockerenv'
+
         # This value is not explicitly specified in the spec, only implied to be
         # less than 512.
         MAXIMUM_VALUE_LENGTH = 500
@@ -102,9 +109,11 @@ module Mongo
         # if the environment contains invalid or contradictory state, it will
         # be initialized with {{name}} set to {{nil}}.
         def initialize
+          @fields = {}
           @error = nil
           @name = detect_environment
-          populate_fields
+          populate_faas_fields
+          detect_container
         rescue TooManyEnvironments => e
           self.error = "too many environments detected: #{e.message}"
         rescue MissingVariable => e
@@ -115,6 +124,23 @@ module Mongo
           self.error = "value for #{e.message} is too long"
         end
 
+        # Queries the detected container information.
+        #
+        # @return [ Hash | nil ] the detected container information, or
+        #    nil if no container was detected.
+        def container
+          fields[:container]
+        end
+
+        # Queries whether any environment information was able to be
+        # detected.
+        #
+        # @return [ true | false ] if any environment information was
+        #   detected.
+        def present?
+          @name || fields.any?
+        end
+
         # Queries whether the current environment is a valid FaaS environment.
         #
         # @return [ true | false ] whether the environment is a FaaS
@@ -159,14 +185,11 @@ module Mongo
           @name == 'vercel'
         end
 
-        # Compiles the detected environment information into a Hash. It will
-        # always include a {{name}} key, but may include other keys as well,
-        # depending on the detected FaaS environment. (See the handshake
-        # spec for details.)
+        # Compiles the detected environment information into a Hash.
         #
         # @return [ Hash ] the detected environment information.
         def to_h
-          fields.merge(name: name)
+          name ? fields.merge(name: name) : fields
         end
 
         private
@@ -192,6 +215,38 @@ module Mongo
           names.first
         end
 
+        # Looks for the presence of a container. Currently can detect
+        # Docker (by the existence of a .dockerenv file in the root
+        # directory) and Kubernetes (by the existence of the KUBERNETES_SERVICE_HOST
+        # environment variable).
+        def detect_container
+          runtime = docker_present? && 'docker'
+          orchestrator = kubernetes_present? && 'kubernetes'
+
+          return unless runtime || orchestrator
+
+          fields[:container] = {}
+          fields[:container][:runtime] = runtime if runtime
+          fields[:container][:orchestrator] = orchestrator if orchestrator
+        end
+
+        # Checks for the existence of a .dockerenv in the root directory.
+        def docker_present?
+          File.exist?(dockerenv_path)
+        end
+
+        # Implementing this as a method so that it can be mocked in tests, to
+        # test the presence or absence of Docker.
+        def dockerenv_path
+          DOCKERENV_PATH
+        end
+
+        # Checks for the presence of a non-empty KUBERNETES_SERVICE_HOST
+        # environment variable.
+        def kubernetes_present?
+          !ENV['KUBERNETES_SERVICE_HOST'].to_s.empty?
+        end
+
         # Determines whether the named environment variable exists, and (if
         # a pattern has been declared for that descriminator) whether the
         # pattern matches the value of the variable.
@@ -212,10 +267,10 @@ module Mongo
         # Extracts environment information from the current environment
         # variables, based on the detected FaaS environment. Populates the
         # {{@fields}} instance variable.
-        def populate_fields
+        def populate_faas_fields
           return unless name
 
-          @fields = FIELDS[name].each_with_object({}) do |(var, defn), fields|
+          FIELDS[name].each_with_object(@fields) do |(var, defn), fields|
             fields[defn[:field]] = extract_field(var, defn)
           end
         end

data/lib/mongo/server/app_metadata.rb

@@ -187,13 +187,14 @@ module Mongo
         }
       end
 
-      # Returns the environment doc describing the current FaaS environment.
+      # Returns the environment doc describing the current execution
+      # environment.
       #
-      # @return [ Hash | nil ] the environment doc (or nil if not in a FaaS
-      #   environment).
+      # @return [ Hash | nil ] the environment doc (or nil if no relevant
+      #    environment info was detected)
       def env_doc
         env = Environment.new
-        env.faas? ? env.to_h : nil
+        env.present? ? env.to_h : nil
       end
 
       def type

data/lib/mongo/server/description/features.rb

@@ -48,6 +48,7 @@ module Mongo
           # provided by the client during findAndModify operations, requiring the
           # driver to raise client-side errors when those options are provided.
           find_and_modify_option_validation: 8,
+          sharded_transactions: 8,
           transactions: 7,
           scram_sha_256: 7,
           array_filters: 6,

data/lib/mongo/server/pending_connection.rb

@@ -110,6 +110,24 @@ module Mongo
 
       private
 
+      # Sends the hello command to the server, then receive and deserialize
+      # the response.
+      #
+      # This method is extracted to be mocked in the tests.
+      #
+      # @param [ Protocol::Message ] Command that should be sent to a server
+      #   for handshake purposes.
+      #
+      # @return [ Mongo::Protocol::Reply ] Deserialized server response.
+      def get_handshake_response(hello_command)
+        @server.round_trip_time_averager.measure do
+          add_server_diagnostics do
+            socket.write(hello_command.serialize.to_s)
+            Protocol::Message.deserialize(socket, Protocol::Message::MAX_MESSAGE_SIZE)
+          end
+        end
+      end
+
       # @param [ BSON::Document | nil ] speculative_auth_doc The document to
       #   provide in speculativeAuthenticate field of handshake command.
       #
@@ -131,12 +149,7 @@ module Mongo
         doc = nil
         @server.handle_handshake_failure! do
           begin
-            response = @server.round_trip_time_averager.measure do
-              add_server_diagnostics do
-                socket.write(hello_command.serialize.to_s)
-                Protocol::Message.deserialize(socket, Protocol::Message::MAX_MESSAGE_SIZE)
-              end
-            end
+            response = get_handshake_response(hello_command)
             result = Operation::Result.new([response])
             result.validate!
             doc = result.documents.first

data/lib/mongo/server_selector/base.rb

@@ -164,6 +164,10 @@ module Mongo
       #   for mongos pinning. Added in version 2.10.0.
       # @param [ true | false ] write_aggregation Whether we need a server that
       #   supports writing aggregations (e.g. with $merge/$out) on secondaries.
+      # @param [ Array<Server> ] deprioritized A list of servers that should
+      #   be selected from only if no other servers are available. This is
+      #   used to avoid selecting the same server twice in a row when
+      #   retrying a command.
       #
       # @return [ Mongo::Server ] A server matching the server preference.
       #
@@ -174,8 +178,8 @@ module Mongo
       #   lint mode is enabled.
       #
       # @since 2.0.0
-      def select_server(cluster, ping = nil, session = nil, write_aggregation: false)
-        select_server_impl(cluster, ping, session, write_aggregation).tap do |server|
+      def select_server(cluster, ping = nil, session = nil, write_aggregation: false, deprioritized: [])
+        select_server_impl(cluster, ping, session, write_aggregation, deprioritized).tap do |server|
           if Lint.enabled? && !server.pool.ready?
             raise Error::LintError, 'Server selector returning a server with a pool which is not ready'
           end
@@ -183,7 +187,7 @@ module Mongo
       end
 
       # Parameters and return values are the same as for select_server.
-      private def select_server_impl(cluster, ping, session, write_aggregation)
+      private def select_server_impl(cluster, ping, session, write_aggregation, deprioritized)
         if cluster.topology.is_a?(Cluster::Topology::LoadBalanced)
           return cluster.servers.first
         end
@@ -266,7 +270,7 @@ module Mongo
             end
           end
 
-          server = try_select_server(cluster, write_aggregation: write_aggregation)
+          server = try_select_server(cluster, write_aggregation: write_aggregation, deprioritized: deprioritized)
 
           if server
             unless cluster.topology.compatible?
@@ -321,11 +325,15 @@ module Mongo
       #   an eligible server.
       # @param [ true | false ] write_aggregation Whether we need a server that
       #   supports writing aggregations (e.g. with $merge/$out) on secondaries.
+      # @param [ Array<Server> ] deprioritized A list of servers that should
+      #   be selected from only if no other servers are available. This is
+      #   used to avoid selecting the same server twice in a row when
+      #   retrying a command.
       #
       # @return [ Server | nil ] A suitable server, if one exists.
       #
       # @api private
-      def try_select_server(cluster, write_aggregation: false)
+      def try_select_server(cluster, write_aggregation: false, deprioritized: [])
         servers = if write_aggregation && cluster.replica_set?
           # 1. Check if ALL servers in cluster support secondary writes.
           is_write_supported = cluster.servers.reduce(true) do |res, server|
@@ -347,7 +355,7 @@ module Mongo
         # by the selector (e.g. for secondary preferred, the first
         # server may be a secondary and the second server may be primary)
         # and we should take the first server here respecting the order
-        server = servers.first
+        server = suitable_server(servers, deprioritized)
 
         if server
           if Lint.enabled?
@@ -418,6 +426,24 @@ module Mongo
 
       private
 
+      # Returns a server from the list of servers that is suitable for
+      # executing the operation.
+      #
+      # @param [ Array<Server> ] servers The candidate servers.
+      # @param [ Array<Server> ] deprioritized A list of servers that should
+      #  be selected from only if no other servers are available.
+      #
+      # @return [ Server | nil ] The suitable server or nil if no suitable
+      #  server is available.
+      def suitable_server(servers, deprioritized)
+        preferred = servers - deprioritized
+        if preferred.empty?
+          servers.first
+        else
+          preferred.first
+        end
+      end
+
       # Convert this server preference definition into a format appropriate
       #   for sending to a MongoDB server (i.e., as a command field).
       #

data/lib/mongo/session/server_session/dirtyable.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2024 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 Session
+    class ServerSession
+      # Functionality for manipulating and querying a session's
+      # "dirty" state, per the last paragraph at
+      # https://github.com/mongodb/specifications/blob/master/source/sessions/driver-sessions.rst#server-session-pool
+      #
+      #   If a driver has a server session pool and a network error is
+      #   encountered when executing any command with a ClientSession, the
+      #   driver MUST mark the associated ServerSession as dirty. Dirty server
+      #   sessions are discarded when returned to the server session pool. It is
+      #   valid for a dirty session to be used for subsequent commands (e.g. an
+      #   implicit retry attempt, a later command in a bulk write, or a later
+      #   operation on an explicit session), however, it MUST remain dirty for
+      #   the remainder of its lifetime regardless if later commands succeed.
+      #
+      # @api private
+      module Dirtyable
+        # Query whether the server session has been marked dirty or not.
+        #
+        # @return [ true | false ] the server session's dirty state
+        def dirty?
+          @dirty
+        end
+
+        # Mark the server session as dirty (the default) or clean.
+        #
+        # @param [ true | false ] mark whether the mark the server session
+        #   dirty or not.
+        def dirty!(mark = true)
+          @dirty = mark
+        end
+      end
+    end
+  end
+end

data/lib/mongo/session/server_session.rb

@@ -15,6 +15,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require 'mongo/session/server_session/dirtyable'
+
 module Mongo
 
   class Session
@@ -25,6 +27,7 @@ module Mongo
     #
     # @since 2.5.0
     class ServerSession
+      include Dirtyable
 
       # Regex for removing dashes from the UUID string.
       #

data/lib/mongo/session/session_pool.rb

@@ -25,21 +25,6 @@ module Mongo
     #
     # @since 2.5.0
     class SessionPool
-
-      # Create a SessionPool.
-      #
-      # @example
-      #   SessionPool.create(cluster)
-      #
-      # @param [ Mongo::Cluster ] cluster The cluster that will be associated with this
-      #   session pool.
-      #
-      # @since 2.5.0
-      def self.create(cluster)
-        pool = new(cluster)
-        cluster.instance_variable_set(:@session_pool, pool)
-      end
-
       # Initialize a SessionPool.
       #
       # @example
@@ -105,9 +90,7 @@ module Mongo
 
         @mutex.synchronize do
           prune!
-          unless about_to_expire?(session)
-            @queue.unshift(session)
-          end
+          @queue.unshift(session) if return_to_queue?(session)
         end
       end
 
@@ -136,6 +119,17 @@ module Mongo
 
       private
 
+      # Query whether the given session is okay to return to the
+      # pool's queue.
+      #
+      # @param [ Session::ServerSession ] session the session to query
+      #
+      # @return [ true | false ] whether to return the session to the
+      #   queue.
+      def return_to_queue?(session)
+        !session.dirty? && !about_to_expire?(session)
+      end
+
       def about_to_expire?(session)
         if session.nil?
           raise ArgumentError, 'session cannot be nil'