mongo 2.24.1 → 2.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9359ddba0c1cd025a706f5970893bbdce249c2ab5fbe9d4ce3293a308bb11ade
-  data.tar.gz: f88046bc63c0a6b2d23017a3df2ba2cfe72bf6cd7d9565c985e64084bc41147d
+  metadata.gz: 439e028e8b9ce062d109e1760508977f13a87dd6ee4cb9d5221a6a3108fec214
+  data.tar.gz: bb346a893717256c3eac12af4a63c718bfd4f567b1ec17b95727e45f9f8e11d5
 SHA512:
-  metadata.gz: 1ea813993a5e069434299e68eacfb1c79bcbb0161728d703dd20e3047f2699a11640c94067e22c1089e34b56398afb959843eb3d914f110878056c646402c7e8
-  data.tar.gz: 837e4866998fc01f8523768fbee6f062a3d0564932f318c27d701e826ed123a4c329df0d74449455afa1146e2de42d7fe54941aaf25e9e9061fc83dd82d87d06
+  metadata.gz: 3d650edf8067fbe760d1c0526e62bef7cfda7c27284b725ffcc5a8e3c33c712011b3aa478e87db2abea876d36e332daf733d1180954ed6bd1e5003a258a05f49
+  data.tar.gz: 6832d11c4cae68a7776c8e5f7ef8e5bd9fcbda45bedf8e8cb208fdc5103060582a315cb75434e003462500b4da05deb5e71618a6856159262ff3655fbe16888d

data/bin/mongo_console

@@ -4,8 +4,8 @@
 $LOAD_PATH[0, 0] = File.join(File.dirname(__FILE__), '..', 'lib')
 
 require 'mongo'
-# include the mongo namespace
-include Mongo
+# include the mongo namespace so its constants are available unqualified
+Object.include(Mongo)
 
 begin
   require 'pry'

data/lib/mongo/address/validator.rb

@@ -24,7 +24,7 @@ module Mongo
         case address_str
         when /\A\[[\d:]+\](?::(\d+))?\z/
           # ipv6 with optional port
-          if port_str = ::Regexp.last_match(1)
+          if (port_str = ::Regexp.last_match(1))
             validate_port_str!(port_str)
           end
         when %r{\A/}, /\.sock\z/

data/lib/mongo/address.rb

@@ -302,9 +302,7 @@ module Mongo
       raise Error::TimeoutError, "#{e.class}: #{e} (for #{self})" if csot
 
       raise e
-    rescue IOError, SystemCallError, ::SocketError => e
-      raise Error::SocketError, "#{e.class}: #{e} (for #{self})"
-    rescue OpenSSL::SSL::SSLError => e
+    rescue IOError, SystemCallError, ::SocketError, OpenSSL::SSL::SSLError => e
       raise Error::SocketError, "#{e.class}: #{e} (for #{self})"
     end
   end

data/lib/mongo/auth/aws/conversation.rb

@@ -74,10 +74,6 @@ module Mongo
           client_first_data.to_bson.to_s
         end
 
-        def wrap_data(data)
-          BSON::Binary.new(data.to_bson.to_s)
-        end
-
         def client_nonce
           @client_nonce ||= SecureRandom.random_bytes(32)
         end

data/lib/mongo/auth/aws/credentials_retriever.rb

@@ -140,14 +140,9 @@ module Mongo
         # @raise Error::TimeoutError if credentials cannot be retrieved within
         #   the timeout defined on the operation context.
         def obtain_credentials_from_endpoints(timeout_holder = nil)
-          if (credentials = web_identity_credentials(timeout_holder)) && credentials_valid?(credentials,
-                                                                                            'Web identity token')
-            credentials
-          elsif (credentials = ecs_metadata_credentials(timeout_holder)) && credentials_valid?(credentials,
-                                                                                               'ECS task metadata')
-            credentials
-          elsif (credentials = ec2_metadata_credentials(timeout_holder)) && credentials_valid?(credentials,
-                                                                                               'EC2 instance metadata')
+          if ((credentials = web_identity_credentials(timeout_holder)) && credentials_valid?(credentials, 'Web identity token')) ||
+             ((credentials = ecs_metadata_credentials(timeout_holder)) && credentials_valid?(credentials, 'ECS task metadata')) ||
+             ((credentials = ec2_metadata_credentials(timeout_holder)) && credentials_valid?(credentials, 'EC2 instance metadata'))
             credentials
           end
         end

