mongo 2.4.1 → 2.14.0

data/lib/mongo/operation/shared/response_handling.rb

@@ -0,0 +1,169 @@
+# Copyright (C) 2019-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.
+# 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
+  module Operation
+
+    # Shared behavior of response handling for operations.
+    #
+    # @api private
+    module ResponseHandling
+
+      private
+
+      def validate_result(result, client, connection)
+        unpin_maybe(session) do
+          add_error_labels(client, connection, session) do
+            add_server_diagnostics(connection) do
+              result.validate!
+            end
+          end
+        end
+      end
+
+      # Adds error labels to exceptions raised in the yielded to block,
+      # which should perform MongoDB operations and raise Mongo::Errors on
+      # failure. This method handles network errors (Error::SocketError)
+      # and server-side errors (Error::OperationFailure); it does not
+      # handle server selection errors (Error::NoServerAvailable), for which
+      # labels are added in the server selection code.
+      def add_error_labels(client, connection, session)
+        begin
+          yield
+        rescue Mongo::Error::SocketError => e
+          if session && session.in_transaction? && !session.committing_transaction?
+            e.add_label('TransientTransactionError')
+          end
+          if session && session.committing_transaction?
+            e.add_label('UnknownTransactionCommitResult')
+          end
+
+          maybe_add_retryable_write_error_label!(e, connection, client, session)
+
+          raise e
+        rescue Mongo::Error::SocketTimeoutError => e
+          maybe_add_retryable_write_error_label!(e, connection, client, session)
+          raise e
+        rescue Mongo::Error::OperationFailure => e
+          if session && session.committing_transaction?
+            if e.write_retryable? || e.wtimeout? || (e.write_concern_error? &&
+                !Session::UNLABELED_WRITE_CONCERN_CODES.include?(e.write_concern_error_code)
+            ) || e.max_time_ms_expired?
+              e.add_label('UnknownTransactionCommitResult')
+            end
+          end
+
+          maybe_add_retryable_write_error_label!(e, connection, client, session)
+
+          raise e
+        end
+      end
+
+      # Unpins the session if the session is pinned and the yielded to block
+      # raises errors that are required to unpin the session.
+      #
+      # @note This method takes the session as an argument because this module
+      #   is included in BulkWrite which does not store the session in the
+      #   receiver (despite Specifiable doing so).
+      #
+      # @param [ Session | nil ] session Session to consider.
+      def unpin_maybe(session)
+        yield
+      rescue Mongo::Error => e
+        if session
+          session.unpin_maybe(e)
+        end
+        raise
+      end
+
+      # Yields to the block and, if the block raises an exception, adds a note
+      # to the exception with the address of the specified server.
+      #
+      # This method is intended to add server address information to exceptions
+      # raised during execution of operations on servers.
+      def add_server_diagnostics(connection)
+        yield
+      rescue Error::SocketError, Error::SocketTimeoutError
+        # Diagnostics should have already been added by the connection code,
+        # do not add them again.
+        raise
+      rescue Error, Error::AuthError => e
+        e.add_note("on #{connection.address.seed}")
+        e.generation = connection.generation
+        raise e
+      end
+
+      private
+
+      # A method that will add the RetryableWriteError label to an error if
+      # any of the following conditions are true:
+      #
+      # The error meets the criteria for a retryable error (i.e. has one
+      #   of the retryable error codes or error messages)
+      #
+      # AND the server does not support adding the RetryableWriteError label OR
+      #   the error is a network error (i.e. the driver must add the label)
+      #
+      # AND the error occured during a commitTransaction or abortTransaction
+      #   OR the error occured during a write outside of a transaction on a
+      #   client that has retry writes enabled.
+      #
+      # If these conditions are met, the original error will be mutated.
+      # If they're not met, the error will not be changed.
+      #
+      # @param [ Mongo::Error ] error The error to which to add the label.
+      # @param [ Mongo::Server::Connection ] connection The connection on which
+      #   the operation is performed.
+      # @param [ Mongo::Client | nil ] client The client that is performing
+      #   the operation.
+      # @param [ Mongo::Session ] session The operation's session.
+      #
+      # @note The client argument is optional because some operations, such as
+      #   end_session, do not pass the client as an argument to the execute
+      #   method.
+      def maybe_add_retryable_write_error_label!(error, connection, client, session)
+        in_transaction = session && session.in_transaction?
+        committing_transaction = in_transaction && session.committing_transaction?
+        aborting_transaction = in_transaction && session.aborting_transaction?
+        modern_retry_writes = client && client.options[:retry_writes]
+        legacy_retry_writes = client && !client.options[:retry_writes] &&
+          client.max_write_retries > 0
+
+        # An operation is retryable if it meets one of the following criteria:
+        # - It is a commitTransaction or abortTransaction
+        # - It does not occur during a transaction and the client has enabled
+        #   modern or legacy writes
+        #
+        # Note: any write operation within a transaction (excepting commit and
+        # abort is NOT a retryable operation)
+        retryable_operation = committing_transaction || aborting_transaction ||
+          (!in_transaction && (modern_retry_writes || legacy_retry_writes))
+
+        # An operation should add the RetryableWriteError label if one of the
+        # following conditions is met:
+        # - The server does not support adding the RetryableWriteError label
+        # - The error is a network error
+        should_add_error_label =
+          !connection.description.features.retryable_write_error_label_enabled? ||
+          error.write_concern_error_label?('RetryableWriteError') ||
+          error.is_a?(Mongo::Error::SocketError) ||
+          error.is_a?(Mongo::Error::SocketTimeoutError)
+
+        if retryable_operation && should_add_error_label && error.write_retryable?
+          error.add_label('RetryableWriteError')
+        end
+      end
+    end
+  end
+end

