mongo 2.24.0 → 2.25.0

data/lib/mongo/crypt/kms/credentials.rb

@@ -21,28 +21,17 @@ module Mongo
       #
       # @api private
       class Credentials
-        # @return [ Credentials::AWS | nil ] AWS KMS credentials.
-        attr_reader :aws
+        # KMS provider types that support on-demand credential retrieval.
+        ON_DEMAND_PROVIDERS = %w[aws gcp azure].freeze
 
-        # @return [ Credentials::Azure | nil ] Azure KMS credentials.
-        attr_reader :azure
+        attr_reader :credentials_map
 
-        # @return [ Credentials::GCP | nil ] GCP KMS credentials.
-        attr_reader :gcp
-
-        # @return [ Credentials::KMIP | nil ] KMIP KMS credentials.
-        attr_reader :kmip
-
-        # @return [ Credentials::Local | nil ] Local KMS credentials.
-        attr_reader :local
-
-        # Creates a KMS credentials object form a parameters hash.
+        # Creates a KMS credentials object from a parameters hash.
         #
-        # @param [ Hash ] kms_providers A hash that contains credential for
-        #   KMS providers. The hash should have KMS provider names as keys,
-        #   and required parameters for every provider as values.
-        #   Required parameters for KMS providers are described in corresponding
-        #   classes inside Mongo::Crypt::KMS module.
+        # @param [ Hash ] kms_providers A hash that contains credentials for
+        #   KMS providers. Keys may be provider types (:aws, :local, etc.) or
+        #   named provider identifiers ("aws:name1", "local:name2", etc.).
+        #   Values are hashes of credentials for the corresponding provider type.
         #
         # @note There may be more than one KMS provider specified.
         #
@@ -51,29 +40,79 @@ module Mongo
         def initialize(kms_providers)
           raise ArgumentError.new('KMS providers options must not be nil') if kms_providers.nil?
 
-          @aws = AWS::Credentials.new(kms_providers[:aws]) if kms_providers.key?(:aws)
-          @azure = Azure::Credentials.new(kms_providers[:azure]) if kms_providers.key?(:azure)
-          @gcp = GCP::Credentials.new(kms_providers[:gcp]) if kms_providers.key?(:gcp)
-          @kmip = KMIP::Credentials.new(kms_providers[:kmip]) if kms_providers.key?(:kmip)
-          @local = Local::Credentials.new(kms_providers[:local]) if kms_providers.key?(:local)
-          return unless @aws.nil? && @azure.nil? && @gcp.nil? && @kmip.nil? && @local.nil?
+          @credentials_map = {}
+
+          kms_providers.each do |identifier, opts|
+            identifier_str = identifier.to_s
+            provider_type = KMS.provider_base_type(identifier_str)
+
+            creds = case provider_type
+                    when 'aws' then AWS::Credentials.new(opts)
+                    when 'azure' then Azure::Credentials.new(opts)
+                    when 'gcp' then GCP::Credentials.new(opts)
+                    when 'kmip' then KMIP::Credentials.new(opts)
+                    when 'local' then Local::Credentials.new(opts)
+                    else
+                      raise ArgumentError.new(
+                        'KMS providers options must have one of the following keys: ' \
+                        ':aws, :azure, :gcp, :kmip, :local'
+                      )
+                    end
+
+            @credentials_map[identifier_str] = creds
+          end
+
+          return unless @credentials_map.empty?
 
           raise ArgumentError.new(
-            'KMS providers options must have one of the following keys: ' +
+            'KMS providers options must have one of the following keys: ' \
             ':aws, :azure, :gcp, :kmip, :local'
           )
         end
 
