mongo 2.24.1 → 2.25.0

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/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"

data/lib/mongo/error/operation_failure.rb

@@ -233,9 +233,9 @@ module Mongo
         def retrieve_details(document)
           return nil unless document
 
-          if wce = document['writeConcernError']
+          if (wce = document['writeConcernError'])
             wce['errInfo']
-          elsif we = document['writeErrors']&.first
+          elsif (we = document['writeErrors']&.first)
             we['errInfo']
           end
         end

data/lib/mongo/error/parser.rb

@@ -180,13 +180,13 @@ module Mongo
       end
 
       def parse_single(message, key, doc = document)
-        return unless error = doc[key]
+        return unless (error = doc[key])
 
         append(message, error)
       end
 
       def parse_multiple(message, key)
-        return unless errors = document[key]
+        return unless (errors = document[key])
 
         errors.each do |error|
           parse_single(message, 'errmsg', error)
@@ -228,7 +228,7 @@ module Mongo
         return unless @code.nil? && @code_name.nil?
         # If we have writeErrors, and all of their codes are the same,
         # use that code. Otherwise don't set the code
-        return unless write_errors = document['writeErrors']
+        return unless (write_errors = document['writeErrors'])
 
         codes = write_errors.map { |e| e['code'] }.compact
         return unless codes.uniq.length == 1

data/lib/mongo/error/sdam_error_detection.rb

@@ -29,10 +29,9 @@ module Mongo
         # Require the error to be communicated at the top level of the response
         # for it to influence SDAM state. See DRIVERS-1376 / RUBY-2516.
         return false if document && document['ok'] == 1
+        return false if node_recovering?
 
-        if node_recovering?
-          false
-        elsif code
+        if code
           NOT_MASTER_CODES.include?(code)
         elsif message
           message.include?('not master')

data/lib/mongo/grid/fs_bucket.rb

@@ -480,7 +480,7 @@ module Mongo
       #
       # @since 2.1.0
       def write_concern
-        @write_concern ||= if wco = @options[:write_concern] || @options[:write]
+        @write_concern ||= if (wco = @options[:write_concern] || @options[:write])
                              WriteConcern.get(wco)
                            else
                              database.write_concern
@@ -494,6 +494,32 @@ module Mongo
         chunks_collection.drop(timeout_ms: context.remaining_timeout_ms)
       end
 
+      # Ensures the files and chunks collections have their required indexes,
+      # creating any that are missing.
+      #
+      # @param [ CsotTimeoutHolder | nil ] timeout_holder The timeout holder.
+      #
+      # @api private
+      def ensure_indexes!(timeout_holder = nil)
+        fc_idx = files_collection.find(
+          {},
+          limit: 1,
+          projection: { _id: 1 },
+          timeout_ms: timeout_holder&.remaining_timeout_ms
+        ).first
+        create_index_if_missing!(files_collection, FSBucket::FILES_INDEX) if fc_idx.nil?
+
+        cc_idx = chunks_collection.find(
+          {},
+          limit: 1,
+          projection: { _id: 1 },
+          timeout_ms: timeout_holder&.remaining_timeout_ms
+        ).first
+        return unless cc_idx.nil?
+
+        create_index_if_missing!(chunks_collection, FSBucket::CHUNKS_INDEX, unique: true)
+      end
+
       private
 
       # @param [ Hash ] opts The options.
@@ -516,26 +542,6 @@ module Mongo
         "#{prefix}.#{Grid::File::Info::COLLECTION}"
       end
 
-      def ensure_indexes!(timeout_holder = nil)
-        fc_idx = files_collection.find(
-          {},
-          limit: 1,
-          projection: { _id: 1 },
-          timeout_ms: timeout_holder&.remaining_timeout_ms
-        ).first
-        create_index_if_missing!(files_collection, FSBucket::FILES_INDEX) if fc_idx.nil?
-
-        cc_idx = chunks_collection.find(
-          {},
-          limit: 1,
-          projection: { _id: 1 },
-          timeout_ms: timeout_holder&.remaining_timeout_ms
-        ).first
-        return unless cc_idx.nil?
-
-        create_index_if_missing!(chunks_collection, FSBucket::CHUNKS_INDEX, unique: true)
-      end
-
       def create_index_if_missing!(collection, index_spec, options = {})
         indexes_view = collection.indexes
         begin

data/lib/mongo/grid/stream/write.rb

@@ -148,7 +148,7 @@ module Mongo
           #
           # @since 2.1.0
           def write_concern
