mongo 2.15.0 → 2.18.1

data/lib/mongo/dbref.rb

@@ -16,109 +16,5 @@
 # limitations under the License.
 
 module Mongo
-
-  # Represents a DBRef document in the database.
-  #
-  # @since 2.1.0
-  class DBRef
-    include BSON::JSON
-
-    # The constant for the collection reference field.
-    #
-    # @since 2.1.0
-    COLLECTION = '$ref'.freeze
-
-    # The constant for the id field.
-    #
-    # @since 2.1.0
-    ID = '$id'.freeze
-
-    # The constant for the database field.
-    #
-    # @since 2.1.0
-    DATABASE = '$db'.freeze
-
-    # @return [ String ] collection The collection name.
-    attr_reader :collection
-
-    # @return [ BSON::ObjectId ] id The referenced document id.
-    attr_reader :id
-
-    # @return [ String ] database The database name.
-    attr_reader :database
-
-    # Get the DBRef as a JSON document
-    #
-    # @example Get the DBRef as a JSON hash.
-    #   dbref.as_json
-    #
-    # @return [ Hash ] The max key as a JSON hash.
-    #
-    # @since 2.1.0
-    def as_json(*args)
-      document = { COLLECTION => collection, ID => id }
-      document.merge!(DATABASE => database) if database
-      document
-    end
-
-    # Instantiate a new DBRef.
-    #
-    # @example Create the DBRef.
-    #   Mongo::DBRef.new('users', id, 'database')
-    #
-    # @param [ String ] collection The collection name.
-    # @param [ BSON::ObjectId ] id The object id.
-    # @param [ String ] database The database name.
-    #
-    # @since 2.1.0
-    def initialize(collection, id, database = nil)
-      @collection = collection
-      @id = id
-      @database = database
-    end
-
-    # Converts the DBRef to raw BSON.
-    #
-    # @example Convert the DBRef to raw BSON.
-    #   dbref.to_bson
-    #
-    # @param [ BSON::ByteBuffer ] buffer The encoded BSON buffer to append to.
-    # @param [ true, false ] validating_keys Whether keys should be validated when serializing.
-    #
-    # @return [ String ] The raw BSON.
-    #
-    # @since 2.1.0
-    def to_bson(buffer = BSON::ByteBuffer.new, validating_keys = BSON::Config.validating_keys?)
-      as_json.to_bson(buffer)
-    end
-
-    module ClassMethods
-
-      # Deserialize the hash from BSON, converting to a DBRef if appropriate.
-      #
-      # @param [ String ] buffer The bson representing a hash.
-      #
-      # @return [ Hash, DBRef ] The decoded hash or DBRef.
-      #
-      # @see http://bsonspec.org/#/specification
-      #
-      # @since 2.0.0
-      def from_bson(buffer, **options)
-        # bson-ruby 4.8.0 changes #from_bson API to take **options.
-        # However older bsons fail if invoked with a plain super here,
-        # even if options are empty.
-        decoded = if options.empty?
-          super(buffer)
-        else
-          super
-        end
-        if ref = decoded[COLLECTION]
-          decoded = DBRef.new(ref, decoded[ID], decoded[DATABASE])
-        end
-        decoded
-      end
-    end
-  end
-
-  ::Hash.send(:extend, DBRef::ClassMethods)
+  DBRef = BSON::DBRef
 end

data/lib/mongo/error/bad_load_balancer_target.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2021 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 Error
+
+    # Raised when the driver is in load-balancing mode but a connection
+    # is established to something other than a mongos.
+    class BadLoadBalancerTarget < Error
+    end
+  end
+end

data/lib/mongo/error/bulk_write_error.rb

@@ -55,15 +55,42 @@ module Mongo
 
       private
 
+      # Generates an error message when there are multiple write errors.
+      #
+      # @example Multiple documents fail validation
+      #
+      # col has validation { 'validator' => { 'x' => { '$type' => 'string' } } }
+      # col.insert_many([{_id: 1}, {_id: 2}], ordered: false)
+      #
+      # Multiple errors:
+      #   [121]: Document failed validation --
+      #     {"failingDocumentId":1,"details":{"operatorName":"$type",
+      #     "specifiedAs":{"x":{"$type":"string"}},"reason":"field was
+      #     missing"}};
+      #   [121]: Document failed validation --
+      #     {"failingDocumentId":2, "details":{"operatorName":"$type",
+      #     "specifiedAs":{"x":{"$type":"string"}}, "reason":"field was
+      #     missing"}}
+      #
+      # @return [ String ] The error message
       def build_message
         errors = @result['writeErrors']
         return nil unless errors
 
