mongo 2.10.5 → 2.15.1

data/lib/mongo/server_selector/{selectable.rb → base.rb}

@@ -1,4 +1,7 @@
-# Copyright (C) 2014-2019 MongoDB, Inc.
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -13,12 +16,10 @@
 # limitations under the License.
 
 module Mongo
+
   module ServerSelector
 
-    # Provides common behavior for filtering a list of servers by server mode or tag set.
-    #
-    # @since 2.0.0
-    module Selectable
+    class Base
 
       # Initialize the server selector.
       #
@@ -36,19 +37,25 @@ module Mongo
       #   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
+      #   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.
       #
       # @raise [ Error::InvalidServerPreference ] If tag sets are specified
       #   but not allowed.
       #
-      # @since 2.0.0
+      # @api private
       def initialize(options = nil)
         options = options ? options.dup : {}
         if options[:max_staleness] == -1
           options.delete(:max_staleness)
         end
-        @options = options.freeze
-        @tag_sets = (options[:tag_sets] || []).freeze
+        @options = options
+        @tag_sets = options[:tag_sets] || []
         @max_staleness = options[:max_staleness]
+        @hedge = options[:hedge]
+
         validate!
       end
 
@@ -58,26 +65,50 @@ module Mongo
       # @return [ Array ] tag_sets The tag sets used to select servers.
       attr_reader :tag_sets
 
-      # @return [ Integer ] max_staleness The maximum replication lag, in seconds, that a
-      #   secondary can suffer and still be eligible for a read.
+      # @return [ Integer ] max_staleness The maximum replication lag, in
+      #   seconds, that a secondary can suffer and still be eligible for a read.
       #
       # @since 2.4.0
       attr_reader :max_staleness
 
-      # Check equality of two server selector.
+      # @return [ Hash | nil ] hedge The document specifying whether to enable
+      #   hedged reads.
+      attr_reader :hedge
+
+      # Get the timeout for server selection.
       #
-      # @example Check server selector equality.
-      #   preference == other
+      # @example Get the server selection timeout, in seconds.
+      #   selector.server_selection_timeout
       #
-      # @param [ Object ] other The other preference.
+      # @return [ Float ] The timeout.
       #
-      # @return [ true, false ] Whether the objects are equal.
+      # @since 2.0.0
+      #
+      # @deprecated This setting is now taken from the cluster options when
+      #   a server is selected. Will be removed in version 3.0.
+      def server_selection_timeout
+        @server_selection_timeout ||=
+          (options[:server_selection_timeout] || ServerSelector::SERVER_SELECTION_TIMEOUT)
+      end
+
+      # Get the local threshold boundary for nearest selection in seconds.
+      #
+      # @example Get the local threshold.
+      #   selector.local_threshold
+      #
+      # @return [ Float ] The local threshold.
       #
       # @since 2.0.0
-      def ==(other)
-        name == other.name &&
-          tag_sets == other.tag_sets &&
-            max_staleness == other.max_staleness
+      #
+      # @deprecated This setting is now taken from the cluster options when
+      #   a server is selected. Will be removed in version 3.0.
+      def local_threshold
+        @local_threshold ||= (options[:local_threshold] || ServerSelector::LOCAL_THRESHOLD)
+      end
+
+      # @api private
+      def local_threshold_with_cluster(cluster)
+        options[:local_threshold] || cluster.options[:local_threshold] || LOCAL_THRESHOLD
       end
 
       # Inspect the server selector.
@@ -89,7 +120,22 @@ module Mongo
       #
       # @since 2.2.0
       def inspect
-        "#<#{self.class.name}:0x#{object_id} tag_sets=#{tag_sets.inspect} max_staleness=#{max_staleness.inspect}>"
+        "#<#{self.class.name}:0x#{object_id} tag_sets=#{tag_sets.inspect} max_staleness=#{max_staleness.inspect} hedge=#{hedge}>"
+      end
+
+      # Check equality of two server selectors.
+      #
+      # @example Check server selector equality.
+      #   preference == other
+      #
+      # @param [ Object ] other The other preference.
+      #
+      # @return [ true, false ] Whether the objects are equal.
+      #
+      # @since 2.0.0
+      def ==(other)
+        name == other.name && hedge == other.hedge &&
+          max_staleness == other.max_staleness && tag_sets == other.tag_sets
       end
 
       # Select a server from the specified cluster, taking into account