data/lib/mongo/auth/base.rb

@@ -102,7 +102,7 @@ module Mongo
         context = Operation::Context.new(options: {
                                            server_api: connection.options[:server_api],
                                          })
-        if server_api = context.server_api
+        if (server_api = context.server_api)
           msg = msg.maybe_add_server_api(server_api)
         end
         reply = connection.dispatch([ msg ], context)

data/lib/mongo/auth/sasl_conversation_base.rb

@@ -71,7 +71,7 @@ module Mongo
           mechanism: auth_mechanism_name,
           payload: BSON::Binary.new(payload)
         )
-        if options = client_first_message_options
+        if (options = client_first_message_options)
           # Short SCRAM conversation,
           # https://jira.mongodb.org/browse/DRIVERS-707
           doc[:options] = options

data/lib/mongo/auth/scram_conversation_base.rb

@@ -200,7 +200,7 @@ module Mongo
       # This method can be called from different conversation steps
       # depending on whether the short SCRAM conversation is used.
       def check_server_signature(payload_data)
-        return unless verifier = payload_data['v']
+        return unless (verifier = payload_data['v'])
         raise Error::InvalidSignature.new(verifier, server_signature) unless compare_digest(verifier, server_signature)
 
         @server_verified = true
@@ -281,13 +281,6 @@ module Mongo
       # @since 2.0.0
       attr_reader :iterations
 
-      # Get the data from the returned payload.
-      #
-      # @api private
-      #
-      # @since 2.0.0
-      attr_reader :payload_data
-
       # Get the server nonce from the payload.
       #
       # @api private

data/lib/mongo/auth/stringprep.rb

@@ -97,12 +97,7 @@ module Mongo
       end
 
       def normalize!(out)
-        if String.method_defined?(:unicode_normalize!)
-          out.unicode_normalize!(:nfkc)
-        else
-          require 'mongo/auth/stringprep/unicode_normalize/normalize'
-          out.replace(UnicodeNormalize.normalize(out, :nfkc))
-        end
+        out.unicode_normalize!(:nfkc)
       end
 
       def table_contains?(table, c)

data/lib/mongo/auth/user/view.rb

@@ -152,7 +152,7 @@ module Mongo
         end
 
         def execute_operation(options)
-          client.send(:with_session, options) do |session|
+          client.with_session(options) do |session|
             op = yield session
             op.execute(next_primary(nil, session), context: Operation::Context.new(client: client, session: session))
           end

data/lib/mongo/bulk_write/combineable.rb

@@ -39,7 +39,6 @@ module Mongo
         @requests = requests
         @has_collation = false
         @has_array_filters = false
-        @has_hint = false
       end
 
       # @return [ Boolean ] Whether one or more operation specifies the collation
@@ -54,12 +53,6 @@ module Mongo
         @has_array_filters
       end
 
-      # @return [ Boolean ] Whether one or more operation specifies the
-      #   hint option.
-      def has_hint?
-        @has_hint
-      end
-
       private
 
       def combine_requests(ops)

data/lib/mongo/bulk_write/result_combiner.rb

@@ -92,7 +92,7 @@ module Mongo
 
       def combine_counts!(result)
         Result::FIELDS.each do |field|
-          if result.respond_to?(field) && value = result.send(field)
+          if result.respond_to?(field) && (value = result.public_send(field))
             results.merge!(field => (results[field] || 0) + value)
           end
         end
@@ -115,7 +115,7 @@ module Mongo
       end
 
       def combine_write_errors!(result)
-        if write_errors = result.aggregate_write_errors(count)
+        if (write_errors = result.aggregate_write_errors(count))
           results.merge!(
             'writeErrors' => ((results['writeErrors'] || []) << write_errors).flatten
           )
