RUBY-2219 Force read preference primaryPreferred in Single topology (#1868)

Co-authored-by: Oleg Pudeyev <oleg@bsdpower.com>

Author: 2 people

docs/tutorials/ruby-driver-crud-operations.txt

@@ -292,9 +292,9 @@ Read Preference
 ~~~~~~~~~~~~~~~
 
 Read preference determines the candidate :manual:`replica set</replication/>`
-members to which a query or command can be sent. They consist of a **mode** specified as
-a symbol, an array of hashes known as **tag_sets**, and two timing options:
-**local_threshold** and **server_selection_timeout**.
+members to which a query or command can be sent. They consist of a **mode**
+specified as a symbol, an array of hashes known as **tag_sets**, and two
+timing options: **local_threshold** and **server_selection_timeout**.
 
 ``local_threshold``
   Defines the upper limit in seconds of the latency window
@@ -305,6 +305,12 @@ a symbol, an array of hashes known as **tag_sets**, and two timing options:
   Defines how long to block for server selection
   before throwing an exception. The default is 30,000 milliseconds, or 30 seconds.
 
+.. note::
+
+  Read preference does not apply to Standalone deployments. When a client
+  is connected to a Standalone deployment, any application-specified read
+  preference is ignored.
+
 For more information on the algorithm used to select a server, please
 refer to the `Server Selection documentation, available on GitHub
 <https://github.com/mongodb/specifications/blob/master/source/server-sel
@@ -337,17 +343,29 @@ using the ``with`` method:
 Mode
 ~~~~
 
-There are five possible read preference modes. They are ``:primary``,
-``:secondary``, ``:primary_preferred``, ``:secondary_preferred``,
-``:nearest``. Please see the :manual:`read preference documentation in the MongoDB Manual
-</core/read-preference/>` for an explanation of the modes and tag sets.
+There are five possible read preference modes: ``:primary``, ``:secondary``,
+``:primary_preferred``, ``:secondary_preferred`` and``:nearest``.
+Please see the :manual:`read preference documentation in the MongoDB Manual
+</core/read-preference/>` for an explanation of the modes.
+
+.. note::
+
+  When a client is directly connected to a server using the ``:direct_connection``
+  Ruby option or the ``directConnection`` URI option, read preference mode
+  is automatically set to ``:primary_preferred`` to permit read operations
+  against secondaries. If the application specified a ``:primary`` read
+  preference mode, the mode is automatically converted to ``:primary_preferred``.
+  If another read preference mode is specified, it is passed to the server
+  unchanged.
 
 Tag sets
 ~~~~~~~~
 
 The ``tag_sets`` parameter is an ordered list of tag sets used to
 restrict the eligibility of servers for selection, such as for data
-center awareness.
+center awareness. Please see the :manual:`read preference documentation in
+the MongoDB Manual </core/read-preference/>` for an explanation of tag sets.
+
 
 A read preference tag set (T) matches a server tag set (S) – or
 equivalently a server tag set (S) matches a read preference tag set

lib/mongo/operation/shared/read_preference_supported.rb

@@ -15,19 +15,83 @@
 module Mongo
   module Operation
 
-    # Shared behavior of operations that support read preference.
+    # Read preference handling for pre-OP_MSG operation implementations.
+    #
+    # This module is not used by OP_MSG operation classes (those deriving
+    # from OpMsgBase). Instead, read preference for those classes is handled
+    # in SessionsSupported module.
     #
     # @since 2.5.2
+    # @api private
     module ReadPreferenceSupported
 
       private
 
-      SLAVE_OK = :slave_ok
-
+      # Get the options for executing the operation on a particular server.
+      #
+      # @param [ Server ] server The server that the operation will be
+      #   executed on.
+      #
+      # @return [ Hash ] The options.
+      #
+      # @since 2.0.0
       def options(server)
-        update_options_for_slave_ok(super, server)
+        add_slave_ok_flag_maybe(super, server)
+      end
+
+      # Adds :slave_ok flag to options based on the read preference specified
+      # in the operation or implied by the topology that the server is a
+      # part of.
+      #
+      # @param [ Hash ] options The options calculated so far.
+      #
+      # @return [ Hash ] The new options.
+      def add_slave_ok_flag_maybe(options, server)
+        add_flag =
+          # https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#topology-type-single
+          if server.standalone?
+            # Read preference is never sent to standalones.
+            false
+          elsif server.cluster.single?
+            # In Single topology the driver forces primaryPreferred read
+            # preference mode (via the slave_ok flag, in case of old servers)
+            # so that the query is satisfied.
+            true
+          else
+            # In replica sets and sharded clusters, read preference is passed
+            # to the server if one is specified by the application, and there
+            # is no default.
+            read && read.slave_ok?
+          end
+
+        if add_flag
+          options= options.dup
+          (options[:flags] ||= []) << :slave_ok
+        end
+
+        options
       end
 
+      def command(server)
+        sel = super
+        update_selector_for_read_pref(sel, server)
+      end
+
+      # Adds $readPreference field to the command document.
+      #
+      # $readPreference is only sent when the server is a mongos,
+      # following the rules described in
+      # https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#passing-read-preference-to-mongos.
+      # The topology does not matter for figuring out whether to send
+      # $readPreference since the decision is always made based on
+      # server type.
+      #
+      # $readPreference is not sent to pre-OP_MSG replica set members.
+      #
+      # @param [ Hash ] sel Existing command document.
+      # @param [ Server ] server The server that the command is to be sent to.
+      #
+      # @return [ Hash ] New command document to send to the server.
       def update_selector_for_read_pref(sel, server)
         if read && server.mongos? && read_pref = read.to_mongos
           Mongo::Lint.validate_camel_case_read_preference(read_pref)
@@ -37,21 +101,6 @@ def update_selector_for_read_pref(sel, server)
           sel
         end
       end
-
-      def update_options_for_slave_ok(opts, server)
-        if (server.cluster.single? && !server.mongos?) || (read && read.slave_ok?)
-          opts.dup.tap do |o|
-            (o[:flags] ||= []) << SLAVE_OK
-          end
-        else
-          opts
-        end
-      end
-
-      def command(server)
-        sel = super
-        update_selector_for_read_pref(sel, server)
-      end
     end
   end
 end

lib/mongo/operation/shared/sessions_supported.rb

@@ -123,9 +123,8 @@ def command(server)
         sel = selector(server).dup
         add_write_concern!(sel)
         sel[Protocol::Msg::DATABASE_IDENTIFIER] = db_name
-        unless server.standalone?
-          sel['$readPreference'] = read.to_doc if read
-        end
+
+        add_read_preference(sel, server)
 
         if server.features.sessions_enabled?
           apply_cluster_time!(sel, server)
@@ -139,6 +138,48 @@ def command(server)
         sel
       end
 
+      # Adds $readPreference field to the command document.
+      #
+      # $readPreference is only sent when the server is a mongos,
+      # following the rules described in
+      # https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#passing-read-preference-to-mongos.
+      # The topology does not matter for figuring out whether to send
+      # $readPreference since the decision is always made based on
+      # server type.
+      #
+      # $readPreference is sent to OP_MSG-grokking replica set members.
+      #
+      # @param [ Hash ] sel Existing command document which will be mutated.
+      # @param [ Server ] server The server that the command is to be sent to.
+      def add_read_preference(sel, server)
+        # https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#topology-type-single
+        if server.standalone?
+          # Read preference is never sent to standalones.
+        elsif server.cluster.single?
+          # In Single topology:
+          # - If no read preference is specified by the application, the driver
+          #   adds mode: primaryPreferred.
+          # - If a read preference is specified by the application, the driver
+          #   replaces the mode with primaryPreferred.
+          read_doc = if read
+            BSON::Document.new(read.to_doc)
+          else
+            BSON::Document.new
+          end
+          if [nil, 'primary'].include?(read_doc['mode'])
+            read_doc['mode'] = 'primaryPreferred'
+          end
+          sel['$readPreference'] = read_doc
+        else
+          # In replica sets and sharded clusters, read preference is passed
+          # to the server if one is specified by the application, and there
+          # is no default.
+          if read
+            sel['$readPreference'] = read.to_doc
+          end
+        end
+      end
+
       def apply_session_options(sel, server)
         apply_cluster_time!(sel, server)
         sel[:txnNumber] = BSON::Int64.new(txn_num) if txn_num

spec/integration/read_preference_spec.rb

@@ -482,4 +482,30 @@
       end
     end
   end
+
+  context 'secondary read with direct connection' do
+    require_topology :replica_set
+
+    let(:address_str) do
+      Mongo::ServerSelector.get(mode: :secondary).
+        select_server(authorized_client.cluster).address.seed
+    end
+
+    let(:secondary_client) do
+      new_local_client([address_str],
+        SpecConfig.instance.all_test_options.merge(connect: :direct))
+    end
+
+    it 'succeeds without read preference' do
+      secondary_client['foo'].find.to_a
+    end
+
+    it 'succeeds with read preference: secondary' do
+      secondary_client['foo', {read: {mode: :secondary}}].find.to_a
+    end
+
+    it 'succeeds with read preference: primary' do
+      secondary_client['foo', {read: {mode: :primary}}].find.to_a
+    end
+  end
 end

spec/mongo/operation/find/legacy_spec.rb

@@ -71,6 +71,7 @@
       let(:secondary_server_single) do
         double('secondary_server').tap do |server|
           allow(server).to receive(:mongos?) { false }
+          allow(server).to receive(:standalone?) { false }
           allow(server).to receive(:cluster) { cluster_single }
           allow(server).to receive(:features) { authorized_primary.features }
         end