mongo 2.25.0 → 2.26.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 846c673e8e85d3e7007bec794833276ed4da9591347e361465b190c10829c504
-  data.tar.gz: ad93e6b640fbdb3c6f757df0c0ae433f4c79d50c209fb0bd3c0b8c84402148a9
+  metadata.gz: 39d9792c95b149dbbcb1b065df222c345eea9c84912e03de9a8994d7aea32ab8
+  data.tar.gz: b491401e88ffde8324e802267b35f75f6f92997f5746b3634612e1a9d63f11e8
 SHA512:
-  metadata.gz: 29750ebefccf852b621847e68bffd039f3e28c63829334880416d7e8348fbd8cc5769d7f5b1cf872030d874610739ef4df90f493d9b325d8bebcfe2dd7d7b638
-  data.tar.gz: fbb6248041e00a490ccf23e62c364ce3c8ea8214f3fd4c6f07ff8df18e090702c53039e30a1b2b66f8a5e464ebf4e9162d993a0c67cd0818911449a91d168b3f
+  metadata.gz: aad7e612834dd20849a707f6fde3d5a8101765af93df37eee119ad0418dd518b738ec8834689f0aeac267ac117aab2f89f84362f0c588f8714b96c1c87c286ef
+  data.tar.gz: 6a1c05b23598ac63e37267393de256bd0f2d250f14e881e2fda7a436a2ee2775d60e61d076c4fbaaa77230e7135f89095c55a737edca13a3434f048fdf8aa5db

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

data/lib/mongo/client.rb

@@ -241,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
@@ -509,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
@@ -519,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
@@ -601,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,
@@ -621,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
@@ -830,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]
 
@@ -1260,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

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

data/lib/mongo/cluster.rb

@@ -586,8 +586,7 @@ module Mongo
     # @option options [ true | false ] :keep_connection_pool Usually when the
     #   new server description is unknown, the connection pool on the
     #   respective server is cleared. Set this option to true to keep the
-    #   existing connection pool (required when handling not master errors
-    #   on 4.2+ servers).
+    #   existing connection pool (required when handling not master errors).
     # @option options [ true | false ] :awaited Whether the updated description
     #   was a result of processing an awaited hello.
     # @option options [ Object ] :service_id Change state for the specified

data/lib/mongo/collection/queryable_encryption.rb

@@ -62,8 +62,8 @@ module Mongo
       def maybe_drop_emm_collections(encrypted_fields, client, session)
         encrypted_fields = if encrypted_fields
                              encrypted_fields
-                           elsif encrypted_fields_map
-                             encrypted_fields_for_drop_from_map
+                           elsif client.options[:auto_encryption_options]
+                             encrypted_fields_for_drop
                            else
                              {}
                            end
@@ -127,12 +127,13 @@ module Mongo
           {}
       end
 
-      # Tries to return the encrypted fields from the {{encrypted_fields_map}}
-      # value, for the current namespace.
+      # Tries to return the encrypted fields for the current namespace from
+      # the {{encrypted_fields_map}} value, falling back to the encrypted
+      # fields advertised by the server for the collection.
       #
       # @return [ Hash | nil ] the encrypted fields, if found
-      def encrypted_fields_for_drop_from_map
-        encrypted_fields_map[namespace] ||
+      def encrypted_fields_for_drop
+        (encrypted_fields_map && encrypted_fields_map[namespace]) ||
           database.list_collections(filter: { name: name })
                   .first
                   &.fetch(:options, {})

data/lib/mongo/collection/view/aggregation.rb

@@ -115,15 +115,15 @@ module Mongo
 
         def send_initial_query(server, context, operation: nil)
           if server.load_balancer?