@@ -138,7 +184,7 @@ module Mongo
           raise Error::NoServerAvailable.new(self, cluster, msg)
         end
 
-        deadline = Time.now + server_selection_timeout
+        deadline = Utils.monotonic_time + server_selection_timeout
 
         if session && session.pinned_server
           if Mongo::Lint.enabled?
@@ -156,7 +202,7 @@ module Mongo
             # This will no longer be the case once SRV polling is implemented.
 
             unless server.mongos?
-              while (time_remaining = deadline - Time.now) > 0
+              while (time_remaining = deadline - Utils.monotonic_time) > 0
                 wait_for_server_selection(cluster, time_remaining)
               end
 
@@ -174,6 +220,7 @@ module Mongo
         if cluster.replica_set?
           validate_max_staleness_value_early!
         end
+
         if cluster.addresses.empty?
           if Lint.enabled?
             unless cluster.servers.empty?
@@ -183,46 +230,22 @@ module Mongo
           msg = "Cluster has no addresses, and therefore will never have a server"
           raise Error::NoServerAvailable.new(self, cluster, msg)
         end
+
 =begin Add this check in version 3.0.0
         unless cluster.connected?
           msg = 'Cluster is disconnected'
           raise Error::NoServerAvailable.new(self, cluster, msg)
         end
 =end
+
         loop do
-          servers = candidates(cluster)
-          if Lint.enabled?
-            servers.each do |server|
-              # It is possible for a server to have a nil average RTT here
-              # because the ARTT comes from description which may be updated
-              # by a background thread while server selection is running.
-              # Currently lint mode is not a public feature, if/when this
-              # changes (https://jira.mongodb.org/browse/RUBY-1576) the
-              # requirement for ARTT to be not nil would need to be removed.
-              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?
+          server = try_select_server(cluster)
+
+          if server
             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
-
-            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
-
             if session && session.starting_transaction? && cluster.sharded?
               session.pin(server)
             end
@@ -232,7 +255,7 @@ module Mongo
 
           cluster.scan!(false)
 
-          time_remaining = deadline - Time.now
+          time_remaining = deadline - Utils.monotonic_time
           if time_remaining > 0
             wait_for_server_selection(cluster, time_remaining)
 
@@ -245,7 +268,11 @@ module Mongo
           end
         end
 
-        msg = "No #{name} server is available in cluster: #{cluster.summary} " +
+        msg = "No #{name} server"
+        if is_a?(ServerSelector::Secondary) && !tag_sets.empty?
+          msg += " with tag sets: #{tag_sets}"
+        end
+        msg += " is available in cluster: #{cluster.summary} " +
                 "with timeout=#{server_selection_timeout}, " +
                 "LT=#{local_threshold_with_cluster(cluster)}"
         msg += server_selection_diagnostic_message(cluster)
@@ -260,67 +287,106 @@ module Mongo
         raise e
       end
 
-      # Get the timeout for server selection.
-      #
-      # @example Get the server selection timeout, in seconds.
-      #   selector.server_selection_timeout
+      # Tries to find a suitable server, returns the server if one is available
+      # or nil if there isn't a suitable server.
       #
-      # @return [ Float ] The timeout.
-      #
-      # @since 2.0.0
+      # @return [ Server | nil ] A suitable server, if one exists.
       #
-      # @deprecated This setting is now taken from the cluster options when a server is selected.
-      #   Will be removed in 3.0.
-      def server_selection_timeout
-        @server_selection_timeout ||=
-          (options[:server_selection_timeout] || ServerSelector::SERVER_SELECTION_TIMEOUT)
-      end
+      # @api private
+      def try_select_server(cluster)
+        servers = suitable_servers(cluster)
 