-            @write_concern ||= if wco = @options[:write_concern] || @options[:write]
+            @write_concern ||= if (wco = @options[:write_concern] || @options[:write])
                                  WriteConcern.get(wco)
                                else
                                  fs.write_concern
@@ -212,7 +212,7 @@ module Mongo
           end
 
           def ensure_indexes!
-            fs.send(:ensure_indexes!, @timeout_holder)
+            fs.ensure_indexes!(@timeout_holder)
           end
 
           def ensure_open!

data/lib/mongo/index/view.rb

@@ -168,11 +168,11 @@ module Mongo
         options = options.dup
 
         create_options = {}
-        if session = @options[:session]
+        if (session = @options[:session])
           create_options[:session] = session
         end
         %i[commit_quorum session comment timeout_ms max_time_ms].each do |key|
-          if value = options.delete(key)
+          if (value = options.delete(key))
             create_options[key] = value
           end
         end
@@ -347,10 +347,20 @@ module Mongo
         end
       end
 
+      # The query limit for an index view. Always -1; present so a Cursor
+      # can treat an index view like a collection view.
+      #
+      # @api private
+      def limit
+        -1
+      end
+
       private
 
       def drop_by_name(name, opts = {})
-        client.send(:with_session, @options) do |session|
+        session_options = @options.dup
+        session_options[:session] = opts[:session] if opts[:session]
+        client.with_session(session_options) do |session|
           spec = {
             db_name: database.name,
             coll_name: collection.name,
@@ -394,10 +404,6 @@ module Mongo
         Operation::Indexes.new(indexes_spec(session))
       end
 
-      def limit
-        -1
-      end
-
       def normalize_keys(spec)
         return false if spec.is_a?(String)
 

data/lib/mongo/monitoring/event/cmap/connection_check_out_failed.rb

@@ -62,6 +62,7 @@ module Mongo
           # @since 2.9.0
           # @api private
           def initialize(address, reason)
+            super()
             @reason = reason
             @address = address
           end

data/lib/mongo/monitoring/event/cmap/connection_check_out_started.rb

@@ -35,6 +35,7 @@ module Mongo
           # @since 2.9.0
           # @api private
           def initialize(address)
+            super()
             @address = address
           end
 

data/lib/mongo/monitoring/event/cmap/connection_checked_in.rb

@@ -47,6 +47,7 @@ module Mongo
           # @since 2.9.0
           # @api private
           def initialize(address, id, pool)
+            super()
             @address = address
             @connection_id = id
             @pool = pool

data/lib/mongo/monitoring/event/cmap/connection_checked_out.rb

@@ -48,6 +48,7 @@ module Mongo
           # @since 2.9.0
           # @api private
           def initialize(address, id, pool)
+            super()
             @address = address
             @connection_id = id
             @pool = pool

data/lib/mongo/monitoring/event/cmap/connection_closed.rb

@@ -79,6 +79,7 @@ module Mongo
           # @since 2.9.0
           # @api private
           def initialize(address, id, reason)
+            super()
             @reason = reason
             @address = address
             @connection_id = id

data/lib/mongo/monitoring/event/cmap/connection_created.rb

@@ -41,6 +41,7 @@ module Mongo
           # @since 2.9.0
           # @api private
           def initialize(address, id)
+            super()
             @address = address
             @connection_id = id
           end

data/lib/mongo/monitoring/event/cmap/connection_ready.rb

@@ -41,6 +41,7 @@ module Mongo
           # @since 2.9.0
           # @api private
           def initialize(address, id)
+            super()
             @address = address
             @connection_id = id
           end

data/lib/mongo/monitoring/event/cmap/pool_cleared.rb

@@ -43,6 +43,7 @@ module Mongo
           #
           # @api private
           def initialize(address, service_id: nil, interrupt_in_use_connections: nil)
+            super()
             @address = address
             @service_id = service_id
             @options = {}

data/lib/mongo/monitoring/event/cmap/pool_closed.rb

@@ -42,6 +42,7 @@ module Mongo
           # @since 2.9.0
           # @api private
           def initialize(address, pool)
+            super()
             @address = address
             @pool = pool
           end

data/lib/mongo/monitoring/event/cmap/pool_created.rb

@@ -48,6 +48,7 @@ module Mongo
           # @since 2.9.0
           # @api private
           def initialize(address, options, pool)
+            super()
             @address = address
             @options = options.dup.freeze
             @pool = pool