mongo 2.6.4 → 2.7.0.rc0

data/lib/mongo/server/round_trip_time_averager.rb

@@ -0,0 +1,64 @@
+# Copyright (C) 2018-2019 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 Server
+    # @api private
+    class RoundTripTimeAverager
+
+      # The weighting factor (alpha) for calculating the average moving
+      # round trip time.
+      RTT_WEIGHT_FACTOR = 0.2.freeze
+      private_constant :RTT_WEIGHT_FACTOR
+
+      def initialize
+        @last_round_trip_time = nil
+        @average_round_trip_time = nil
+      end
+
+      attr_reader :last_round_trip_time
+      attr_reader :average_round_trip_time
+
+      def measure
+        start = Time.now
+        begin
+          rv = yield
+        rescue Exception => exc
+        end
+        last_round_trip_time = Time.now - start
+
+        # If ismaster fails, we need to return the last round trip time
+        # because it is used in the heartbeat failed SDAM event,
+        # but we must not update the round trip time recorded in the server.
+        unless exc
+          @last_round_trip_time = last_round_trip_time
+          update_average_round_trip_time
+        end
+
+        [rv, exc, last_round_trip_time, average_round_trip_time]
+      end
+
+      private
+
+      # This method is separate for testing purposes.
+      def update_average_round_trip_time
+        @average_round_trip_time = if average_round_trip_time
+          RTT_WEIGHT_FACTOR * last_round_trip_time + (1 - RTT_WEIGHT_FACTOR) * average_round_trip_time
+        else
+          last_round_trip_time
+        end
+      end
+    end
+  end
+end

data/lib/mongo/server_selector.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB, Inc.
+# Copyright (C) 2014-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server_selector/nearest.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB, Inc.
+# Copyright (C) 2014-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server_selector/primary.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB, Inc.
+# Copyright (C) 2014-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server_selector/primary_preferred.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB, Inc.
+# Copyright (C) 2014-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server_selector/secondary.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB, Inc.
+# Copyright (C) 2014-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server_selector/secondary_preferred.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB, Inc.
+# Copyright (C) 2014-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/server_selector/selectable.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB, Inc.
+# Copyright (C) 2014-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -60,6 +60,10 @@ 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,
+      #   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.
       #
       # @raise [ Error::InvalidServerPreference ] If tag sets are specified
       #   but not allowed.
@@ -100,19 +104,37 @@ module Mongo
         deadline = Time.now + server_selection_timeout
         while (deadline - Time.now) > 0
           servers = candidates(cluster)
+          if Lint.enabled?
+            servers.each do |server|
+              if server.average_round_trip_time.nil?
+                raise Error::LintError, "Server #{server.address} has nil average rtt"
+              end
+            end
+          end
           if servers && !servers.compact.empty?
+            unless cluster.topology.compatible?
+              raise Error::UnsupportedFeatures, cluster.topology.compatibility_error.to_s
+            end
+
+            # This list of servers may be ordered in a specific way
+            # 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
-            # HACK: all servers in a topology must satisfy wire protocol
-            # constraints. There is probably a better implementation than
-            # checking all servers here
-            cluster.servers.each do |a_server|
-              a_server.check_driver_support!
+
+            if cluster.topology.single? &&
+              cluster.topology.replica_set_name &&
+              cluster.topology.replica_set_name != server.description.replica_set_name
+            then
+              msg = "Cluster topology specifies replica set name #{cluster.topology.replica_set_name}, but the server has replica set name #{server.description.replica_set_name || '<nil>'}"
+              raise Error::NoServerAvailable.new(self, cluster, msg)
             end
+
             return server
           end
-          cluster.scan!
+          cluster.scan!(false)
         end
-        raise Error::NoServerAvailable.new(self)
+        raise Error::NoServerAvailable.new(self, cluster)
       end
 
       # Get the timeout for server selection.
@@ -195,6 +217,10 @@ module Mongo
         matching_servers = candidates.select(&:secondary?)
         matching_servers = filter_stale_servers(matching_servers, primary(candidates).first)
         matching_servers = match_tag_sets(matching_servers) unless tag_sets.empty?