+        # @return [ Credentials::AWS | nil ] AWS KMS credentials (unnamed provider only).
+        def aws
+          @credentials_map['aws']
+        end
+
+        # @return [ Credentials::Azure | nil ] Azure KMS credentials (unnamed provider only).
+        def azure
+          @credentials_map['azure']
+        end
+
+        # @return [ Credentials::GCP | nil ] GCP KMS credentials (unnamed provider only).
+        def gcp
+          @credentials_map['gcp']
+        end
+
+        # @return [ Credentials::KMIP | nil ] KMIP KMS credentials (unnamed provider only).
+        def kmip
+          @credentials_map['kmip']
+        end
+
+        # @return [ Credentials::Local | nil ] Local KMS credentials (unnamed provider only).
+        def local
+          @credentials_map['local']
+        end
+
+        # Returns true if any configured provider supports on-demand credential
+        # retrieval and has been configured with empty credentials.
+        #
+        # @return [ Boolean ]
+        def any_on_demand?
+          @credentials_map.any? do |identifier, creds|
+            ON_DEMAND_PROVIDERS.include?(KMS.provider_base_type(identifier)) && creds.empty?
+          end
+        end
+
         # Convert credentials object to a BSON document in libmongocrypt format.
         #
         # @return [ BSON::Document ] Credentials as BSON document.
         def to_document
           BSON::Document.new.tap do |bson|
-            bson[:aws] = @aws.to_document if @aws
-            bson[:azure] = @azure.to_document if @azure
-            bson[:gcp] = @gcp.to_document if @gcp
-            bson[:kmip] = @kmip.to_document if @kmip
-            bson[:local] = @local.to_document if @local
+            @credentials_map.each do |identifier, creds|
+              bson[identifier] = creds.to_document
+            end
           end
         end
       end

data/lib/mongo/crypt/kms/kmip/master_document.rb

@@ -31,8 +31,12 @@ module Mongo
           # @return [ String | nil ] KMIP KMS endpoint with optional port.
           attr_reader :endpoint
 
+          # @return [ true | false | nil ] Whether the KMIP server performs
+          #   encryption and decryption of the data key.
+          attr_reader :delegated
+
           FORMAT_HINT = 'KMIP KMS key document must be in the format: ' +
-                        "{ key_id: 'KEY-ID', endpoint: 'ENDPOINT' }"
+                        "{ key_id: 'KEY-ID', endpoint: 'ENDPOINT', delegated: true|false }"
 
           # Creates a master key document object form a parameters hash.
           #
@@ -42,6 +46,9 @@ module Mongo
           #   a 96 byte KMIP Secret Data managed object, optional. If key_id
           #   is omitted, the driver creates a random 96 byte identifier.
           # @option opts [ String | nil ] :endpoint KMIP endpoint, optional.
+          # @option opts [ true | false | nil ] :delegated If true, the KMIP
+          #   server performs encryption and decryption of the data key,
+          #   optional. Defaults to false.
           #
           # @raise [ ArgumentError ] If required options are missing or incorrectly
           #   formatted.
@@ -52,6 +59,7 @@ module Mongo
             @endpoint = validate_param(
               :endpoint, opts, FORMAT_HINT, required: false
             )
+            @delegated = validate_delegated(opts)
           end
 
           # Convert master key document object to a BSON document in libmongocrypt format.
@@ -63,8 +71,29 @@ module Mongo
                                }).tap do |bson|
               bson.update({ endpoint: endpoint }) unless endpoint.nil?
               bson.update({ keyId: key_id }) unless key_id.nil?
+              bson.update({ delegated: delegated }) unless delegated.nil?
             end
           end
+
+          private
+
+          # Validate the optional :delegated KMIP master key option.
+          #
+          # @param [ Hash ] opts Master key options.
+          #
+          # @return [ true | false | nil ] The delegated value, or nil if absent.
+          #
+          # @raise [ ArgumentError ] If delegated is present but not a boolean.
+          def validate_delegated(opts)
+            return nil unless opts.key?(:delegated)
+
+            value = opts[:delegated]
+            return value if value == true || value == false || value.nil?
+
+            raise ArgumentError.new(
+              "The delegated option must be a boolean; currently have #{value}"
+            )
+          end
         end
       end
     end

data/lib/mongo/crypt/kms/master_key_document.rb

@@ -22,23 +22,28 @@ module Mongo
       #
       # @api private
       class MasterKeyDocument
-        # Known KMS provider names.
+        # Known KMS provider types.
         KMS_PROVIDERS = %w[aws azure gcp kmip local].freeze
 