-            # Connection will be checked in when cursor is drained.
-            connection = server.pool.check_out(context: context)
-            initial_query_op(
-              context.session,
-              effective_read_preference(connection)
-            ).execute_with_connection(
-              connection,
-              context: context
-            )
+            server.pool.with_cursor_connection(context: context) do |connection|
+              initial_query_op(
+                context.session,
+                effective_read_preference(connection)
+              ).execute_with_connection(
+                connection,
+                context: context
+              )
+            end
           else
             server.with_connection do |connection|
               initial_query_op(

data/lib/mongo/collection/view/change_stream.rb

@@ -350,8 +350,7 @@ module Mongo
             if server.load_balancer?
               # In load balanced topology, manually check out a connection
               # so it remains checked out and pinned to the cursor.
-              connection = server.pool.check_out(context: context)
-              begin
+              server.pool.with_cursor_connection(context: context) do |connection|
                 result = send_initial_query(connection, context)
 
                 start_at_operation_time = if (doc = result.replies.first && result.replies.first.documents.first)
@@ -360,9 +359,6 @@ module Mongo
                                             nil
                                           end
                 result
-              rescue StandardError
-                server.pool.check_in(connection)
-                raise
               end
             else
               server.with_connection do |connection|

data/lib/mongo/collection/view/iterable.rb

@@ -172,16 +172,9 @@ module Mongo
         def send_initial_query(server, context, operation: nil)
           operation ||= initial_query_op(context.session)
           if server.load_balancer?
-            # Connection will be checked in when cursor is drained,
-            # unless the connection is pinned to a transaction (in which
-            # case it stays checked out for the transaction duration).
-            if context.connection_global_id
-              connection = server.pool.check_out_pinned_connection(
-                context.connection_global_id
-              )
+            server.pool.with_cursor_connection(context: context) do |connection|
+              operation.execute_with_connection(connection, context: context)
             end
-            connection ||= server.pool.check_out(context: context)
-            operation.execute_with_connection(connection, context: context)
           else
             operation.execute(server, context: context)
           end

data/lib/mongo/collection/view/map_reduce.rb

@@ -73,10 +73,11 @@ module Mongo
           context = Operation::Context.new(client: client, session: session,
                                            operation_timeouts: view.operation_timeouts)
           if server.load_balancer?
-            # Connection will be checked in when cursor is drained.
-            connection = server.pool.check_out(context: context)
-            result = send_initial_query_with_connection(connection, context.session, context: context)
-            result = send_fetch_query_with_connection(connection, session) unless inline?
+            result = server.pool.with_cursor_connection(context: context) do |connection|
+              res = send_initial_query_with_connection(connection, context.session, context: context)
+              res = send_fetch_query_with_connection(connection, session) unless inline?
+              res
+            end
           else
             result = send_initial_query(server, context)
             result = send_fetch_query(server, session) unless inline?

data/lib/mongo/collection/view/readable.rb

@@ -739,9 +739,9 @@ module Mongo
               connection_global_id: result.connection_global_id
             )
             result = if server.load_balancer?
-                       # Connection will be checked in when cursor is drained.
-                       connection = server.pool.check_out(context: context)
-                       op.execute_with_connection(connection, context: context)
+                       server.pool.with_cursor_connection(context: context) do |connection|
+                         op.execute_with_connection(connection, context: context)
+                       end
                      else
                        op.execute(server, context: context)
                      end

data/lib/mongo/collection/view/writable.rb

@@ -88,11 +88,6 @@ module Mongo
               operation_timeouts: operation_timeouts(opts)
             )
             write_with_retry(write_concern, context: context) do |connection, txn_num, context|
-              gte_4_4 = connection.server.description.server_version_gte?('4.4')
-              if !gte_4_4 && opts[:hint] && write_concern && !write_concern.acknowledged?
-                raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-              end
-
               Operation::WriteCommand.new(
                 selector: cmd,
                 db_name: database.name,
@@ -216,11 +211,6 @@ module Mongo
             )
             value = tracer.trace_operation(operation, context, op_name: 'findOneAndUpdate') do
               write_with_retry(write_concern, context: context) do |connection, txn_num, context|