+        # Per server selection spec the server selected MUST be a random
+        # one matching staleness and latency requirements.
+        # Selectors always pass the output of #secondaries to #nearest
+        # which shuffles the server list, fulfilling this requirement.
         matching_servers
       end
 
@@ -233,22 +259,21 @@ module Mongo
 
       def filter_stale_servers(candidates, primary = nil)
         return candidates unless @max_staleness
-        max_staleness_ms = @max_staleness * 1000
 
         if primary
           candidates.select do |server|
             validate_max_staleness_support!(server)
             staleness = (server.last_scan - server.last_write_date) -
                         (primary.last_scan - primary.last_write_date)  +
-                        (server.heartbeat_frequency_seconds * 1000)
-            staleness <= max_staleness_ms
+                        server.heartbeat_frequency_seconds
+            staleness <= @max_staleness
           end
         else
           max_write_date = candidates.collect(&:last_write_date).max
           candidates.select do |server|
             validate_max_staleness_support!(server)
-            staleness = max_write_date - server.last_write_date + (server.heartbeat_frequency_seconds * 1000)
-            staleness <= max_staleness_ms
+            staleness = max_write_date - server.last_write_date + server.heartbeat_frequency_seconds
+            staleness <= @max_staleness
           end
         end
       end

data/lib/mongo/session.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2017-2018 MongoDB, Inc.
+# Copyright (C) 2017-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -18,7 +18,7 @@ require 'mongo/session/server_session'
 module Mongo
 
   # A logical session representing a set of sequential operations executed
-  #   by an application that are related in some way.
+  # by an application that are related in some way.
   #
   # @since 2.5.0
   class Session
@@ -30,7 +30,7 @@ module Mongo
     # @since 2.5.0
     attr_reader :options
 
-    # Get the cluster through which this session was created.
+    # Get the client through which this session was created.
     #
     # @since 2.5.1
     attr_reader :client
@@ -68,20 +68,21 @@ module Mongo
     # @since 2.5.0
     SESSIONS_NOT_SUPPORTED = 'Sessions are not supported by the connected servers.'.freeze
 
-    # The state of a session in which the last operation was not related to any transaction or no
-    # operations have yet occurred.
+    # The state of a session in which the last operation was not related to
+    # any transaction or no operations have yet occurred.
     #
     # @since 2.6.0
     NO_TRANSACTION_STATE = :no_transaction
 
-    # The state of a session in which a user has initiated a transaction but no operations within
-    # the transactions have occurred yet.
+    # The state of a session in which a user has initiated a transaction but
+    # no operations within the transactions have occurred yet.
     #
     # @since 2.6.0
     STARTING_TRANSACTION_STATE = :starting_transaction
 
-    # The state of a session in which a transaction has been started and at least one operation has
-    # occurred, but the transaction has not yet been committed or aborted.
+    # The state of a session in which a transaction has been started and at
+    # least one operation has occurred, but the transaction has not yet been
+    # committed or aborted.
     #
     # @since 2.6.0
     TRANSACTION_IN_PROGRESS_STATE = :transaction_in_progress
@@ -103,6 +104,8 @@ module Mongo
 
     # Initialize a Session.
     #
+    # @note Applications should use Client#start_session to begin a session.
+    #
     # @example
     #   Session.new(server_session, client, options)
     #
@@ -117,6 +120,7 @@ module Mongo
     #     and *:nearest*.
     #
     # @since 2.5.0
+    # @api private
     def initialize(server_session, client, options = {})
       @server_session = server_session
       options = options.dup
@@ -155,7 +159,12 @@ module Mongo
     # @since 2.5.0
     def end_session
       if !ended? && @client
-        abort_transaction if within_states?(TRANSACTION_IN_PROGRESS_STATE) rescue Mongo::Error
+        if within_states?(TRANSACTION_IN_PROGRESS_STATE)
+          begin
+            abort_transaction
+          rescue Mongo::Error
+          end
+        end
         @client.cluster.session_pool.checkin(@server_session)
       end
     ensure
@@ -182,6 +191,7 @@ module Mongo
     # @return [ Hash, BSON::Document ] The command document.
     #
     # @since 2.6.0
+    # @api private
     def add_autocommit!(command)
       command.tap do |c|
         c[:autocommit] = false if in_transaction?