-        # Creates a master key document object form a parameters hash.
+        # Creates a master key document object from a parameters hash.
         #
-        # @param [ String ] kms_provider. KMS provider name.
+        # @param [ String ] kms_provider KMS provider identifier. May be a
+        #   provider type (e.g. "aws") or a named provider (e.g. "aws:name1").
         # @param [ Hash ] options A hash that contains master key options for
         #   the KMS provider.
         #   Required parameters for KMS providers are described in corresponding
         #   classes inside Mongo::Crypt::KMS module.
         #
-        # @raise [ ArgumentError ] If required options are missing or incorrectly.
+        # @raise [ ArgumentError ] If required options are missing or incorrectly
+        #   formatted.
         def initialize(kms_provider, options)
           raise ArgumentError.new('Key document options must not be nil') if options.nil?
 
+          @provider = kms_provider.to_s
+          provider_type = KMS.provider_base_type(@provider)
+
           master_key = options.fetch(:master_key, {})
-          @key_document = case kms_provider.to_s
+          @key_document = case provider_type
                           when 'aws' then KMS::AWS::MasterKeyDocument.new(master_key)
                           when 'azure' then KMS::Azure::MasterKeyDocument.new(master_key)
                           when 'gcp' then KMS::GCP::MasterKeyDocument.new(master_key)
@@ -53,7 +58,7 @@ module Mongo
         #
         # @return [ BSON::Document ] Master key document as BSON document.
         def to_document
-          @key_document.to_document
+          @key_document.to_document.merge(provider: @provider)
         end
       end
     end

data/lib/mongo/crypt/kms.rb

@@ -16,13 +16,24 @@
 
 module Mongo
   module Crypt
-    module KMS
+    module KMS # rubocop:disable Style/Documentation
       # This error indicates that we could not obtain credential for
       # a KMS service.
       #
       # @api private
       class CredentialsNotFound < RuntimeError; end
 
+      # Returns the base provider type from a KMS provider identifier.
+      # For example, "aws:name1" returns "aws" and :aws returns "aws".
+      #
+      # @param [ String | Symbol ] identifier The KMS provider identifier.
+      # @return [ String ] The base provider type.
+      #
+      # @api private
+      def self.provider_base_type(identifier)
+        identifier.to_s.split(':').first
+      end
+
       # This module contains helper methods for validating KMS parameters.
       #
       # @api private

data/lib/mongo/cursor.rb

@@ -382,7 +382,7 @@ module Mongo
       with_overload_retry(context: possibly_refreshed_context) do
         process(execute_operation(get_more_operation))
       end
-    rescue Error::SocketError, Error::SocketTimeoutError
+    rescue Error::SocketError, Error::SocketTimeoutError, Error::ConnectionPerished
       @get_more_network_error = true
       raise
     rescue Error::OperationFailure => e
@@ -463,6 +463,12 @@ module Mongo
       if view.respond_to?(:options) && view.options.is_a?(Hash) && !view.options[:comment].nil?
         spec[:comment] = view.options[:comment]
       end
+      # A cursor built from a runCursorCommand response carries a getMore-specific
+      # maxTimeMS that is sent on getMore commands. Regular find/aggregate views
+      # do not expose this, so their getMores are unaffected.
+      if view.respond_to?(:max_time_ms_for_get_more) && view.max_time_ms_for_get_more
+        spec[:max_time_ms] = view.max_time_ms_for_get_more
+      end
       Operation::GetMore.new(spec)
     end
 
@@ -501,7 +507,7 @@ module Mongo
     end
 
     def limit
-      @view.send(:limit)
+      @view.limit
     end
 
     def register

