mongo 2.17.4 → 2.21.0

data/lib/mongo/server.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #
@@ -54,6 +54,15 @@ module Mongo
     #   done by this server. Note: setting this option to false will make
     #   the server non-functional. It is intended for use in tests which
     #   manually invoke SDAM state transitions.
+    # @option options [ true, false ] :populator_io For internal driver
+    #   use only. Set to false to prevent the populator threads from being
+    #   created and started in the server's connection pool. It is intended
+    #   for use in tests that also turn off monitoring_io, unless the populator
+    #   is explicitly needed. If monitoring_io is off, but the populator_io
+    #   is on, the populator needs to be manually closed at the end of the
+    #   test, since a cluster without monitoring is considered not connected,
+    #   and thus will not clean up the connection pool populator threads on
+    #   close.
     # @option options [ true | false ] :load_balancer Whether this server
     #   is a load balancer.
     # @option options [ String ] :connect The client connection mode.
@@ -71,7 +80,7 @@ module Mongo
         include Id
       end
       @scan_semaphore = DistinguishingSemaphore.new
-      @round_trip_time_averager = RoundTripTimeAverager.new
+      @round_trip_time_calculator = RoundTripTimeCalculator.new
       @description = Description.new(address, {},
         load_balancer: !!@options[:load_balancer],
         force_load_balancer: force_load_balancer?,
@@ -188,6 +197,7 @@ module Mongo
                    :max_message_size,
                    :tags,
                    :average_round_trip_time,
+                   :minimum_round_trip_time,
                    :mongos?,
                    :other?,
                    :primary?,
@@ -219,9 +229,9 @@ module Mongo
     # @api private
     attr_reader :scan_semaphore
 
-    # @return [ RoundTripTimeAverager ] Round trip time averager object.
+    # @return [ RoundTripTimeCalculator ] Round trip time calculator object.
     # @api private
-    attr_reader :round_trip_time_averager
+    attr_reader :round_trip_time_calculator
 
     # Is this server equal to another?
     #
@@ -267,25 +277,41 @@ module Mongo
       if monitor
         monitor.stop!
       end
-      _pool = @pool_lock.synchronize do
-        @pool
-      end
-      if _pool
-        # For backwards compatibility we disconnect/clear the pool rather
-        # than close it here. We also stop the populator which allows the
-        # the pool to continue providing connections but stops it from
-        # connecting in background on clients/servers that are in fact
-        # intended to be closed and no longer used.
-        begin
-          _pool.disconnect!(stop_populator: true)
-        rescue Error::PoolClosedError
-          # If the pool was already closed, we don't need to do anything here.
-        end
-      end
+
       @connected = false
+
+      # The current CMAP spec requires a pool to be mostly unusable
+      # if its server is unknown (or, therefore, disconnected).
+      # However any outstanding operations should continue to completion,
+      # and their connections need to be checked into the pool to be
+      # torn down. Because of this cleanup requirement we cannot just
+      # close the pool and set it to nil here, to be recreated the next
+      # time the server is discovered.
+      pool_internal&.clear
+
       true
     end
 
+    def close
+      if monitor
+        monitor.stop!
+      end
+
+      @connected = false
+
+      _pool = nil
+      @pool_lock.synchronize do
+        _pool, @pool = @pool, nil
+      end
+
+      # TODO: change this to _pool.close in RUBY-3174.
+      # Clear the pool. If the server is not unknown then the
+      # pool will stay ready. Stop the background populator thread.
+      _pool&.close(stay_ready: true)
+
+      nil
+    end
+
     # Whether the server is connected.
     #
     # @return [ true|false ] Whether the server is connected.
@@ -397,8 +423,29 @@ module Mongo
     #
     # @since 2.0.0
     def pool
+      if unknown?
+        raise Error::ServerNotUsable, address
+      end
+
       @pool_lock.synchronize do
-        @pool ||= ConnectionPool.new(self, options)
+        opts = connected? ? options : options.merge(populator_io: false)
+        @pool ||= ConnectionPool.new(self, opts).tap do |pool|
+          pool.ready
+        end
+      end
+    end
+
+    # Internal driver method to retrieve the connection pool for this server.
+    #
+    # Unlike +pool+, +pool_internal+ will not create a pool if one does not
+    # already exist.
+    #
+    # @return [ Server::ConnectionPool | nil ] The connection pool, if one exists.
+    #
+    # @api private
+    def pool_internal
+      @pool_lock.synchronize do
+        @pool
       end
     end
 
@@ -444,8 +491,12 @@ module Mongo
     # @return [ Object ] The result of the block execution.
     #
     # @since 2.3.0
-    def with_connection(service_id: nil, &block)
-      pool.with_connection(service_id: service_id, &block)
+    def with_connection(connection_global_id: nil, context: nil, &block)
+      pool.with_connection(
+        connection_global_id: connection_global_id,
+        context: context,
+        &block
+      )
     end
 
     # Handle handshake failure.
@@ -480,18 +531,15 @@ module Mongo
     rescue Mongo::Error::SocketTimeoutError
       # possibly cluster is slow, do not give up on it
       raise
-    rescue Mongo::Error::SocketError => e
-      # non-timeout network error
+    rescue Mongo::Error::SocketError, Auth::Unauthorized => e
+      # non-timeout network error or auth error, clear the pool and mark the
+      # topology as unknown
       unknown!(
         generation: e.generation,
         service_id: e.service_id,
         stop_push_monitor: true,
       )
       raise
-    rescue Auth::Unauthorized
-      # auth error, keep server description and topology as they are
-      pool.disconnect!
-      raise
     end
 
     # Whether the server supports modern read retries.
@@ -511,9 +559,15 @@ module Mongo
     # @note Retryable writes are only available on server versions 3.6+ and with
     #   sharded clusters or replica sets.
     #
+    # @note Some of the conditions in this method automatically return false for
+    #       for load balanced topologies. The conditions in this method should
+    #       always be true, since load-balanced topologies are only available on
+    #       MongoDB 5.0+, and not for standalone topologies. Therefore, we can
+    #       assume that retry writes are enabled.
+    #
     # @since 2.5.0
     def retry_writes?
-      !!(features.sessions_enabled? && logical_session_timeout && !standalone?)
+      !!(features.sessions_enabled? && logical_session_timeout && !standalone?) || load_balancer?
     end
 
     # Marks server unknown and publishes the associated SDAM event
@@ -532,8 +586,6 @@ module Mongo
     #   respective server is cleared. Set this option to true to keep the
     #   existing connection pool (required when handling not master errors
     #   on 4.2+ servers).
-    # @option options [ Object ] :service_id Discard state for the specified
-    #   service id only.
     # @option options [ TopologyVersion ] :topology_version Topology version
     #   of the error response that is causing the server to be marked unknown.
     # @option options [ true | false ] :stop_push_monitor Whether to stop
@@ -543,6 +595,8 @@ module Mongo
     #
     # @since 2.4.0, SDAM events are sent as of version 2.7.0
     def unknown!(options = {})
+      pool = pool_internal
+
       if load_balancer?
         # When the client is in load-balanced topology, servers (the one and
         # only that can be) starts out as a load balancer and stays as a
@@ -551,15 +605,18 @@ module Mongo
         # However, this method also clears connection pool for the server
         # when the latter is marked unknown, and this part needs to happen
         # when the server is a load balancer.
+        #
+        # It is possible for a load balancer server to not have a service id,
+        # for example if there haven't been any successful connections yet to
+        # this server, but the server can still be marked unknown if one
+        # of such connections failed midway through its establishment.
         if service_id = options[:service_id]
-          pool.disconnect!(service_id: service_id)
-        elsif Lint.enabled?
-          raise Error::LintError, 'Load balancer was asked to be marked unknown without a service id'
+          pool&.disconnect!(service_id: service_id)
         end
         return
       end
 
-      if options[:generation] && options[:generation] < pool.generation
+      if options[:generation] && options[:generation] < pool&.generation
         return
       end
 
@@ -591,17 +648,35 @@ module Mongo
 
     # @api private
     def update_description(description)
+      pool = pool_internal
+      if pool && !description.unknown?
+        pool.ready
+      end
       @description = description
     end
 
+    # Clear the servers description so that it is considered unknown and can be
+    # safely disconnected.
+    #
+    # @api private
+    def clear_description
+      @description = Mongo::Server::Description.new(address, {})
+    end
+
     # @param [ Object ] :service_id Close connections with the specified
     #   service id only.
+    # @param [ true | false ] :interrupt_in_use_connections Whether or not the
+    #   cleared connections should be interrupted as well.
     #
     # @api private
-    def clear_connection_pool(service_id: nil)
+    def clear_connection_pool(service_id: nil, interrupt_in_use_connections: false)
       @pool_lock.synchronize do
-        if @pool
-          @pool.disconnect!(service_id: service_id)
+        # A server being marked unknown after it is closed is technically
+        # incorrect but it does not meaningfully alter any state.
+        # Because historically the driver permitted servers to be marked
+        # unknown at any time, continue doing so even if the pool is closed.
+        if @pool && !@pool.closed?
+          @pool.disconnect!(service_id: service_id, interrupt_in_use_connections: interrupt_in_use_connections)
         end
       end
     end
@@ -627,5 +702,5 @@ require 'mongo/server/connection'
 require 'mongo/server/connection_pool'
 require 'mongo/server/description'
 require 'mongo/server/monitor'
-require 'mongo/server/round_trip_time_averager'
+require 'mongo/server/round_trip_time_calculator'
 require 'mongo/server/push_monitor'

data/lib/mongo/server_selector/base.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2020 MongoDB Inc.
 #
@@ -33,11 +33,11 @@ module Mongo
       #
       # @option options [ Integer ] :local_threshold The local threshold boundary for
       #  nearest selection in seconds.
-      # @option options [ Integer ] max_staleness The maximum replication lag,
+      # @option options [ Integer ] :max_staleness The maximum replication lag,
       #   in seconds, that a secondary can suffer and still be eligible for a read.
       #   A value of -1 is treated identically to nil, which is to not
       #   have a maximum staleness.
-      # @option options [ Hash | nil ] hedge A Hash specifying whether to enable hedged
+      # @option options [ Hash | nil ] :hedge A Hash specifying whether to enable hedged
       #   reads on the server. Hedged reads are not enabled by default. When
       #   specifying this option, it must be in the format: { enabled: true },
       #   where the value of the :enabled key is a boolean value.
@@ -164,6 +164,12 @@ 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.
+      # @param [ Float | nil ] :timeout Timeout in seconds for the operation,
+      #   if any.
       #
       # @return [ Mongo::Server ] A server matching the server preference.
       #
@@ -174,12 +180,35 @@ module Mongo
       #   lint mode is enabled.
       #
       # @since 2.0.0
-      def select_server(cluster, ping = nil, session = nil, write_aggregation: false)
+      def select_server(
+        cluster,
+        ping = nil,
+        session = nil,
+        write_aggregation: false,
+        deprioritized: [],
+        timeout: nil
+      )
+        select_server_impl(cluster, ping, session, write_aggregation, deprioritized, timeout).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
+        end
+      end
+
+      # Parameters and return values are the same as for select_server, only
+      # the +timeout+ param is renamed to +csot_timeout+.
+      private def select_server_impl(cluster, ping, session, write_aggregation, deprioritized, csot_timeout)
         if cluster.topology.is_a?(Cluster::Topology::LoadBalanced)
           return cluster.servers.first
         end
 
-        server_selection_timeout = cluster.options[:server_selection_timeout] || SERVER_SELECTION_TIMEOUT
+        timeout = cluster.options[:server_selection_timeout] || SERVER_SELECTION_TIMEOUT
+
+        server_selection_timeout = if csot_timeout && csot_timeout > 0
+                                     [timeout, csot_timeout].min
+                                   else
+                                     timeout
+                                   end
 
         # Special handling for zero timeout: if we have to select a server,
         # and the timeout is zero, fail immediately (since server selection
@@ -245,7 +274,19 @@ module Mongo
 =end
 
         loop do
-          server = try_select_server(cluster, write_aggregation: write_aggregation)
+          if Lint.enabled?
+            cluster.servers.each do |server|
+              # TODO: Add this back in RUBY-3174.
+              # if !server.unknown? && !server.connected?
+              #   raise Error::LintError, "Server #{server.summary} is known but is not connected"
+              # end
+              if !server.unknown? && !server.pool.ready?
+                raise Error::LintError, "Server #{server.summary} is known but has non-ready pool"
+              end
+            end
+          end
+
+          server = try_select_server(cluster, write_aggregation: write_aggregation, deprioritized: deprioritized)
 
           if server
             unless cluster.topology.compatible?
@@ -300,11 +341,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|
@@ -326,7 +371,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?
@@ -397,6 +442,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).
       #
