mongo 2.19.1 → 2.21.0

data/lib/mongo/server_selector/base.rb

@@ -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,21 +180,35 @@ 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: [],
+        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.
-      private def select_server_impl(cluster, ping, session, write_aggregation)
+      # 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
@@ -266,7 +286,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 +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|
@@ -347,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?
@@ -418,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).
       #
@@ -612,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.

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'

data/lib/mongo/session.rb

@@ -57,6 +57,12 @@ module Mongo
     #
     # @option options [ true|false ] :causal_consistency Whether to enable
     #   causal consistency for this session.
+    # @option options [ Integer ] :default_timeout_ms The timeoutMS value for
+    #   the following operations executed on the session:
+    #   - commitTransaction
+    #   - abortTransaction
+    #   - withTransaction
+    #   - endSession
     # @option options [ Hash ] :default_transaction_options Options to pass
     #   to start_transaction by default, can contain any of the options that
     #   start_transaction accepts.
@@ -96,6 +102,7 @@ module Mongo
       @options = options.dup.freeze
       @cluster_time = nil
       @state = NO_TRANSACTION_STATE
+      @with_transaction_deadline = nil
     end
 
     # @return [ Hash ] The options for this session.
@@ -123,6 +130,23 @@ module Mongo
     # @since 2.5.0
     attr_reader :operation_time
 
+    # Sets the dirty state to the given value for the underlying server
+    # session. If there is no server session, this does nothing.
+    #
+    # @param [ true | false ] mark whether to mark the server session as
+    #   dirty, or not.
+    def dirty!(mark = true)
+      @server_session&.dirty!(mark)
+    end
+
+    # @return [ true | false | nil ] whether the underlying server session is
+    #   dirty. If no server session exists for this session, returns nil.
+    #
+    # @api private
+    def dirty?
+      @server_session&.dirty?
+    end
+
     # @return [ Hash ] The options for the transaction currently being executed
     # on this session.
     #
@@ -421,9 +445,21 @@ module Mongo
     #   progress or if the write concern is unacknowledged.
     #
     # @since 2.7.0
-    def with_transaction(options=nil)
-      # Non-configurable 120 second timeout for the entire operation
-      deadline = Utils.monotonic_time + 120
+    def with_transaction(options = nil)
+      if timeout_ms = (options || {})[:timeout_ms]
+        timeout_sec = timeout_ms / 1_000.0
+        deadline = Utils.monotonic_time + timeout_sec
+        @with_transaction_deadline = deadline
+      elsif default_timeout_ms = @options[:default_timeout_ms]
+        timeout_sec = default_timeout_ms / 1_000.0
+        deadline = Utils.monotonic_time + timeout_sec
+        @with_transaction_deadline = deadline
+      elsif @client.timeout_sec
+        deadline = Utils.monotonic_time + @client.timeout_sec
+        @with_transaction_deadline = deadline
+      else
+        deadline = Utils.monotonic_time + 120
+      end
       transaction_in_progress = false
       loop do
         commit_options = {}
@@ -437,6 +473,7 @@ module Mongo
         rescue Exception => e
           if within_states?(STARTING_TRANSACTION_STATE, TRANSACTION_IN_PROGRESS_STATE)
             log_warn("Aborting transaction due to #{e.class}: #{e}")
+            @with_transaction_deadline = nil
             abort_transaction
             transaction_in_progress = false
           end
@@ -464,7 +501,7 @@ module Mongo
           rescue Mongo::Error => e
             if e.label?('UnknownTransactionCommitResult')
               if Utils.monotonic_time >= deadline ||
-                e.is_a?(Error::OperationFailure) && e.max_time_ms_expired?
+                e.is_a?(Error::OperationFailure::Family) && e.max_time_ms_expired?
               then
                 transaction_in_progress = false
                 raise
@@ -505,9 +542,10 @@ module Mongo
         log_warn('with_transaction callback broke out of with_transaction loop, aborting transaction')
         begin
           abort_transaction
-        rescue Error::OperationFailure, Error::InvalidTransactionOperation
+        rescue Error::OperationFailure::Family, Error::InvalidTransactionOperation
         end
       end
+      @with_transaction_deadline = nil
     end
 
     # Places subsequent operations in this session into a new transaction.
@@ -522,6 +560,7 @@ module Mongo
     #
     # @option options [ Integer ] :max_commit_time_ms The maximum amount of
     #   time to allow a single commitTransaction command to run, in milliseconds.
+    #   This options is deprecated, use :timeout_ms instead.
     # @option options [ Hash ] :read_concern The read concern options hash,
     #   with the following optional keys:
     #   - *:level* -- the read preference level as a symbol; valid values
@@ -532,12 +571,18 @@ module Mongo
     #   items:
     #   - *:mode* -- read preference specified as a symbol; the only valid value is
     #     *:primary*.