@@ -125,7 +125,7 @@ module Mongo
       end
 
       def combine_write_concern_errors!(result)
-        return unless write_concern_errors = result.aggregate_write_concern_errors(count)
+        return unless (write_concern_errors = result.aggregate_write_concern_errors(count))
 
         results['writeConcernErrors'] = (results['writeConcernErrors'] || []) +
                                         write_concern_errors

data/lib/mongo/bulk_write/validatable.rb

@@ -43,10 +43,6 @@ module Mongo
         @has_collation = true if document.respond_to?(:keys) && (document[:collation] || document[Operation::COLLATION])
 
         @has_array_filters = true if document.respond_to?(:keys) && document[:array_filters]
-
-        return unless document.respond_to?(:keys) && document[:hint]
-
-        @has_hint = true
       end
 
       private

data/lib/mongo/bulk_write.rb

@@ -236,8 +236,6 @@ module Mongo
     end
 
     def execute_operation(name, values, connection, context, operation_id, result_combiner, session, txn_num = nil)
-      validate_hint!(connection)
-
       unpin_maybe(session, connection) do
         if values.size > connection.description.max_write_batch_size
           split_execute(name, values, connection, context, operation_id, result_combiner, session, txn_num)
@@ -310,38 +308,6 @@ module Mongo
       Operation::Update.new(spec).bulk_execute(connection, context: context)
     end
 
-    def validate_hint!(connection)
-      return unless op_combiner.has_hint?
-      return unless !can_hint?(connection) && write_concern && !write_concern.acknowledged?
-
-      raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-    end
-
-    # Loop through the requests and check if each operation is allowed to send
-    # a hint for each operation on the given server version.
-    #
-    # For the following operations, the client can send a hint for all supported
-    # server versions, and for the rest, the client can only send it for 4.4+:
-    #   - updateOne
-    #   - updateMany
-    #   - replaceOne
-    #
-    # @param [ Connection ] connection The connection object.
-    #
-    # @return [ true | false ] Whether the request is able to send hints for
-    #   the current server version.
-    def can_hint?(connection)
-      gte_4_4 = connection.server.description.server_version_gte?('4.4')
-      op_combiner.requests.all? do |req|
-        op = req.keys.first
-        if req[op].keys.include?(:hint)
-          %i[update_one update_many replace_one].include?(op) || gte_4_4
-        else
-          true
-        end
-      end
-    end
-
     # Perform the request document validation required by driver specifications.
     # This method validates the first key of each update request document to be
     # an operator (i.e. start with $) and the first key of each replacement
@@ -360,7 +326,7 @@ module Mongo
       requests_empty = true
       @requests.each do |req|
         requests_empty = false
-        if op = req.keys.first
+        if (op = req.keys.first)
           if %i[update_one update_many].include?(op)
             if (doc = maybe_first(req.dig(op, :update))) && (key = doc.keys&.first) && !key.to_s.start_with?('$')
               raise Error::InvalidUpdateDocument.new(key: key) if Mongo.validate_update_replace

data/lib/mongo/client.rb

@@ -172,7 +172,6 @@ module Mongo
         @monitoring
       end
     end
-    private :monitoring
 
     # Determine if this client is equivalent to another object.
     #
@@ -242,7 +241,11 @@ module Mongo
     #   printed to the mongod logs upon establishing a connection
     # @option options [ Symbol ] :auth_mech The authentication mechanism to
     #   use. One of :mongodb_cr, :mongodb_x509, :plain, :scram, :scram256
-    # @option options [ Hash ] :auth_mech_properties
+    # @option options [ Hash ] :auth_mech_properties When passed in a
+    #   connection string as authMechanismProperties, key-value pairs are
+    #   delimited by commas, so a value containing a comma (",") must not be
+    #   provided as part of the connection string. Such a value must be passed
+    #   through this option instead. Values may contain colons (":").
     # @option options [ String ] :auth_source The source to authenticate from.
     # @option options [ true | false | nil | Integer ] :bg_error_backtrace
     #   Experimental. Set to true to log complete backtraces for errors in