-        fragment = errors.first(10).map do |error|
-          "[#{error['code']}]: #{error['errmsg']}"
-        end.join('; ')
+        fragment = ""
+        cut_short = false
+        errors.first(10).each_with_index do |error, i|
+          fragment += "; " if fragment.length > 0
+          fragment += "[#{error['code']}]: #{error['errmsg']}"
+          fragment += " -- #{error['errInfo'].to_json}" if error['errInfo']
+
+          if fragment.length > 3000
+            cut_short = i < [9, errors.length].min
+            break
+          end
+        end
 
-        fragment += '...' if errors.length > 10
+        fragment += '...' if errors.length > 10 || cut_short
 
         if errors.length > 1
           fragment = "Multiple errors: #{fragment}"

data/lib/mongo/error/invalid_config_option.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Mongo
+  class Error
+
+    # This error is raised when a bad configuration option is attempted to be
+    # set.
+    class InvalidConfigOption < Error
+
+      # Create the new error.
+      #
+      # @param [ Symbol, String ] name The attempted config option name.
+      #
+      # @api private
+      def initialize(name)
+        super("Invalid config option #{name}.")
+      end
+    end
+  end
+end

data/lib/mongo/error/invalid_replacement_document.rb

@@ -19,23 +19,41 @@ module Mongo
   class Error
 
     # Exception raised if the object is not a valid replacement document.
-    #
-    # @since 2.0.0
     class InvalidReplacementDocument < Error
 
       # The error message.
       #
-      # @since 2.0.0
+      # @deprecated
       MESSAGE = 'Invalid replacement document provided'.freeze
 
-      # Instantiate the new exception.
+      # Construct the error message.
+      #
+      # @param [ String ] key The invalid key.
+      #
+      # @return [ String ] The error message.
       #
-      # @example Instantiate the exception.
-      #   Mongo::Error::InvalidReplacementDoc.new
+      # @api private
+      def self.message(key)
+        message = "Invalid replacement document provided. Replacement documents "
+        message += "must not contain atomic modifiers. The \"#{key}\" key is invalid."
+        message
+      end
+
+      # Send and cache the warning.
+      #
+      # @api private
+      def self.warn(logger, key)
+        @warned ||= begin
+          logger.warn(message(key))
+          true
+        end
+      end
+
+      # Instantiate the new exception.
       #
-      # @since 2.0.0
-      def initialize
-        super(MESSAGE)
+      # @param [ String ] :key The invalid key.
+      def initialize(key: nil)
+        super(self.class.message(key))
       end
     end
   end

data/lib/mongo/error/invalid_update_document.rb

@@ -25,17 +25,37 @@ module Mongo
 
       # The error message.
       #
-      # @since 2.0.0
+      # @deprecated
       MESSAGE = 'Invalid update document provided'.freeze
 
-      # Instantiate the new exception.
+      # Construct the error message.
+      #
+      # @param [ String ] key The invalid key.
+      #
+      # @return [ String ] The error message.
       #
-      # @example Instantiate the exception.
-      #   Mongo::Error::InvalidUpdateDocument.new
+      # @api private
+      def self.message(key)
+        message = "Invalid update document provided. Updates documents must only "
+        message += "contain only atomic modifiers. The \"#{key}\" key is invalid."
+        message
+      end
+
+      # Send and cache the warning.
+      #
+      # @api private
+      def self.warn(logger, key)
+        @warned ||= begin
+          logger.warn(message(key))
+          true
+        end
+      end
+
+      # Instantiate the new exception.
       #
-      # @since 2.0.0
-      def initialize
-        super(MESSAGE)
+      # @param [ String ] :key The invalid key.
+      def initialize(key: nil)
+        super(self.class.message(key))
       end
     end
   end

data/lib/mongo/error/labelable.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2019-2022 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 Error
+
+    # A module encapsulating functionality to manage labels added to errors.
+    #
+    # @note Although methods of this module are part of the public API,
+    #   the fact that these methods are defined on this module and not on
+    #   the classes which include this module is not part of the public API.
+    #
+    # @api semipublic
+    module Labelable
+
+      # Does the error have the given label?
+      #
+      # @example
+      #   error.label?(label)
+      #
+      # @param [ String ] label The label to check if the error has.
+      #
+      # @return [ true, false ] Whether the error has the given label.
+      #
+      # @since 2.6.0
+      def label?(label)
+        @labels && @labels.include?(label)
+      end
+
+      # Gets the set of labels associated with the error.
+      #
+      # @example
+      #   error.labels
+      #
+      # @return [ Array ] The set of labels.
+      #
+      # @since 2.7.0
+      def labels
+        if @labels
+          @labels.dup
+        else
+          []
+        end
+      end
+
+      # Adds the specified label to the error instance, if the label is not
+      # already in the set of labels.
+      #
+      # @param [ String ] label The label to add.
+      #
+      # @api private
+      def add_label(label)
+        @labels ||= []
+        @labels << label unless label?(label)
+      end
+    end
+  end
+end