data/lib/mongo/database/cursor_command_view.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2025 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 Database
+    # The minimal view a Cursor needs when it is built from an arbitrary
+    # command response rather than from a collection query.
+    #
+    # It carries the getMore-specific options (batchSize, maxTimeMS, comment)
+    # and the cursor type and timeout mode, and answers the few methods the
+    # Cursor reads from its view.
+    #
+    # @api private
+    class CursorCommandView
+      # @param [ Mongo::Database ] database The database the command ran on.
+      # @param [ Hash ] options The getMore and timeout options.
+      #
+      # @option options [ Integer ] :batch_size The batchSize for getMores.
+      # @option options [ Integer ] :max_time_ms The maxTimeMS for getMores.
+      # @option options [ Object ] :comment The comment for getMores.
+      # @option options [ Symbol ] :cursor_type :tailable or :tailable_await.
+      # @option options [ Symbol ] :timeout_mode :cursor_lifetime or :iteration.
+      def initialize(database, options = {})
+        @database = database
+        @options = options
+      end
+
+      # @return [ Mongo::Database ] The database the command ran on.
+      attr_reader :database
+
+      # @return [ Hash ] The view options. Used by the Cursor to read the
+      #   getMore comment.
+      attr_reader :options
+
+      # @return [ Mongo::Client ] The client.
+      def client
+        database.client
+      end
+
+      # A placeholder collection used only so the Cursor can reach the client
+      # and database. The actual namespace for getMore and killCursors is taken
+      # from the command response, not from this collection.
+      #
+      # @return [ Mongo::Collection ] The $cmd pseudo collection.
+      def collection
+        @collection ||= Collection.new(database, '$cmd')
+      end
+
+      # @return [ Integer | nil ] The batchSize sent on getMore commands.
+      def batch_size
+        options[:batch_size]
+      end
+
+      # @return [ Integer | nil ] The maxTimeMS sent on getMore commands.
+      def max_time_ms_for_get_more
+        options[:max_time_ms]
+      end
+
+      # @return [ Symbol | nil ] The cursor type.
+      def cursor_type
+        options[:cursor_type]
+      end
+
+      # @return [ Symbol | nil ] The timeout mode.
+      def timeout_mode
+        options[:timeout_mode]
+      end
+
+      # @return [ Hash ] timeout values for the operation context.
+      def operation_timeouts(opts = {})
+        database.operation_timeouts(opts)
+      end
+
+      # Cursors do not support a limit when built from a command response.
+      #
+      # @api private
+      def limit
+        nil
+      end
+    end
+  end
+end

data/lib/mongo/database.rb

@@ -15,6 +15,7 @@
 # limitations under the License.
 
 require 'mongo/database/view'
+require 'mongo/database/cursor_command_view'
 
 module Mongo
   # Represents a database on the db server and operations that can execute on
@@ -259,6 +260,119 @@ module Mongo
       end
     end
 