@@ -265,6 +268,11 @@ module Mongo
     # @option options [ Float ] :connect_timeout The timeout, in seconds, to
     #   attempt a connection.
     # @option options [ String ] :database The database to connect to.
+    # @option options [ true | false ] :enable_overload_retargeting Whether
+    #   the driver deprioritizes a server that returns an overload error,
+    #   reducing the likelihood of retrying on the same overloaded server.
+    #   This option works with MongoDB Atlas Server Version 9.0 and above.
+    #   Default: false.
     # @option options [ Float ] :heartbeat_frequency The interval, in seconds,
     #   for the server monitor to refresh its description via hello.
     # @option options [ Object ] :id_generator A custom object to generate ids
@@ -277,6 +285,9 @@ module Mongo
     # @option options [ String ] :log_prefix A custom log prefix to use when
     #   logging. This option is experimental and subject to change in a future
     #   version of the driver.
+    # @option options [ Integer ] :max_adaptive_retries The maximum number of
+    #   retries to attempt when the driver encounters overload errors. This
+    #   option works with MongoDB Atlas Server Version 9.0 and above. Default: 2.
     # @option options [ Integer ] :max_connecting The maximum number of
     #  connections that can be connecting simultaneously. The default is 2.
     #  This option should be increased if there are many threads that share
@@ -288,9 +299,13 @@ module Mongo
     # @option options [ Integer ] :max_pool_size The maximum size of the
     #   connection pool. Setting this option to zero creates an unlimited connection pool.
     # @option options [ Integer ] :max_read_retries The maximum number of read
-    #   retries when legacy read retries are in use.
+    #   retries when legacy read retries are in use. Deprecated: this option
+    #   only affects the legacy retry implementation, which is deprecated and
+    #   will be removed in a future version.
     # @option options [ Integer ] :max_write_retries The maximum number of write
-    #   retries when legacy write retries are in use.
+    #   retries when legacy write retries are in use. Deprecated: this option
+    #   only affects the legacy retry implementation, which is deprecated and
+    #   will be removed in a future version.
     # @option options [ Integer ] :min_pool_size The minimum size of the
     #   connection pool.
     # @option options [ true, false ] :monitoring If false is given, the
@@ -325,7 +340,9 @@ module Mongo
     #   - *:local_threshold*.
     # @option options [ Hash ] :read_concern The read concern option.
     # @option options [ Float ] :read_retry_interval The interval, in seconds,
-    #   in which reads on a mongos are retried.
+    #   in which reads on a mongos are retried. Deprecated: this option only
+    #   affects the legacy retry implementation, which is deprecated and will
+    #   be removed in a future version.
     # @option options [ Symbol ] :replica_set The name of the replica set to
     #   connect to. Servers not in this replica set will be ignored.
     # @option options [ true | false ] :retry_reads If true, modern retryable
@@ -496,6 +513,10 @@ module Mongo
     #     (this part of the API is subject to change).
     #   - :encrypted_fields_map => Hash | nil, maps a collection namespace to
     #     a hash describing encrypted fields for queryable encryption.
+    #     - Note: Supplying an encrypted_fields_map provides more security
+    #       than relying on an encryptedFields obtained from the server. It
+    #       protects against a malicious server advertising a false
+    #       encryptedFields.
     #     - Note: If a collection is present on both the encryptedFieldsMap
     #       and schemaMap, an error will be raised.
     #   - :bypass_query_analysis => Boolean | nil, when true disables automatic
@@ -506,6 +527,10 @@ module Mongo
     #   - :crypt_shared_lib_required => [ Boolean | nil ]  Whether
     #     crypt shared library is required. If 'true', an error will be raised
     #     if a crypt_shared library cannot be loaded by libmongocrypt.
+    #   - :key_expiration_ms => Integer | nil, the lifetime of the data
+    #     encryption key cache, in milliseconds. Must be a non-negative
+    #     integer. A value of 0 means the cache never expires. Defaults to
+    #     60000.
     #
     #   Notes on automatic encryption:
     #   - Automatic encryption is an enterprise only feature that only applies