-                gte_4_4 = connection.server.description.server_version_gte?('4.4')
-                if !gte_4_4 && opts[:hint] && write_concern && !write_concern.acknowledged?
-                  raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-                end
-
                 operation.txn_num = txn_num
                 operation.execute_with_connection(connection, context: context)
               end
@@ -287,11 +277,6 @@ module Mongo
             )
             tracer.trace_operation(operation, context, op_name: 'deleteMany') do
               nro_write_with_retry(write_concern, context: context) do |connection, _txn_num, context|
-                gte_4_4 = connection.server.description.server_version_gte?('4.4')
-                if !gte_4_4 && opts[:hint] && write_concern && !write_concern.acknowledged?
-                  raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-                end
-
                 operation.execute_with_connection(connection, context: context)
               end
             end
@@ -346,11 +331,6 @@ module Mongo
               operation_timeouts: operation_timeouts(opts)
             )
             write_with_retry(write_concern, context: context) do |connection, txn_num, context|
-              gte_4_4 = connection.server.description.server_version_gte?('4.4')
-              if !gte_4_4 && opts[:hint] && write_concern && !write_concern.acknowledged?
-                raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-              end
-
               Operation::Delete.new(
                 deletes: [ delete_doc ],
                 db_name: collection.database.name,
@@ -428,11 +408,6 @@ module Mongo
               operation_timeouts: operation_timeouts(opts)
             )
             write_with_retry(write_concern, context: context) do |connection, txn_num, context|
-              gte_4_2 = connection.server.description.server_version_gte?('4.2')
-              if !gte_4_2 && opts[:hint] && write_concern && !write_concern.acknowledged?
-                raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-              end
-
               Operation::Update.new(
                 updates: [ update_doc ],
                 db_name: collection.database.name,
@@ -507,11 +482,6 @@ module Mongo
               operation_timeouts: operation_timeouts(opts)
             )
             nro_write_with_retry(write_concern, context: context) do |connection, _txn_num, context|
-              gte_4_2 = connection.server.description.server_version_gte?('4.2')
-              if !gte_4_2 && opts[:hint] && write_concern && !write_concern.acknowledged?
-                raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-              end
-
               Operation::Update.new(
                 updates: [ update_doc ],
                 db_name: collection.database.name,
@@ -601,11 +571,6 @@ module Mongo
             )
             tracer.trace_operation(operation, context) do
               write_with_retry(write_concern, context: context) do |connection, txn_num, context|
-                gte_4_2 = connection.server.description.server_version_gte?('4.2')
-                if !gte_4_2 && opts[:hint] && write_concern && !write_concern.acknowledged?
-                  raise Error::UnsupportedOption.hint_error(unacknowledged_write: true)
-                end
-
                 operation.txn_num = txn_num
                 operation.execute_with_connection(connection, context: context)
               end

data/lib/mongo/crypt/auto_encrypter.rb

@@ -81,6 +81,9 @@ module Mongo
       # @option options [ Boolean | nil ] :crypt_shared_lib_required Whether
       #   crypt shared library is required. If 'true', an error will be raised
       #   if a crypt_shared library cannot be loaded by libmongocrypt.
+      # @option options [ Integer | nil ] :key_expiration_ms The lifetime of the
+      #   data encryption key cache, in milliseconds. A value of 0 means the
+      #   cache never expires. Defaults to 60000.
       #
       # @raise [ ArgumentError ] If required options are missing or incorrectly
       #   formatted.
@@ -99,7 +102,8 @@ module Mongo
           bypass_query_analysis: @options[:bypass_query_analysis],
           crypt_shared_lib_path: @options[:extra_options][:crypt_shared_lib_path],
           crypt_shared_lib_required: @options[:extra_options][:crypt_shared_lib_required],