data/lib/mongo/error/missing_connection.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2022 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 Error
+
+    # Exception raised when trying to check out connection that does not exist.
+    class MissingConnection < Error
+    end
+  end
+end

data/lib/mongo/error/missing_file_chunk.rb

@@ -30,11 +30,17 @@ module Mongo
       #   Mongo::Error::MissingFileChunk.new(expected_n, chunk)
       #
       # @param [ Integer ] expected_n The expected index value.
-      # @param [ Grid::File::Chunk ] chunk The chunk read from GridFS.
+      # @param [ Grid::File::Chunk | Integer ] chunk The chunk read from GridFS.
       #
       # @since 2.1.0
+      #
+      # @api private
       def initialize(expected_n, chunk)
-        super("Unexpected chunk in sequence. Expected next chunk to have index #{expected_n} but it has index #{chunk.n}")
+        if chunk.is_a?(Integer)
+          super("Missing chunk(s). Expected #{expected_n} chunks but got #{chunk}.")
+        else
+          super("Unexpected chunk in sequence. Expected next chunk to have index #{expected_n} but it has index #{chunk.n}")
+        end
       end
     end
   end

data/lib/mongo/error/missing_service_id.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2021 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 Error
+
+    # Raised when the driver is in load-balancing mode via the URI option
+    # but a connection does not report a value in the serviceId field.
+    class MissingServiceId < Error
+    end
+  end
+end

data/lib/mongo/error/no_service_connection_available.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2021 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 Error
+
+    # Raised when the driver requires a connection to a particular service
+    # but no matching connections exist in the connection pool.
+    class NoServiceConnectionAvailable < Error
+      # @api private
+      def initialize(message, address:, service_id:)
+        super(message)
+
+        @address = address
+        @service_id = service_id
+      end
+
+      # @return [ Mongo::Address ] The address to which a connection was
+      #   requested.
+      attr_reader :address
+
+      # @return [ nil | Object ] The service id.
+      attr_reader :service_id
+
+      # @api private
+      def self.generate(address:, service_id:)
+        new(
+          "The connection pool for #{address} does not have a connection for service #{service_id}",
+          address: address,
+          service_id: service_id,
+        )
+      end
+    end
+  end
+end

data/lib/mongo/error/notable.rb

@@ -63,6 +63,20 @@ module Mongo
       # @return [ Integer | nil ] Connection pool generation.
       attr_accessor :generation
 
+      # Returns service id for the connection on which the error occurred.
+      #
+      # @return [ Object | nil ] Service id.
+      #
+      # @api experimental
+      attr_accessor :service_id
+
+      # Returns global id of the connection on which the error occurred.
+      #
+      # @return [ Integer | nil ] Connection global id.
+      #
+      # @api private
+      attr_accessor :connection_global_id
+
       # @api public
       def to_s
         super + notes_tail

data/lib/mongo/error/operation_failure.rb

@@ -14,6 +14,7 @@
 # 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.
+require 'mongo/error/read_write_retryable'
 
 module Mongo
   class Error
@@ -24,53 +25,7 @@ module Mongo
     class OperationFailure < Error
       extend Forwardable
       include SdamErrorDetection