@@ -591,9 +654,9 @@ module Mongo
       # state resulting from SDAM will immediately wake up this method and
       # cause it to return.
       #
-      # If the cluster des not have a server selection semaphore, waits
+      # If the cluster does not have a server selection semaphore, waits
       # the smaller of 0.25 seconds and the specified remaining time.
-      # This functionality is provided for backwards compatibilty only for
+      # This functionality is provided for backwards compatibility only for
       # applications directly invoking the server selection process.
       # If lint mode is enabled and the cluster does not have a server
       # selection semaphore, Error::LintError will be raised.
@@ -604,9 +667,9 @@ module Mongo
         if cluster.server_selection_semaphore
           # Since the semaphore may have been signaled between us checking
           # the servers list earlier and the wait call below, we should not
-          # wait for the full remaining time - wait for up to 1 second, then
+          # wait for the full remaining time - wait for up to 0.5 second, then
           # recheck the state.
-          cluster.server_selection_semaphore.wait([time_remaining, 1].min)
+          cluster.server_selection_semaphore.wait([time_remaining, 0.5].min)
         else
           if Lint.enabled?
             raise Error::LintError, 'Waiting for server selection without having a server selection semaphore'

data/lib/mongo/server_selector/nearest.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #

data/lib/mongo/server_selector/primary.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #

data/lib/mongo/server_selector/primary_preferred.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #

data/lib/mongo/server_selector/secondary.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #

data/lib/mongo/server_selector/secondary_preferred.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #

data/lib/mongo/server_selector.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2017-2020 MongoDB Inc.
 #
@@ -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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2017-2020 MongoDB Inc.
 #
@@ -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
@@ -99,11 +84,13 @@ module Mongo
       #
       # @since 2.5.0
       def checkin(session)
+        if session.nil?
+          raise ArgumentError, 'session cannot be nil'
+        end
+
         @mutex.synchronize do
           prune!
-          unless about_to_expire?(session)
-            @queue.unshift(session)
-          end
+          @queue.unshift(session) if return_to_queue?(session)
         end
       end
 
@@ -132,7 +119,22 @@ 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'
+        end
+
         # Load balancers spec explicitly requires to ignore the logical session
         # timeout value.
         # No rationale is provided as of the time of this writing.