-          disable_crypt_shared_lib_search: @options[:extra_options][:disable_crypt_shared_lib_search]
+          disable_crypt_shared_lib_search: @options[:extra_options][:disable_crypt_shared_lib_search],
+          key_expiration_ms: @options[:key_expiration_ms]
         )
 
         @mongocryptd_options = @options[:extra_options].slice(

data/lib/mongo/crypt/binding.rb

@@ -81,7 +81,7 @@ module Mongo
       # will cause a `LoadError`.
       #
       # @api private
-      MIN_LIBMONGOCRYPT_VERSION = Gem::Version.new('1.12.0')
+      MIN_LIBMONGOCRYPT_VERSION = Gem::Version.new('1.20.0')
 
       # @!method self.mongocrypt_version(len)
       #   @api private
@@ -1479,6 +1479,31 @@ module Mongo
         mongocrypt_setopt_bypass_query_analysis(handle.ref)
       end
 
+      # @!method self.mongocrypt_setopt_key_expiration(crypt, cache_expiration_ms)
+      #   @api private
+      #
+      #   Set the expiration time for the data encryption key cache.
+      #
+      #   @param [ FFI::Pointer ] crypt A pointer to a mongocrypt_t object.
+      #   @param [ Integer ] cache_expiration_ms The cache expiration time in
+      #     milliseconds. If zero, the cache never expires.
+      #   @return [ Boolean ] Returns whether the option was set successfully.
+      attach_function(:mongocrypt_setopt_key_expiration, %i[pointer uint64], :bool)
+
+      # Set the expiration time for the data encryption key cache on the
+      # Mongo::Crypt::Handle object.
+      #
+      # @param [ Mongo::Crypt::Handle ] handle
+      # @param [ Integer ] cache_expiration_ms The cache expiration time in
+      #   milliseconds. If zero, the cache never expires.
+      #
+      # @raise [ Mongo::Error::CryptError ] If the option is not set successfully.
+      def self.setopt_key_expiration(handle, cache_expiration_ms)
+        check_status(handle) do
+          mongocrypt_setopt_key_expiration(handle.ref, cache_expiration_ms)
+        end
+      end
+
       # @!method self.mongocrypt_setopt_aes_256_ctr(crypt, aes_256_ctr_encrypt, aes_256_ctr_decrypt, ctx)
       #   @api private
       #
@@ -1873,6 +1898,46 @@ module Mongo
         end
       end
 
+      # @!method self.mongocrypt_ctx_setopt_algorithm_text(ctx, opts)
+      #   @api private
+      #
+      # Set options for explicit encryption with the "String" algorithm.
+      #
+      # @note The libmongocrypt C function is named `..._algorithm_text` (the
+      #   original "text" name), even though the algorithm string passed to
+      #   mongocrypt_ctx_setopt_algorithm is "String" (renamed for GA). There is
+      #   no `..._algorithm_string` symbol; `..._algorithm_text` is the correct
+      #   and only setter for these options.
+      #
+      # @param [ FFI::Pointer ] ctx A pointer to a mongocrypt_ctx_t object.
+      # @param [ FFI::Pointer ] opts A pointer to a string options document.
+      #
+      # @return [ Boolean ] Whether setting this option succeeded.
+      attach_function(
+        :mongocrypt_ctx_setopt_algorithm_text,
+        %i[
+          pointer
+          pointer
+        ],
+        :bool
+      )
+
+      # Set options for explicit encryption with the "String" algorithm.
+      #
+      # @param [ Mongo::Crypt::Context ] context
+      # @param [ Hash ] opts options
+      #
+      # @raise [ Mongo::Error::CryptError ] If the operation failed
+      def self.ctx_setopt_algorithm_text(context, opts)
+        validate_document(opts)
+        data = opts.to_bson.to_s
+        Binary.wrap_string(data) do |data_p|
+          check_ctx_status(context) do
+            mongocrypt_ctx_setopt_algorithm_text(context.ctx_p, data_p)
+          end
+        end
+      end
+
       # Raise a Mongo::Error::CryptError based on the status of the underlying
       # mongocrypt_t object.
       #