+    # Run a command that returns a cursor and parse the response as a cursor.
+    #
+    # The command is sent to the server unmodified; the driver MUST NOT inspect
+    # or alter it. If the response does not contain a cursor field an error is
+    # raised. The command is never retried.
+    #
+    # Note: if a +maxTimeMS+ field is already set on the command document it is
+    # left as-is. The +max_time_ms+ option below applies only to getMore
+    # commands. Setting both +timeout_ms+ and +max_time_ms+ is not supported
+    # and has undefined behavior.
+    #
+    # @example Run a cursor-returning command.
+    #   database.cursor_command(checkMetadataConsistency: 1)
+    #
+    # @param [ Hash ] command The command to execute.
+    # @param [ Hash ] options The command options.
+    #
+    # @option options [ Hash ] :read The read preference for this command,
+    #   used for server selection and reused for subsequent getMores.
+    # @option options [ Session ] :session The session to use. If none is
+    #   given an implicit session is created and reused for the cursor's
+    #   lifetime.
+    # @option options [ Integer ] :timeout_ms The operation timeout in
+    #   milliseconds.
+    # @option options [ Integer ] :batch_size The batchSize to send on getMore
+    #   commands.
+    # @option options [ Integer ] :max_time_ms The maxTimeMS to send on getMore
+    #   commands.
+    # @option options [ Object ] :comment A comment to attach to getMore
+    #   commands.
+    # @option options [ Symbol ] :cursor_type The cursor type, :tailable or
+    #   :tailable_await. Must match the flags set on the command document.
+    # @option options [ Symbol ] :timeout_mode :cursor_lifetime or :iteration.
+    #
+    # @return [ Mongo::Cursor ] A cursor over the command results.
+    #
+    # @raise [ Error::InvalidCursorOperation ] If the response does not contain
+    #   a cursor.
+    def cursor_command(command, options = {})
+      options = options.dup
+      execution_opts = options.delete(:execution_options) || {}
+      view_options = extract_cursor_command_view_options(options)
+
+      txn_read_pref = (options[:session].txn_read_preference if options[:session] && options[:session].in_transaction?)
+      txn_read_pref ||= options[:read] || ServerSelector::PRIMARY
+      Lint.validate_underscore_read_preference(txn_read_pref)
+      selector = ServerSelector.get(txn_read_pref)
+
+      # The session is intentionally not wrapped in #with_session: an implicit
+      # session must outlive this method and is ended by the cursor when it is
+      # exhausted or closed. Until the cursor takes ownership, the session and
+      # any load-balanced connection are cleaned up here on every exit path.
+      session = client.get_session(options)
+      context = Operation::Context.new(
+        client: client,
+        session: session,
+        operation_timeouts: operation_timeouts(options)
+      )
+      op = Operation::CursorCommand.new(
+        selector: command,
+        db_name: name,
+        read: selector,
+        session: session
+      )
+
+      # Per the client-backpressure spec, retrying a generic command on
+      # overload errors requires both retryable reads and writes to be
+      # enabled, same as Database#command.
+      retry_enabled = client.options[:retry_reads] != false &&
+                      client.options[:retry_writes] != false
+
+      server = nil
+      connection = nil
+      cursor = nil
+      begin
+        result = with_overload_retry(context: context, retry_enabled: retry_enabled) do
+          server = selector.select_server(cluster, nil, session)
+          if server.load_balancer?
+            # The connection is checked in by the cursor when it is drained.
+            connection = check_out_cursor_command_connection(server, context)
+            begin
+              op.execute_with_connection(connection, context: context, options: execution_opts)
+            rescue StandardError
+              # Release the connection before the error propagates so that
+              # a retried attempt checks out a fresh one.
+              connection.connection_pool.check_in(connection) unless connection.pinned?
+              connection = nil
+              raise
+            end
+          else
+            op.execute(server, context: context, options: execution_opts)
+          end
+        end
+
+        unless result.cursor?
+          raise Error::InvalidCursorOperation,
+                'The command response did not include a cursor. ' \
+                'Use Database#command for commands that do not return a cursor.'
+        end
+
+        view = CursorCommandView.new(self, view_options)
+        cursor = Cursor.new(view, result, server, session: session, context: context)
+      ensure
+        # If the cursor was created it owns the session and connection;
+        # otherwise (error or no cursor in the response) release them here.
+        unless cursor
+          connection.connection_pool.check_in(connection) if connection && !connection.pinned?
+          session.end_session if session && session.implicit?
+        end
+      end
+      cursor
+    end
+
     # Execute a read command on the database, retrying the read if necessary.
     #
     # @param [ Hash ] operation The command to execute.
@@ -530,24 +644,6 @@ module Mongo
       )
     end
 
-    # Create a database for the provided client, for use when we don't want the
-    # client's original database instance to be the same.
-    #
-    # @api private
-    #
-    # @example Create a database for the client.
-    #   Database.create(client)
-    #
-    # @param [ Client ] client The client to create on.
-    #
-    # @return [ Database ] The database.
-    #
-    # @since 2.0.0
-    def self.create(client)
-      database = Database.new(client, client.options[:database], client.options)
-      client.instance_variable_set(:@database, database)
-    end
-
     # @return [ Integer | nil ] Operation timeout that is for this database or
     #   for the corresponding client.
     #
@@ -570,5 +666,35 @@ module Mongo
         end
       end
     end