@@ -196,6 +206,7 @@ module Mongo
     # @return [ Hash, BSON::Document ] The command document.
     #
     # @since 2.5.0
+    # @api private
     def add_id!(command)
       command.merge!(lsid: session_id)
     end
@@ -208,9 +219,12 @@ module Mongo
     # @return [ Hash, BSON::Document ] The command document.
     #
     # @since 2.6.0
+    # @api private
     def add_start_transaction!(command)
       command.tap do |c|
-        c[:startTransaction] = true if starting_transaction?
+        if starting_transaction?
+          c[:startTransaction] = true
+        end
       end
     end
 
@@ -222,6 +236,7 @@ module Mongo
     # @return [ Hash, BSON::Document ] The command document.
     #
     # @since 2.6.0
+    # @api private
     def add_txn_num!(command)
       command.tap do |c|
         c[:txnNumber] = BSON::Int64.new(@server_session.txn_num) if in_transaction?
@@ -236,6 +251,7 @@ module Mongo
     # @return [ Hash, BSON::Document ] The command document.
     #
     # @since 2.6.0
+    # @api private
     def add_txn_opts!(command, read)
       command.tap do |c|
         # The read preference should be added for all read operations.
@@ -278,6 +294,7 @@ module Mongo
     # @return [ Hash, BSON::Document ] The command document.
     #
     # @since 2.6.0
+    # @api private
     def suppress_read_write_concern!(command)
       command.tap do |c|
         next unless in_transaction?
@@ -293,9 +310,10 @@ module Mongo
     #   session.validate_read_preference!(command)
     #
     # @raise [ Mongo::Error::InvalidTransactionOperation ] If the read preference of the command is
-    # not primary.
+    #   not primary.
     #
     # @since 2.6.0
+    # @api private
     def validate_read_preference!(command)
       return unless in_transaction? && non_primary_read_preference_mode?(command)
 
@@ -306,6 +324,7 @@ module Mongo
     # Update the state of the session due to a (non-commit and non-abort) operation being run.
     #
     # @since 2.6.0
+    # @api private
     def update_state!
       case @state
       when STARTING_TRANSACTION_STATE
@@ -327,6 +346,7 @@ module Mongo
     # @raise [ Mongo::Error::InvalidSession ] Raise error if the session is not valid.
     #
     # @since 2.5.0
+    # @api private
     def validate!(cluster)
       check_matching_cluster!(cluster)
       check_if_ended!
@@ -343,6 +363,7 @@ module Mongo
     # @return [ Operation::Result ] The result.
     #
     # @since 2.5.0
+    # @api private
     def process(result)
       unless implicit?
         set_operation_time(result)
@@ -400,19 +421,24 @@ module Mongo
     #
     # @since 2.5.0
     def retry_writes?
-      !!cluster.options[:retry_writes] && (cluster.replica_set? || cluster.sharded?)
+      !!client.options[:retry_writes] && (cluster.replica_set? || cluster.sharded?)
     end
 
-    # Get the session id.
+    # Get the server session id of this session, if the session was not ended.
+    # If the session was ended, returns nil.
     #
     # @example Get the session id.
     #   session.session_id
     #
-    # @return [ BSON::Document ] The session id.
+    # @return [ BSON::Document ] The server session id.
     #
     # @since 2.5.0
     def session_id
-      @server_session.session_id if @server_session
+      if ended?
+        raise Error::SessionEnded
+      end
+
+      @server_session.session_id
     end
 
     # Increment and return the next transaction number.
@@ -423,8 +449,13 @@ module Mongo
     # @return [ Integer ] The next transaction number.
     #
     # @since 2.5.0
+    # @api private
     def next_txn_num
-      @server_session.next_txn_num if @server_session
+      if ended?
+        raise Error::SessionEnded
+      end
+
+      @server_session.next_txn_num
     end
 
     # Get the current transaction number.
@@ -436,7 +467,11 @@ module Mongo
     #
     # @since 2.6.0
     def txn_num
-      @server_session && @server_session.txn_num
+      if ended?
+        raise Error::SessionEnded
+      end
+
+      @server_session.txn_num
     end
 
     # Is this session an implicit one (not user-created).