@@ -588,9 +613,7 @@ module Mongo
       sdam_proc.call(self) if sdam_proc
 
       @connect_lock = Mutex.new
-      @retry_policy = Retryable::RetryPolicy.new(
-        max_retries: @options[:max_adaptive_retries] || Retryable::Backpressure::DEFAULT_MAX_RETRIES
-      )
+      @retry_policy = build_retry_policy
       @connect_lock.synchronize do
         @cluster = Cluster.new(
           addresses,
@@ -608,7 +631,11 @@ module Mongo
             build_encrypter
           end
         end
-      rescue StandardError
+      # ScriptError is rescued in addition to StandardError because
+      # Mongo::Crypt::Binding raises a LoadError when libmongocrypt cannot be
+      # found. Without it the cluster built above would be left open, leaking
+      # its monitoring and connection pool threads.
+      rescue StandardError, ScriptError
         begin
           @cluster.close
         rescue StandardError => e
@@ -782,10 +809,10 @@ module Mongo
     def with(new_options = nil)
       clone.tap do |client|
         opts = client.update_options(new_options || Options::Redacted.new)
-        Database.create(client)
+        client.reset_database!
         # We can't use the same cluster if some options that would affect it
         # have changed.
-        Cluster.create(client, monitoring: opts[:monitoring]) if cluster_modifying?(opts)
+        client.reset_cluster!(monitoring: opts[:monitoring]) if cluster_modifying?(opts)
       end
     end
 
@@ -817,6 +844,12 @@ module Mongo
         options.update(opts)
         @options = options.freeze
 
+        # The retry policy is built from the options, so a client created by
+        # #with needs its own policy when the option changed.
+        if @options[:max_adaptive_retries] != old_options[:max_adaptive_retries]
+          @retry_policy = build_retry_policy
+        end
+
         auto_encryption_options_changed =
           @options[:auto_encryption_options] != old_options[:auto_encryption_options]
 
@@ -841,6 +874,31 @@ module Mongo
       end
     end
 
+    # Replaces this client's database with a fresh instance built from the
+    # client's current options. Used by #with so a reconfigured client does
+    # not share its database with the client it was cloned from.
+    #
+    # @api private
+    def reset_database!
+      @database = Database.new(self, options[:database], options)
+    end
+
+    # Replaces this client's cluster with a fresh instance built from the
+    # client's current options. Used by #with so a reconfigured client does
+    # not share its cluster with the client it was cloned from.
+    #
+    # @param [ Monitoring | nil ] monitoring The monitoring instance to use
+    #   with the new cluster. If nil, a new instance of Monitoring is created.
+    #
+    # @api private
+    def reset_cluster!(monitoring: nil)
+      @cluster = Cluster.new(
+        cluster.addresses.map(&:to_s),
+        monitoring || Monitoring.new,
+        cluster_options
+      )
+    end
+
     # Get the read concern for this client.
     #
     # @example Get the client read concern.
@@ -1159,7 +1217,7 @@ module Mongo
     #
     # @api private
     def with_session(options = {})
-      # TODO: Add this back in RUBY-3174.
+      # RUBY-3174 will re-enable this guard; see #assert_not_closed.
       # assert_not_closed
 
       session = get_session(options)
@@ -1222,6 +1280,16 @@ module Mongo
 
     private
 
+    # Builds the retry policy for the backpressure retry loops from the
+    # client's options.
+    #
+    # @return [ Retryable::RetryPolicy ] The retry policy.
+    def build_retry_policy
+      Retryable::RetryPolicy.new(
+        max_retries: @options[:max_adaptive_retries] || Retryable::Backpressure::DEFAULT_MAX_RETRIES
+      )
+    end
+
     # Attempts to parse the given list of addresses, using the provided options.
     #
     # @param [ String | Array<String> ] addresses the list of addresses
@@ -1397,7 +1465,7 @@ module Mongo
         log_warn("Read concern has invalid keys: #{invalid_keys.join(',')}.") unless invalid_keys.empty?
       end
 
-      if server_api = opts[:server_api]
+      if (server_api = opts[:server_api])
         raise ArgumentError, ":server_api value must be a hash: #{server_api}" unless server_api.is_a?(Hash)
 
         extra_keys = server_api.keys - %w[version strict deprecation_errors]
@@ -1444,7 +1512,28 @@ module Mongo
     # Validates all options after they are set on the client.
     # This method is intended to catch combinations of options which are
     # not allowed.
+    # Issues a deprecation warning for each legacy retry tuning option that is
+    # explicitly set. These options only affect the legacy retry
+    # implementation, which is deprecated and will be removed in a future
+    # version. Modern retryable reads and writes (enabled by default) ignore
+    # them.
+    def deprecate_legacy_retry_options!
+      %i[max_read_retries read_retry_interval max_write_retries].each do |key|
+        next unless options.key?(key)
+
+        Mongo::Deprecations.warn(
+          "legacy_retry_option_#{key}",
+          "The :#{key} option is deprecated. It only affects the legacy retry " \
+          'implementation, which is deprecated and will be removed in a future ' \
+          'version. Modern retryable reads and writes are enabled by default ' \
+          'and do not use this option.'
+        )
+      end
+    end
+
     def validate_options!(addresses = nil, is_srv: nil)
+      deprecate_legacy_retry_options!
+
       if options[:write] && options[:write_concern] && options[:write] != options[:write_concern]
         raise ArgumentError, "If :write and :write_concern are both given, they must be identical: #{options.inspect}"
       end
@@ -1502,12 +1591,12 @@ module Mongo
       end
 
       %i[connect_timeout socket_timeout].each do |key|
-        next unless value = options[key]
+        next unless (value = options[key])
         raise ArgumentError, "#{key} must be a non-negative number: #{value}" unless value.is_a?(Numeric)
         raise ArgumentError, "#{key} must be a non-negative number: #{value}" if value < 0
       end
 
-      if value = options[:bg_error_backtrace]
+      if (value = options[:bg_error_backtrace])
         case value
         when Integer
           if value <= 0
@@ -1522,7 +1611,7 @@ module Mongo
         end
       end
 
-      if libraries = options[:wrapping_libraries]
+      if (libraries = options[:wrapping_libraries])
         unless libraries.is_a?(Array)
           raise ArgumentError, ":wrapping_libraries must be an array of hashes: #{libraries}"
         end
@@ -1684,7 +1773,7 @@ module Mongo
                                              "the read preference must be specified as a hash: { mode: #{read.inspect} }")
         end
 