data/lib/mongo/operation/shared/result/aggregatable.rb

@@ -0,0 +1,71 @@
+# 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.
+# 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
+  module Operation
+    class Result
+
+      # Defines custom behavior of bulk write results
+      #
+      # @since 2.0.0
+      # @api private
+      module Aggregatable
+
+        # Aggregate the write errors returned from this result.
+        #
+        # @example Aggregate the write errors.
+        #   result.aggregate_write_errors(0)
+        #
+        # @param [ Integer ] count The number of documents already executed.
+        #
+        # @return [ Array ] The aggregate write errors.
+        #
+        # @since 2.0.0
+        def aggregate_write_errors(count)
+          return unless @replies
+          @replies.reduce(nil) do |errors, reply|
+            if write_errors = reply.documents.first['writeErrors']
+              wes = write_errors.collect do |we|
+                we.merge!('index' => count + we['index'])
+              end
+              (errors || []) << wes if wes
+            end
+          end
+        end
+
+        # Aggregate the write concern errors returned from this result.
+        #
+        # @example Aggregate the write concern errors.
+        #   result.aggregate_write_concern_errors(100)
+        #
+        # @param [ Integer ] count The number of documents already executed.
+        #
+        # @return [ Array ] The aggregate write concern errors.
+        #
+        # @since 2.0.0
+        def aggregate_write_concern_errors(count)
+          return unless @replies
+          @replies.each_with_index.reduce(nil) do |errors, (reply, _)|
+            if write_concern_errors = reply.documents.first['writeConcernErrors']
+              (errors || []) << write_concern_errors.reduce(nil) do |errs, wce|
+                wce.merge!('index' => count + wce['index'])
+                (errs || []) << write_concern_error
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongo/operation/shared/result/use_legacy_error_parser.rb

@@ -0,0 +1,29 @@
+# Copyright (C) 2019-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.
+# 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
+  module Operation
+    class Result
+
+      # This module creates the Parser instance in legacy mode.
+      #
+      # @api private
+      module UseLegacyErrorParser
+        def parser
+          @parser ||= Error::Parser.new(first_document, replies, legacy: true)
+        end
+      end
+    end
+  end
+end

data/lib/mongo/operation/shared/sessions_supported.rb