@@ -463,7 +498,7 @@ module Mongo
       @explicit ||= !implicit?
     end
 
-    # Start a new transaction.
+    # Places subsequent operations in this session into a new transaction.
     #
     # Note that the transaction will not be started on the server until an
     # operation is performed after start_transaction is called.
@@ -473,12 +508,10 @@ module Mongo
     #
     # @param [ Hash ] options The options for the transaction being started.
     #
-    # @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 are *:local*, *:majority*,
-    #   and *:snapshot*
-    #   - *:after_cluster_time* -- the cluster time BSON::Document or hash specifying which cluster
-    #   time reads should occur after
+    # @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
+    #      are *:local*, *:majority*, and *:snapshot*
     # @option options [ Hash ] :write_concern The write concern options. Can be :w =>
     #   Integer|String, :fsync => Boolean, :j => Boolean.
     # @option options [ Hash ] :read The read preference options. The hash may have the following
@@ -486,11 +519,15 @@ module Mongo
     #   - *:mode* -- read preference specified as a symbol; the only valid value is
     #     *:primary*.
     #
-    # @raise [ InvalidTransactionOperation ] If a transaction is already in
-    # progress or if the write concern is unacknowledged.
+    # @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)
+      if options
+        Lint.validate_read_concern_option(options[:read_concern])
+      end
+
       check_if_ended!
 
       if within_states?(STARTING_TRANSACTION_STATE, TRANSACTION_IN_PROGRESS_STATE)
@@ -514,11 +551,13 @@ module Mongo
     # @example Commits the transaction.
     #   session.commit_transaction
     #
-    # @raise [ InvalidTransactionOperation ] If a transaction was just aborted and no new one was
-    #   started.
+    # @option options :write_concern [ nil | WriteConcern::Base ] The write
+    #   concern to use for this operation.
+    #
+    # @raise [ Error::InvalidTransactionOperation ] If there is no active transaction.
     #
     # @since 2.6.0
-    def commit_transaction
+    def commit_transaction(options=nil)
       check_if_ended!
       check_if_no_transaction!
 
@@ -528,9 +567,11 @@ module Mongo
             :abortTransaction, :commitTransaction))
       end
 
+      options ||= {}
+
       begin
-        # If commitTransaction is called twice, we need to run the same commit operation again, so
-        # we revert the session to the previous state.
+        # If commitTransaction is called twice, we need to run the same commit
+        # operation again, so we revert the session to the previous state.
         if within_states?(TRANSACTION_COMMITTED_STATE)
           @state = @last_commit_skipped ? STARTING_TRANSACTION_STATE : TRANSACTION_IN_PROGRESS_STATE
         end
@@ -540,12 +581,17 @@ module Mongo
         else
           @last_commit_skipped = false
 
-          write_with_retry(self, txn_options[:write_concern], true) do |server, txn_num|
+          write_concern = options[:write_concern] || txn_options[:write_concern]
+          if write_concern && !write_concern.is_a?(WriteConcern::Base)
+            write_concern = WriteConcern.get(write_concern)
+          end
+          write_with_retry(self, write_concern, true) do |server, txn_num|
             Operation::Command.new(
               selector: { commitTransaction: 1 },
               db_name: 'admin',
               session: self,
-              txn_num: txn_num
+              txn_num: txn_num,
+              write_concern: write_concern,
             ).execute(server)
           end
         end
@@ -571,8 +617,7 @@ module Mongo
     # @example Abort the transaction.
     #   session.abort_transaction
     #
-    # @raise [ Mongo::Error::InvalidTransactionOperation ] If a transaction was just committed or
-    #   aborted and no new one was started.
+    # @raise [ Error::InvalidTransactionOperation ] If there is no active transaction.
     #
     # @since 2.6.0
     def abort_transaction
@@ -622,6 +667,108 @@ module Mongo
       within_states?(STARTING_TRANSACTION_STATE, TRANSACTION_IN_PROGRESS_STATE)
     end
 