+
+    private
+
+    # Removes the getMore and cursor options from the options hash and returns
+    # them as a separate hash for the CursorCommandView. The remaining options
+    # (e.g. :session, :read, :timeout_ms) are left for command execution.
+    #
+    # @param [ Hash ] options The cursor_command options (mutated).
+    #
+    # @return [ Hash ] The view options.
+    def extract_cursor_command_view_options(options)
+      %i[ batch_size max_time_ms comment cursor_type timeout_mode ].each_with_object({}) do |key, view_options|
+        view_options[key] = options.delete(key) if options.key?(key)
+      end
+    end
+
+    # Checks out a load balanced connection for a cursor command. If the
+    # session is pinned to a connection (e.g. in a transaction), that
+    # connection is reused.
+    #
+    # @param [ Server ] server The load balancer server.
+    # @param [ Operation::Context ] context The operation context.
+    #
+    # @return [ Server::Connection ] The checked out connection.
+    def check_out_cursor_command_connection(server, context)
+      connection = if context.connection_global_id
+                     server.pool.check_out_pinned_connection(context.connection_global_id)
+                   end
+      connection || server.pool.check_out(context: context)
+    end
   end
 end

data/lib/mongo/error/bulk_write_error.rb

@@ -34,6 +34,11 @@ module Mongo
       # @return [ BSON::Document ] result The error result.
       attr_reader :result
 
+      # @return [ Array<String> ] Deduplicated list of "host:port" addresses of
+      #   the servers that produced this bulk write error. Empty when no
+      #   addresses were supplied.
+      attr_reader :server_addresses
+
       # Instantiate the new exception.
       #
       # @example Instantiate the exception.
@@ -41,10 +46,14 @@ module Mongo
       #
       # @param [ Hash ] result A processed response from the server
       #   reporting results of the operation.
+      # @param [ Array<String | Mongo::Address | Mongo::Server::Description> ]
+      #   server_addresses Addresses of the servers that produced this error.
+      #   Entries are normalized to "host:port" strings.
       #
       # @since 2.0.0
-      def initialize(result)
+      def initialize(result, server_addresses: nil)
         @result = result
+        @server_addresses = normalize_server_addresses(server_addresses)
 
         # Exception constructor behaves differently for a nil argument and
         # for no argument. Avoid passing nil explicitly.
@@ -93,8 +102,27 @@ module Mongo
 
         fragment = "Multiple errors: #{fragment}" if errors.length > 1
 
+        if Mongo.include_server_address_in_errors && @server_addresses.any?
+          fragment = "#{fragment} (on #{@server_addresses.join(', ')})"
+        end
+
         fragment
       end
+
+      def normalize_server_addresses(value)
+        return [] if value.nil?
+
+        Array(value).filter_map do |entry|
+          case entry
+          when String then entry
+          when Mongo::Address then entry.seed
+          when Mongo::Server::Description then entry.address&.seed
+          else
+            raise ArgumentError,
+                  "server_addresses entries must be String, Mongo::Address, or Mongo::Server::Description; got #{entry.class}"
+          end
+        end.uniq
+      end
     end
   end
 end

data/lib/mongo/error/invalid_server_preference.rb

@@ -33,6 +33,9 @@ module Mongo
       # Error message when hedge is specified for a read preference that does not support it.
       #
       # @api private
+      #
+      # @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #   be removed in a future version.
       NO_HEDGE_SUPPORT = 'The hedge option cannot be set for this read preference'
 
       # Error message for when the max staleness is not at least twice the heartbeat frequency.

data/lib/mongo/error/invalid_uri.rb

@@ -23,12 +23,16 @@ module Mongo
     class InvalidURI < Error
       # Instantiate the new exception.
       #
+      # The URI is redacted via {Mongo::URI.redact} before being interpolated
+      # so that any cleartext credentials in the original input do not end up
+      # in logs, error reporters, or backtraces.
+      #
       # @example Instantiate the exception.
       #   Mongo::Error::InvalidURI.new(uri, details, format)
       #
       # @since 2.0.0
       def initialize(uri, details, format = nil)
-        message = "Bad URI: #{uri}\n" +
+        message = "Bad URI: #{Mongo::URI.redact(uri)}\n" +
                   "#{details}\n"
         message += "MongoDB URI must be in the following format: #{format}\n" if format
         message += "Please see the following URL for more information: #{Mongo::URI::HELP}\n"