+    # @option options [ Integer ] :timeout_ms The operation timeout in milliseconds.
+    #    Must be a non-negative integer. An explicit value of 0 means infinite.
+    #    The default value is unset which means the value is inherited from
+    #    the client.
     #
     # @raise [ Error::InvalidTransactionOperation ] If a transaction is already in
     #   progress or if the write concern is unacknowledged.
     #
     # @since 2.6.0
     def start_transaction(options = nil)
+      check_transactions_supported!
+
       if options
         Lint.validate_read_concern_option(options[:read_concern])
 
@@ -592,6 +637,10 @@ module Mongo
     #
     # @option options :write_concern [ nil | WriteConcern::Base ] The write
     #   concern to use for this operation.
+    # @option options [ Integer ] :timeout_ms The operation timeout in milliseconds.
+    #    Must be a non-negative integer. An explicit value of 0 means infinite.
+    #    The default value is unset which means the value is inherited from
+    #    the client.
     #
     # @raise [ Error::InvalidTransactionOperation ] If there is no active transaction.
     #
@@ -628,7 +677,11 @@ module Mongo
             write_concern = WriteConcern.get(write_concern)
           end
 
-          context = Operation::Context.new(client: @client, session: self)
+          context = Operation::Context.new(
+            client: @client,
+            session: self,
+            operation_timeouts: operation_timeouts(options)
+          )
           write_with_retry(write_concern, ending_transaction: true,
             context: context,
           ) do |connection, txn_num, context|
@@ -666,10 +719,15 @@ module Mongo
     # @example Abort the transaction.
     #   session.abort_transaction
     #
+    # @option options [ Integer ] :timeout_ms The operation timeout in milliseconds.
+    #    Must be a non-negative integer. An explicit value of 0 means infinite.
+    #    The default value is unset which means the value is inherited from
+    #    the client.
+    #
     # @raise [ Error::InvalidTransactionOperation ] If there is no active transaction.
     #
     # @since 2.6.0
-    def abort_transaction
+    def abort_transaction(options = nil)
       QueryCache.clear
 
       check_if_ended!
@@ -686,10 +744,16 @@ module Mongo
           Mongo::Error::InvalidTransactionOperation.cannot_call_twice_msg(:abortTransaction))
       end
 
+      options ||= {}
+
       begin
         unless starting_transaction?
           @aborting_transaction = true
-          context = Operation::Context.new(client: @client, session: self)
+          context = Operation::Context.new(
+            client: @client,
+            session: self,
+            operation_timeouts: operation_timeouts(options)
+          )
           write_with_retry(txn_options[:write_concern],
             ending_transaction: true, context: context,
           ) do |connection, txn_num, context|
@@ -879,7 +943,7 @@ module Mongo
     #
     # @since 2.6.0
     # @api private
-    def add_txn_opts!(command, read)
+    def add_txn_opts!(command, read, context)
       command.tap do |c|
         # The read concern should be added to any command that starts a transaction.
         if starting_transaction?
@@ -933,6 +997,14 @@ module Mongo
         if c[:writeConcern] && c[:writeConcern][:w] && c[:writeConcern][:w].is_a?(Symbol)
           c[:writeConcern][:w] = c[:writeConcern][:w].to_s
         end
+
+        # Ignore wtimeout if csot
+        if context&.csot?
+          c[:writeConcern]&.delete(:wtimeout)
+        end
+
+        # We must not send an empty (server default) write concern.
+        c.delete(:writeConcern) if c[:writeConcern]&.empty?
       end
     end
 
@@ -1119,6 +1191,8 @@ module Mongo
     # @api private
     attr_accessor :snapshot_timestamp
 
+    attr_reader :with_transaction_deadline
+
     private
 
     # Get the read concern the session will use when starting a transaction.
@@ -1185,5 +1259,32 @@ module Mongo
         raise Mongo::Error::InvalidSession.new(MISMATCHED_CLUSTER_ERROR_MSG)
       end
     end
+
+    def check_transactions_supported!
+      raise Mongo::Error::TransactionsNotSupported, "standalone topology" if cluster.single?
+
+      cluster.next_primary.with_connection do |conn|
+        if cluster.replica_set? && !conn.features.transactions_enabled?
+          raise Mongo::Error::TransactionsNotSupported, "server version is < 4.0"
+        end
+        if cluster.sharded? && !conn.features.sharded_transactions_enabled?
+          raise Mongo::Error::TransactionsNotSupported, "sharded transactions require server version >= 4.2"
+        end
+      end
+    end
+
+    def operation_timeouts(opts)
+      {
+        inherited_timeout_ms: @client.timeout_ms
+      }.tap do |result|
+        if @with_transaction_deadline.nil?
+          if timeout_ms = opts[:timeout_ms]
+            result[:operation_timeout_ms] = timeout_ms
+          elsif default_timeout_ms = options[:default_timeout_ms]
+            result[:operation_timeout_ms] = default_timeout_ms
+          end
+        end
+      end
+    end
   end
 end