-        if mode = read[:mode]
+        if (mode = read[:mode])
           mode = mode.to_sym
           unless Mongo::ServerSelector::PREFERENCES.include?(mode)
             raise Error::InvalidReadOption.new(read, "mode #{mode} is not one of recognized modes")
@@ -1694,6 +1783,17 @@ module Mongo
       true
     end
 
+    # Raises Error::ClientClosed if this client has been closed.
+    #
+    # This is the guard for RUBY-3174 (disallow closed clients from
+    # performing operations). The implementation is complete but not yet
+    # wired in: the intended call site in #with_session is currently
+    # commented out, pending that ticket. Do not delete this method or
+    # Error::ClientClosed as "unused" -- both are here deliberately.
+    #
+    # @raise [ Error::ClientClosed ] if the client has been closed.
+    #
+    # @api private
     def assert_not_closed
       return unless closed?
 

data/lib/mongo/client_encryption.rb

@@ -42,6 +42,10 @@ module Mongo
     # @option options [ Integer ] :timeout_ms The operation timeout in milliseconds.
     #    Must be a non-negative integer. An explicit value of 0 means infinite.
     #    The default value is unset which means the feature is disabled.
+    # @option options [ Integer ] :key_expiration_ms The lifetime of the data
+    #    encryption key cache, in milliseconds. Must be a non-negative integer.
+    #    An explicit value of 0 means the cache never expires. The default is
+    #    60000.
     #
     # @raise [ ArgumentError ] If required options are missing or incorrectly
     #   formatted.