-      def local_threshold_with_cluster(cluster)
-        options[:local_threshold] || cluster.options[:local_threshold] || LOCAL_THRESHOLD
+        # 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
+
+        if server
+          if Lint.enabled?
+            # It is possible for a server to have a nil average RTT here
+            # because the ARTT comes from description which may be updated
+            # by a background thread while server selection is running.
+            # Currently lint mode is not a public feature, if/when this
+            # changes (https://jira.mongodb.org/browse/RUBY-1576) the
+            # requirement for ARTT to be not nil would need to be removed.
+            if server.average_round_trip_time.nil?
+              raise Error::LintError, "Server #{server.address} has nil average rtt"
+            end
+          end
+        end
+
+        server
       end
 
-      # Get the local threshold boundary for nearest selection in seconds.
+      # Returns servers of acceptable types from the cluster.
       #
-      # @example Get the local threshold.
-      #   selector.local_threshold
+      # Does not perform staleness validation, staleness filtering or
+      # latency filtering.
       #
-      # @return [ Float ] The local threshold.
+      # @param [ Cluster ] cluster The cluster.
       #
-      # @since 2.0.0
+      # @return [ Array<Server> ] The candidate servers.
       #
-      # @deprecated This setting is now taken from the cluster options when a server is selected.
-      #   Will be removed in 3.0.
-      def local_threshold
-        @local_threshold ||= (options[:local_threshold] || ServerSelector::LOCAL_THRESHOLD)
+      # @api private
+      def candidates(cluster)
+        servers = cluster.servers
+        servers.each do |server|
+          validate_max_staleness_support!(server)
+        end
+        if cluster.single?
+          servers
+        elsif cluster.sharded?
+          servers
+        elsif cluster.replica_set?
+          select_in_replica_set(servers)
+        else
+          # Unknown cluster - no servers
+          []
+        end
       end
 
-      # Get the potential candidates to select from the cluster.
-      #
-      # @example Get the server candidates.
-      #   selectable.candidates(cluster)
+      # Returns servers satisfying the server selector from the cluster.
       #
       # @param [ Cluster ] cluster The cluster.
       #
-      # @return [ Array<Server> ] The candidate servers.
+      # @return [ Array<Server> ] The suitable servers.
       #
-      # @since 2.4.0
-      def candidates(cluster)
+      # @api private
+      def suitable_servers(cluster)
         if cluster.single?
-          cluster.servers.each { |server| validate_max_staleness_support!(server) }
+          candidates(cluster)
         elsif cluster.sharded?
           local_threshold = local_threshold_with_cluster(cluster)
-          near_servers(cluster.servers, local_threshold).each do |server|
-            validate_max_staleness_support!(server)
-          end
+          servers = candidates(cluster)
+          near_servers(servers, local_threshold)
+        elsif cluster.replica_set?
+          validate_max_staleness_value!(cluster)
+          candidates(cluster)
         else
-          validate_max_staleness_value!(cluster) unless cluster.unknown?
-          select(cluster.servers)
+          # Unknown cluster - no servers
+          []
         end
       end
 
       private
 
+      # Convert this server preference definition into a format appropriate
+      #   for sending to a MongoDB server (i.e., as a command field).
+      #
+      # @return [ Hash ] The server preference formatted as a command field value.
+      #
+      # @since 2.0.0
+      def full_doc
+        @full_doc ||= begin
+          preference = { :mode => self.class.const_get(:SERVER_FORMATTED_NAME) }
+          preference.update(tags: tag_sets) unless tag_sets.empty?
+          preference.update(maxStalenessSeconds: max_staleness) if max_staleness
+          preference.update(hedge: hedge) if hedge
+          preference
+        end
+      end
+
       # Select the primary from a list of provided candidates.
       #
       # @param [ Array ] candidates List of candidate servers to select the
@@ -417,19 +483,23 @@ module Mongo
       def filter_stale_servers(candidates, primary = nil)
         return candidates unless @max_staleness
 
+        # last_scan is filled out by the Monitor, and can be nil if a server
+        # had its description manually set rather than being normally updated
+        # via the SDAM flow. We don't handle the possibility of a nil
+        # last_scan here.
         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
+                        server.cluster.heartbeat_interval
             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