-
-      # Error codes and code names that should result in a failing write
-      # being retried.
-      #
-      # @since 2.6.0
-      # @api private
-      WRITE_RETRY_ERRORS = [
-        {:code_name => 'HostUnreachable', :code => 6},
-        {:code_name => 'HostNotFound', :code => 7},
-        {:code_name => 'NetworkTimeout', :code => 89},
-        {:code_name => 'ShutdownInProgress', :code => 91},
-        {:code_name => 'PrimarySteppedDown', :code => 189},
-        {:code_name => 'ExceededTimeLimit', :code => 262},
-        {:code_name => 'SocketException', :code => 9001},
-        {:code_name => 'NotMaster', :code => 10107},
-        {:code_name => 'InterruptedAtShutdown', :code => 11600},
-        {:code_name => 'InterruptedDueToReplStateChange', :code => 11602},
-        {:code_name => 'NotPrimaryNoSecondaryOk', :code => 13435},
-        {:code_name => 'NotMasterOrSecondary', :code => 13436},
-      ].freeze
-
-      # These are magic error messages that could indicate a master change.
-      #
-      # @since 2.4.2
-      # @api private
-      WRITE_RETRY_MESSAGES = [
-        'not master',
-        'node is recovering',
-      ].freeze
-
-      # These are magic error messages that could indicate a cluster
-      # reconfiguration behind a mongos.
-      #
-      # @since 2.1.1
-      # @api private
-      RETRY_MESSAGES = WRITE_RETRY_MESSAGES + [
-        'transport error',
-        'socket exception',
-        "can't connect",
-        'connect failed',
-        'error querying',
-        'could not get last error',
-        'connection attempt failed',
-        'interrupted at shutdown',
-        'unknown replica set',
-        'dbclient error communicating with server'
-      ].freeze
+      include ReadWriteRetryable
 
       def_delegators :@result, :operation_time
 
@@ -98,41 +53,6 @@ module Mongo
       # @api experimental
       attr_reader :server_message
 
-      # Whether the error is a retryable error according to the legacy
-      # read retry logic.
-      #
-      # @return [ true, false ]
-      #
-      # @since 2.1.1
-      # @deprecated
-      def retryable?
-        write_retryable? ||
-        code.nil? && RETRY_MESSAGES.any?{ |m| message.include?(m) }
-      end
-
-      # Whether the error is a retryable error according to the modern retryable
-      # reads and retryable writes specifications.
-      #
-      # This method is also used by the legacy retryable write logic to determine
-      # whether an error is a retryable one.
-      #
-      # @return [ true, false ]
-      #
-      # @since 2.4.2
-      def write_retryable?
-        write_retryable_code? ||
-        code.nil? && WRITE_RETRY_MESSAGES.any? { |m| message.include?(m) }
-      end
-
-      private def write_retryable_code?
-        if code
-          WRITE_RETRY_ERRORS.any? { |e| e[:code] == code }
-        else
-          # return false rather than nil
-          false
-        end
-      end
-
       # Error codes and code names that should result in a failing getMore
       # command on a change stream NOT being resumed.
       #
@@ -162,7 +82,7 @@ module Mongo
       #
       # @since 2.6.0
       # @api private
-      CHANGE_STREAM_RESUME_MESSAGES = WRITE_RETRY_MESSAGES
+      CHANGE_STREAM_RESUME_MESSAGES = ReadWriteRetryable::WRITE_RETRY_MESSAGES
 
       # Can the change stream on which this error occurred be resumed,
       # provided the operation that triggered this error was a getMore?
@@ -224,6 +144,12 @@ module Mongo
       # @since 2.10.0
       attr_reader :write_concern_error_code_name
 
+      # @return [ String | nil ] The details of the error.
+      #   For WriteConcernErrors this is `document['writeConcernError']['errInfo']`.
+      #   For WriteErrors this is `document['writeErrors'][0]['errInfo']`.
+      #   For all other errors this is nil.
+      attr_reader :details
+
       # @return [ BSON::Document | nil ] The server-returned error document.
       #
       # @api experimental
@@ -258,10 +184,10 @@ module Mongo
       # @option options [ Array<String> ] :labels The set of labels associated
       #   with the error.
       # @option options [ true | false ] :wtimeout Whether the error is a wtimeout.
-      #
-      # @since 2.5.0, options added in 2.6.0
       def initialize(message = nil, result = nil, options = {})
-        super(message)
+        @details = retrieve_details(options[:document])
+        super(append_details(message, @details))
+
         @result = result
         @code = options[:code]
         @code_name = options[:code_name]
@@ -306,6 +232,28 @@ module Mongo
         # either having string keys or providing indifferent access.
         code == 20 && server_message&.start_with?("Transaction numbers") || false
       end
+
+      private
+
+      # Retrieve the details from a document
+      #
+      # @return [ Hash | nil ] the details extracted from the document
+      def retrieve_details(document)
+        return nil unless document
+        if wce = document['writeConcernError']
+          return wce['errInfo']
+        elsif we = document['writeErrors']&.first
+          return we['errInfo']
+        end
+      end
+
+      # Append the details to the message
+      #
+      # @return [ String ] the message with the details appended to it
+      def append_details(message, details)
+        return message unless details && message
+        message + " -- #{details.to_json}"
+      end
     end
   end
 end