+    # Executes the provided block in a transaction, retrying as necessary.
+    #
+    # Returns the return value of the block.
+    #
+    # Exact number of retries and when they are performed are implementation
+    # details of the driver; the provided block should be idempotent, and
+    # should be prepared to be called more than once. The driver may retry
+    # the commit command within an active transaction or it may repeat the
+    # transaction and invoke the block again, depending on the error
+    # encountered if any. Note also that the retries may be executed against
+    # different servers.
+    #
+    # Transactions cannot be nested - InvalidTransactionOperation will be raised
+    # if this method is called when the session already has an active transaction.
+    #
+    # Exceptions raised by the block which are not derived from Mongo::Error
+    # stop processing, abort the transaction and are propagated out of
+    # with_transaction. Exceptions derived from Mongo::Error may be
+    # handled by with_transaction, resulting in retries of the process.
+    #
+    # The number of retries and the total time taken by with_transaction is
+    # not specified by the driver. The driver only guarantees that the number
+    # of retries attempted will be finite, i.e., that it will stop retrying
+    # at some point. The number of retries and the time allowed for the retries
+    # is subject to change in future versions of the driver. Applications that
+    # require known performance characteristics (for example, when servicing
+    # web requests in an application with a fixed number of servers/workers/threads)
+    # are encouraged to explicitly limit the time they allow for with_transaction
+    # calls.
+    #
+    # @example Execute a statement in a transaction
+    #   session.with_transaction(write_concern: {w: :majority}) do
+    #     collection.update_one({ id: 3 }, { '$set' => { status: 'Inactive'} },
+    #                           session: session)
+    #
+    #   end
+    #
+    # @example Execute a statement in a transaction, limiting total time consumed
+    #   Timeout.timeout(5) do
+    #     session.with_transaction(write_concern: {w: :majority}) do
+    #       collection.update_one({ id: 3 }, { '$set' => { status: 'Inactive'} },
+    #                             session: session)
+    #
+    #     end
+    #   end
+    #
+    # @param [ Hash ] options The options for the transaction being started.
+    #   These are the same options that start_transaction accepts.
+    #
+    # @raise [ Error::InvalidTransactionOperation ] If a transaction is already in
+    #   progress or if the write concern is unacknowledged.
+    #
+    # @since 2.7.0
+    def with_transaction(options=nil)
+      loop do
+        commit_options = {}
+        if options
+          commit_options[:write_concern] = options[:write_concern]
+        end
+        start_transaction(options)
+        begin
+          rv = yield self
+        rescue Exception => e
+          if within_states?(STARTING_TRANSACTION_STATE, TRANSACTION_IN_PROGRESS_STATE)
+            abort_transaction
+          end
+
+          if e.is_a?(Mongo::Error) && e.label?(Mongo::Error::TRANSIENT_TRANSACTION_ERROR_LABEL)
+            next
+          end
+
+          raise
+        else
+          if within_states?(TRANSACTION_ABORTED_STATE, NO_TRANSACTION_STATE, TRANSACTION_COMMITTED_STATE)
+            return rv
+          end
+
+          begin
+            commit_transaction(commit_options)
+            return rv
+          rescue Mongo::Error => e
+            if e.label?(Mongo::Error::UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL)
+              wc_options = case v = commit_options[:write_concern]
+                when WriteConcern::Base
+                  v.options
+                when nil
+                  {}
+                else
+                  v
+                end
+              commit_options[:write_concern] = wc_options.merge(w: :majority)
+              retry
+            elsif e.label?(Mongo::Error::TRANSIENT_TRANSACTION_ERROR_LABEL)
+              next
+            else
+              raise
+            end
+          end
+        end
+      end
+    end
+
     # Get the read preference the session will use in the currently
     # active transaction.
     #
@@ -677,17 +824,19 @@ module Mongo
       mode && mode != 'primary'
     end
 
-    def causal_consistency_doc(read_concern)
+    # Returns causal consistency document if the last operation time is
+    # known and causal consistency is enabled, otherwise returns nil.
+    def causal_consistency_doc
       if operation_time && causal_consistency?
-        (read_concern || {}).merge(:afterClusterTime => operation_time)
+        {:afterClusterTime => operation_time}
       else
-        read_concern
+        nil
       end
     end
 
     def causal_consistency?
       @causal_consistency ||= (if @options.key?(:causal_consistency)
-                                 @options[:causal_consistency] == true
+                                 !!@options[:causal_consistency]
                                else
                                  true
                                end)