+            staleness = max_write_date - server.last_write_date + server.cluster.heartbeat_interval
             staleness <= @max_staleness
           end
         end
@@ -441,6 +511,20 @@ module Mongo
         elsif @max_staleness && !max_staleness_allowed?
           raise Error::InvalidServerPreference.new(Error::InvalidServerPreference::NO_MAX_STALENESS_SUPPORT)
         end
+
+        if @hedge
+          unless hedge_allowed?
+            raise Error::InvalidServerPreference.new(Error::InvalidServerPreference::NO_HEDGE_SUPPORT)
+          end
+
+          unless @hedge.is_a?(Hash) && @hedge.key?(:enabled) &&
+              [true, false].include?(@hedge[:enabled])
+            raise Error::InvalidServerPreference.new(
+              "`hedge` value (#{hedge}) is invalid - hedge must be a Hash in the " \
+              "format { enabled: true }"
+            )
+          end
+        end
       end
 
       def validate_max_staleness_support!(server)
@@ -461,10 +545,10 @@ module Mongo
 
       def validate_max_staleness_value!(cluster)
         if @max_staleness
-          heartbeat_frequency_seconds = cluster.options[:heartbeat_frequency] || Server::Monitor::HEARTBEAT_FREQUENCY
+          heartbeat_interval = cluster.heartbeat_interval
           unless @max_staleness >= [
             SMALLEST_MAX_STALENESS_SECONDS,
-            min_cluster_staleness = heartbeat_frequency_seconds + Cluster::IDLE_WRITE_PERIOD_SECONDS,
+            min_cluster_staleness = heartbeat_interval + Cluster::IDLE_WRITE_PERIOD_SECONDS,
           ].max
             msg = "`max_staleness` value (#{@max_staleness}) is too small - it must be at least " +
               "`Mongo::ServerSelector::SMALLEST_MAX_STALENESS_SECONDS` (#{ServerSelector::SMALLEST_MAX_STALENESS_SECONDS}) and (the cluster's heartbeat_frequency " +
@@ -492,7 +576,11 @@ module Mongo
       # @param [ Numeric ] time_remaining Maximum time to wait, in seconds.
       def wait_for_server_selection(cluster, time_remaining)
         if cluster.server_selection_semaphore