@@ -50,7 +54,9 @@ module Mongo
         key_vault_client,
         options[:key_vault_namespace],
         Crypt::KMS::Credentials.new(options[:kms_providers]),
-        Crypt::KMS::Validations.validate_tls_options(options[:kms_tls_options])
+        Crypt::KMS::Validations.validate_tls_options(options[:kms_tls_options]),
+        options[:timeout_ms],
+        options[:key_expiration_ms]
       )
     end
 
@@ -100,15 +106,34 @@ module Mongo
     #   encryption key.
     # @option options [ String ] :algorithm The algorithm used to encrypt the value.
     #   Valid algorithms are "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
-    #   "AEAD_AES_256_CBC_HMAC_SHA_512-Random", "Indexed", "Unindexed".
+    #   "AEAD_AES_256_CBC_HMAC_SHA_512-Random", "Indexed", "Unindexed", "Range",
+    #   "String".
     # @option options [ Integer | nil ] :contention_factor Contention factor
-    #   to be applied if encryption algorithm is set to "Indexed". If not
-    #   provided, it defaults to a value of 0. Contention factor should be set
-    #   only if encryption algorithm is set to "Indexed".
+    #   to be applied if encryption algorithm is set to "Indexed", "Range", or
+    #   "String". If not provided, it defaults to a value of 0. Contention factor
+    #   should be set only if encryption algorithm is set to "Indexed", "Range",
+    #   or "String".
     # @option options [ String | nil ] query_type Query type to be applied
-    # if encryption algorithm is set to "Indexed". Query type should be set
-    #   only if encryption algorithm is set to "Indexed". The only allowed
-    #   value is "equality".
+    #   if encryption algorithm is set to "Indexed", "Range", or "String".
+    #   Allowed values are "equality" (for "Indexed"), "range" (for "Range"),
+    #   and "prefix", "suffix", "substring" (for "String").
+    # @option options [ Hash | nil ] :range_opts Specifies index options for a
+    #   Queryable Encryption field supporting "range" queries. Required when
+    #   algorithm is "Range". Allowed options are :min, :max, :trim_factor,
+    #   :sparsity, :precision.
+    # @option options [ Hash | nil ] :string_opts Specifies index options for a
+    #   Queryable Encryption field supporting "prefix", "suffix", or "substring"
+    #   queries. Required when algorithm is "String". Allowed options are
+    #   :case_sensitive, :diacritic_sensitive, :prefix, :suffix, :substring.
+    #
+    # @note The result of explicit encryption with the "Indexed", "Range", or
+    #   "String" algorithm must be processed by the server to insert or query.
+    #   To insert or query with such a payload, use a Mongo::Client configured
+    #   with :auto_encryption_options. The :bypass_query_analysis option may be
+    #   true; the :bypass_auto_encryption option must be false.
+    #
+    # @note The "substring" query type is unstable and subject to backwards
+    #   breaking changes.
     #
     # @note The :key_id and :key_alt_name options are mutually exclusive. Only
     #   one is required to perform explicit encryption.
@@ -116,8 +141,8 @@ module Mongo
     # @return [ BSON::Binary ] A BSON Binary object of subtype 6 (ciphertext)
     #   representing the encrypted value.
     #
-    # @raise [ ArgumentError ] if either contention_factor or query_type
-    #   is set, and algorithm is not "Indexed".
+    # @raise [ ArgumentError ] if either contention_factor or query_type is set,
+    #   and algorithm is not "Indexed", "Range", or "String".
     def encrypt(value, options = {})
       @encrypter.encrypt(value, options)
     end
@@ -148,7 +173,7 @@ module Mongo
     #   expression. The only allowed value is "Range"
     # @option options [ Integer | nil ] :contention_factor Contention factor
     #   to be applied If not  provided, it defaults to a value of 0.
-    # @option options [ String | nil ] query_type Query type to be applied.
+    # @option options [ String | nil ] :query_type Query type to be applied.
     #   The only allowed value is "range".
     #
     # @note The :key_id and :key_alt_name options are mutually exclusive. Only