@@ -0,0 +1,239 @@
+# Copyright (C) 2015-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.
+# 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
+  module Operation
+
+    # Shared behavior of operations that support a session.
+    #
+    # @since 2.5.2
+    # @api private
+    module SessionsSupported
+
+      private
+
+      ZERO_TIMESTAMP = BSON::Timestamp.new(0, 0)
+
+      READ_COMMANDS = [
+        :aggregate,
+        :collStats,
+        :count,
+        :dbStats,
+        :distinct,
+        :find,
+        :geoNear,
+        :geoSearch,
+        :group,
+        :mapReduce,
+        :parallelCollectionScan
+      ].freeze
+
+      # Adds causal consistency document to the selector, if one can be
+      # constructed and the selector is for a startTransaction command.
+      #
+      # When operations are performed in a transaction, only the first
+      # operation (the one which starts the transaction via startTransaction)
+      # is allowed to have a read concern, and with it the causal consistency
+      # document, specified.
+      def apply_causal_consistency!(selector, connection)
+        return unless selector[:startTransaction]
+
+        apply_causal_consistency_if_possible(selector, connection)
+      end
+
+      # Adds causal consistency document to the selector, if one can be
+      # constructed.
+      #
+      # In order for the causal consistency document to be constructed,
+      # causal consistency must be enabled for the session and the session
+      # must have the current operation time. Also, topology must be
+      # replica set or sharded cluster.
+      def apply_causal_consistency_if_possible(selector, connection)
+        if !connection.description.standalone?
+          cc_doc = session.send(:causal_consistency_doc)
+          if cc_doc
+            rc_doc = (selector[:readConcern] || read_concern || {}).merge(cc_doc)
+            selector[:readConcern] = Options::Mapper.transform_values_to_strings(
+              rc_doc)
+          end
+        end
+      end
+
+      def flags
+        acknowledged_write? ? [] : [:more_to_come]
+      end
+
+      def apply_cluster_time!(selector, connection)
+        if !connection.description.standalone?
+          cluster_time = [
+            connection.cluster_time,
+            session&.cluster_time,
+          ].compact.max
+
+          if cluster_time
+            selector['$clusterTime'] = cluster_time
+          end
+        end
+      end
+
+      def read_command?(sel)
+        READ_COMMANDS.any? { |c| sel[c] }
+      end
+
+      def add_write_concern!(sel)
+        sel[:writeConcern] = write_concern.options if write_concern
+      end
+
+      def apply_autocommit!(selector)
+        session.add_autocommit!(selector)
+      end
+
+      def apply_start_transaction!(selector)
+        session.add_start_transaction!(selector)
+      end
+
+      def apply_txn_num!(selector)
+        session.add_txn_num!(selector)
+      end
+
+      def apply_read_pref!(selector)
+        session.apply_read_pref!(selector) if read_command?(selector)
+      end
+
+      def apply_txn_opts!(selector)
+        session.add_txn_opts!(selector, read_command?(selector))
+      end
+
+      def suppress_read_write_concern!(selector)
+        session.suppress_read_write_concern!(selector)
+      end
+
+      def validate_read_preference!(selector)
+        session.validate_read_preference!(selector) if read_command?(selector)
+      end
+
+      def command(connection)
+        if Lint.enabled?
+          unless connection.is_a?(Server::Connection)
+            raise Error::LintError, "Connection is not a Connection instance: #{connection}"
+          end
+        end
+
+        sel = selector(connection).dup
+        add_write_concern!(sel)
+        sel[Protocol::Msg::DATABASE_IDENTIFIER] = db_name
+
+        add_read_preference(sel, connection)
+
+        if connection.features.sessions_enabled?
+          apply_cluster_time!(sel, connection)
+          if session && (acknowledged_write? || session.in_transaction?)
+            apply_session_options(sel, connection)
+          end
+        elsif session && session.explicit?
+          apply_session_options(sel, connection)
+        end
+
+        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::Connection ] connection The connection that the
+      #   operation will be executed on.
+      def add_read_preference(sel, connection)
+        Lint.assert_type(connection, Server::Connection)
+
+        # https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#topology-type-single
+        if connection.description.standalone?
+          # Read preference is never sent to standalones.
+        elsif connection.description.mongos?
+          # When server is a mongos:
+          # - $readPreference is never sent when mode is 'primary'
+          # - When mode is 'secondaryPreferred' $readPreference is only sent
+          #   when a non-mode field (i.e. tag_sets) is present
+          # - Otherwise $readPreference is sent
+          if read
+            doc = read.to_mongos
+            if doc
+              sel['$readPreference'] = doc
+            end
+          end
+        elsif connection.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, 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, connection)
+        apply_cluster_time!(sel, connection)
+        sel[:txnNumber] = BSON::Int64.new(txn_num) if txn_num
+        sel.merge!(lsid: session.session_id)
+        apply_start_transaction!(sel)
+        apply_causal_consistency!(sel, connection)
+        apply_autocommit!(sel)
+        apply_txn_opts!(sel)
+        suppress_read_write_concern!(sel)
+        validate_read_preference!(sel)
+        apply_txn_num!(sel)
+        if session.recovery_token &&
+          (sel[:commitTransaction] || sel[:abortTransaction])
+        then
+          sel[:recoveryToken] = session.recovery_token
+        end
+      end
+
+      def build_message(connection)
+        super.tap do |message|
+          if session
+            # Serialize the message to detect client-side problems,
+            # such as invalid BSON keys. The message will be serialized again
+            # later prior to being sent to the connection.
+            message.serialize(BSON::ByteBuffer.new)
+
+            session.update_state!
+          end
+        end
+      end
+    end
+  end
+end