-          cluster.server_selection_semaphore.wait(time_remaining)
+          # 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
+          # recheck the state.
+          cluster.server_selection_semaphore.wait([time_remaining, 1].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,4 +1,7 @@
-# Copyright (C) 2014-2019 MongoDB, Inc.
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2014-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -19,8 +22,7 @@ module Mongo
     #   of candidates.
     #
     # @since 2.0.0
-    class Nearest
-      include Selectable
+    class Nearest < Base
 
       # Name of the this read preference in the server's format.
       #
@@ -39,13 +41,12 @@ module Mongo
         :nearest
       end
 
-      # Whether the slaveOk bit should be set on wire protocol messages.
+      # Whether the secondaryOk bit should be set on wire protocol messages.
       #   I.e. whether the operation can be performed on a secondary server.
       #
       # @return [ true ] true
-      #
-      # @since 2.0.0
-      def slave_ok?
+      # @api private
+      def secondary_ok?
         true
       end
 
@@ -58,38 +59,44 @@ module Mongo
         true
       end
 
-      # Convert this server preference definition into a format appropriate
-      #   for a mongos server.
+      # Whether the hedge option is allowed to be defined for this server preference.
       #
-      # @example Convert this server preference definition into a format
-      #   for mongos.
-      #   preference = Mongo::ServerSelector::Nearest.new
-      #   preference.to_mongos
+      # @return [ true ] true
+      def hedge_allowed?
+        true
+      end
+
+      # Convert this server preference definition into a format appropriate
+      #   for sending to a MongoDB server (i.e., as a command field).
       #
-      # @return [ Hash ] The server preference formatted for a mongos server.
+      # @return [ Hash ] The server preference formatted as a command field value.
       #
       # @since 2.0.0
-      def to_mongos
-        @doc ||= (preference = { :mode => SERVER_FORMATTED_NAME }
-          preference.merge!({ :tags => tag_sets }) unless tag_sets.empty?
-          preference.merge!({ maxStalenessSeconds: max_staleness }) if max_staleness
-          preference)
+      def to_doc
+        full_doc
       end
-      alias :to_doc :to_mongos
+
+      # Convert this server preference definition into a value appropriate
+      #   for sending to a mongos.
+      #
+      # This method may return nil if the read preference should not be sent
+      # to a mongos.
+      #
+      # @return [ Hash | nil ] The server preference converted to a mongos
+      #   command field value.
+      #
+      # @since 2.0.0
+      alias :to_mongos :to_doc
 
       private
 
       # Select the near servers taking into account any defined tag sets and
       #   local threshold between the nearest server and other servers.
       #
-      # @example Select nearest servers given a list of candidates.
-      #   preference = Mongo::ServerSelector::Nearest.new
-      #   preference.select_server(cluster)
-      #
       # @return [ Array ] The nearest servers from the list of candidates.
       #
       # @since 2.0.0
-      def select(candidates)
+      def select_in_replica_set(candidates)
         matching_servers = filter_stale_servers(candidates, primary(candidates).first)
         matching_servers = match_tag_sets(matching_servers) unless tag_sets.empty?
         near_servers(matching_servers)

data/lib/mongo/server_selector/primary.rb

@@ -1,4 +1,7 @@
-# Copyright (C) 2014-2019 MongoDB, Inc.
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2014-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -20,8 +23,7 @@ module Mongo
     #   of candidates.
     #
     # @since 2.0.0
-    class Primary
-      include Selectable
+    class Primary < Base
 
       # Name of the this read preference in the server's format.
       #
@@ -40,13 +42,12 @@ module Mongo
         :primary
       end
 
-      # Whether the slaveOk bit should be set on wire protocol messages.
+      # Whether the secondaryOk bit should be set on wire protocol messages.
       #   I.e. whether the operation can be performed on a secondary server.
       #
       # @return [ false ] false
-      #
-      # @since 2.0.0
-      def slave_ok?
+      # @api private
+      def secondary_ok?
         false
       end
 
@@ -59,48 +60,45 @@ module Mongo
         false
       end
 
-      # Convert this server preference definition into a format appropriate
-      #   for a mongos server.
-      #
-      # @example Convert this server preference definition into a format
-      #   for mongos.
-      #   preference = Mongo::ServerSelector::Primary.new
-      #   preference.to_mongos
-      #
-      # @return [ nil ] nil
+      # Whether the hedge option is allowed to be defined for this server preference.
       #
-      # @since 2.0.0
-      def to_mongos
-        nil
+      # @return [ false ] false
+      def hedge_allowed?
+        false
       end
 
       # Convert this server preference definition into a format appropriate
-      #   for a mongodb server.
+      #   for sending to a MongoDB server (i.e., as a command field).
       #
-      # @example Convert this server preference definition into a format
-      #   for a server.
-      #   preference = Mongo::ServerSelector::Primary.new
-      #   preference.to_doc
-      #
-      # @return [ Hash ] The server preference formatted for a mongodb server.
+      # @return [ Hash ] The server preference formatted as a command field value.
       #
       # @since 2.5.0
       def to_doc
-        @doc ||= { mode: SERVER_FORMATTED_NAME }
+        { mode: SERVER_FORMATTED_NAME }
+      end
+
+      # Convert this server preference definition into a value appropriate
+      #   for sending to a mongos.
+      #
+      # This method may return nil if the read preference should not be sent
+      # to a mongos.
+      #
+      # @return [ Hash | nil ] The server preference converted to a mongos
+      #   command field value.
+      #
+      # @since 2.0.0
+      def to_mongos
+        nil
       end
 
       private
 
       # Select the primary server from a list of candidates.
       #
-      # @example Select the primary server given a list of candidates.
-      #   preference = Mongo::ServerSelector::Primary.new
-      #   preference.select([candidate_1, candidate_2])
-      #
       # @return [ Array ] The primary server from the list of candidates.
       #
       # @since 2.0.0
-      def select(candidates)
+      def select_in_replica_set(candidates)
         primary(candidates)
       end