mongo 2.17.2 → 2.18.1

data/lib/mongo/client.rb

@@ -92,6 +92,8 @@ module Mongo
       :server_api,
       :server_selection_timeout,
       :socket_timeout,
+      :srv_max_hosts,
+      :srv_service_name,
       :ssl,
       :ssl_ca_cert,
       :ssl_ca_cert_object,
@@ -266,7 +268,7 @@ module Mongo
     # @option options [ Integer ] :max_idle_time The maximum seconds a socket can remain idle
     #   since it has been checked in to the pool.
     # @option options [ Integer ] :max_pool_size The maximum size of the
-    #   connection pool.
+    #   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.
     # @option options [ Integer ] :max_write_retries The maximum number of write
@@ -340,6 +342,13 @@ module Mongo
     #   for selecting a server for an operation.
     # @option options [ Float ] :socket_timeout The timeout, in seconds, to
     #   execute operations on a socket.
+    # @option options [ Integer ] :srv_max_hosts The maximum number of mongoses
+    #   that the driver will communicate with for sharded topologies. If this
+    #   option is 0, then there will be no maximum number of mongoses. If the
+    #   given URI resolves to more hosts than ``:srv_max_hosts``, the client
+    #   will ramdomly choose an ``:srv_max_hosts`` sized subset of hosts.
+    # @option options [ String ] :srv_service_name The service name to use in
+    #   the SRV DNS query.
     # @option options [ true, false ] :ssl Whether to use TLS.
     # @option options [ String ] :ssl_ca_cert The file containing concatenated
     #   certificate authority certificates used to validate certs passed from the
@@ -420,11 +429,16 @@ module Mongo
     #     instance containing the encryption key vault
     #   - :key_vault_namespace => String, the namespace of the key vault in the
     #     format database.collection
-    #   - :kms_providers => Hash, A hash of key management service configuration
-    #     information. Valid hash keys are :local or :aws. There may be more
-    #     than one kms provider specified.
+    #   - :kms_providers => Hash, A hash of key management service (KMS) configuration
+    #     information. Valid hash keys are :aws, :azure, :gcp, :kmip, :local.
+    #     There may be more than one kms provider specified.
+    #   - :kms_tls_options => Hash, A hash of TLS options to authenticate to
+    #     KMS providers, usually used for KMIP servers. Valid hash keys
+    #     are :aws, :azure, :gcp, :kmip, :local. There may be more than one
+    #     kms provider specified.
     #   - :schema_map => Hash | nil, JSONSchema for one or more collections
-    #     specifying which fields should be encrypted.
+    #     specifying which fields should be encrypted. This option is
+    #     mutually exclusive with :schema_map_path.
     #     - Note: Schemas supplied in the schema_map only apply to configuring
     #       automatic encryption for client side encryption. Other validation
     #       rules in the JSON schema will not be enforced by the driver and will
@@ -433,10 +447,21 @@ module Mongo
     #       JSON Schemas obtained from the server. It protects against a
     #       malicious server advertising a false JSON Schema, which could trick
     #       the client into sending unencrypted data that should be encrypted.
+    #     - Note: If a collection is present on both the :encrypted_fields_map
+    #       and :schema_map, an error will be raised.
+    #   - :schema_map_path => String | nil A path to a file contains the JSON schema
+    #   of the collection that stores auto encrypted documents. This option is
+    #   mutually exclusive with :schema_map.
     #   - :bypass_auto_encryption => Boolean, when true, disables auto encryption;
     #     defaults to false.
     #   - :extra_options => Hash | nil, options related to spawning mongocryptd
     #     (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: 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
+    #     analysis of outgoing commands.
     #
     #   Notes on automatic encryption:
     #   - Automatic encryption is an enterprise only feature that only applies
@@ -532,7 +557,7 @@ module Mongo
       end
 =end
       @options.freeze
-      validate_options!(addresses)
+      validate_options!(addresses, is_srv: uri.is_a?(URI::SRVProtocol))
       validate_authentication_options!
 
       database_options = @options.dup
@@ -742,7 +767,7 @@ module Mongo
         # We can't use the same cluster if some options that would affect it
         # have changed.
         if cluster_modifying?(opts)
-          Cluster.create(client)
+          Cluster.create(client, monitoring: opts[:monitoring])
         end
       end
     end
@@ -885,9 +910,11 @@ module Mongo
     #   which databases are returned based on user privileges when access control
     #   is enabled
     #
-    #   See https://docs.mongodb.com/manual/reference/command/listDatabases/
+    #   See https://mongodb.com/docs/manual/reference/command/listDatabases/
     #   for more information and usage.
     # @option opts [ Session ] :session The session to use.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     #
     # @return [ Array<String> ] The names of the databases.
     #
@@ -909,9 +936,11 @@ module Mongo
     #   which databases are returned based on user privileges when access control
     #   is enabled
     #
-    #   See https://docs.mongodb.com/manual/reference/command/listDatabases/
+    #   See https://mongodb.com/docs/manual/reference/command/listDatabases/
     #   for more information and usage.
     # @option opts [ Session ] :session The session to use.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     #
     # @return [ Array<Hash> ] The info for each database.
     #
@@ -933,6 +962,8 @@ module Mongo
     # @param [ Hash ] opts The command options.
     #
     # @option opts [ Session ] :session The session to use.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     #
     # @return [ Array<Mongo::Database> ] The list of database objects.
     #
@@ -984,11 +1015,35 @@ module Mongo
     #
     # @param [ Array<Hash> ] pipeline Optional additional filter operators.
     # @param [ Hash ] options The change stream options.
+    # @option options [ String ] :full_document Allowed values: nil, 'default',
+    #   'updateLookup', 'whenAvailable', 'required'.
+    #
+    #   The default is to not send a value (i.e. nil), which is equivalent to
+    #   'default'. By default, the change notification for partial updates will
+    #   include a delta describing the changes to the document.
+    #
+    #   When set to 'updateLookup', the change notification for partial updates
+    #   will include both a delta describing the changes to the document as well
+    #   as a copy of the entire document that was changed from some time after
+    #   the change occurred.
+    #
+    #   When set to 'whenAvailable', configures the change stream to return the
+    #   post-image of the modified document for replace and update change events
+    #   if the post-image for this event is available.
+    #
+    #   When set to 'required', the same behavior as 'whenAvailable' except that
+    #   an error is raised if the post-image is not available.
+    # @option options [ String ] :full_document_before_change Allowed values: nil,
+    #   'whenAvailable', 'required', 'off'.
     #
-    # @option options [ String ] :full_document Allowed values: 'default', 'updateLookup'.
-    #   Defaults to 'default'. When set to 'updateLookup', the change notification for partial
-    #   updates will include both a delta describing the changes to the document, as well as a copy
-    #   of the entire document that was changed from some time after the change occurred.
+    #   The default is to not send a value (i.e. nil), which is equivalent to 'off'.
+    #
+    #   When set to 'whenAvailable', configures the change stream to return the
+    #   pre-image of the modified document for replace, update, and delete change
+    #   events if it is available.
+    #
+    #   When set to 'required', the same behavior as 'whenAvailable' except that
+    #   an error is raised if the pre-image is not available.
     # @option options [ BSON::Document, Hash ] :resume_after Specifies the logical starting point
     #   for the new change stream.
     # @option options [ Integer ] :max_await_time_ms The maximum amount of time for the server to
@@ -1000,6 +1055,13 @@ module Mongo
     #   changes that occurred at or after the specified timestamp. Any command run
     #   against the server will return a cluster time that can be used here.
     #   Only recognized by server versions 4.0+.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
+    # @option options [ Boolean ] :show_expanded_events Enables the server to
+    #   send the 'expanded' list of change stream events. The list of additional
+    #   events included with this flag set are: createIndexes, dropIndexes,
+    #   modify, create, shardCollection, reshardCollection,
+    #   refineCollectionShardKey.
     #
     # @note A change stream only allows 'majority' read concern.
     # @note This helper method is preferable to running a raw aggregation with a $changeStream
@@ -1011,8 +1073,11 @@ module Mongo
     def watch(pipeline = [], options = {})
       return use(Database::ADMIN).watch(pipeline, options) unless database.name == Database::ADMIN
 
+      view_options = options.dup
+      view_options[:await_data] = true if options[:max_await_time_ms]
+
       Mongo::Collection::View::ChangeStream.new(
-        Mongo::Collection::View.new(self["#{Database::COMMAND}.aggregate"]),
+        Mongo::Collection::View.new(self["#{Database::COMMAND}.aggregate"], {}, view_options),
         pipeline,
         Mongo::Collection::View::ChangeStream::CLUSTER,
         options)
@@ -1088,6 +1153,14 @@ module Mongo
       end
     end
 
+    # Returns encrypted field map hash if provided when creating the client.
+    #
+    # @return [ Hash | nil ] Encrypted field map hash, or nil if not set.
+    # @api private
+    def encrypted_fields_map
+      @encrypted_fields_map ||= @options.fetch(:auto_encryption_options, {})[:encrypted_fields_map]
+    end
+
     private
 
     # Create a new encrypter object using the client's auto encryption options
@@ -1147,11 +1220,26 @@ module Mongo
 
       cluster.validate_session_support!
 
-      Session.new(cluster.session_pool.checkout, self, { implicit: true }.merge(options))
+      options = {implicit: true}.update(options)
+
+      server_session = if options[:implicit]
+        nil
+      else
+        cluster.session_pool.checkout
+      end
+
+      Session.new(server_session, self, options)
     end
 
+    # Auxiliary method that is called by interpreter when copying the client
+    # via dup or clone.
+    #
+    # @param [ Mongo::Client ] original Client that is being cloned.
+    #
+    # @api private
     def initialize_copy(original)
       @options = original.options.dup
+      @connect_lock = Mutex.new
       @monitoring = @cluster ? monitoring : Monitoring.new(options)
       @database = nil
       @read_preference = nil
@@ -1226,6 +1314,12 @@ module Mongo
             end
 
             _options[key] = compressors unless compressors.empty?
+          elsif key == :srv_max_hosts
+            if v && (!v.is_a?(Integer) || v < 0)
+              log_warn("#{v} is not a valid integer for srv_max_hosts")
+            else
+              _options[key] = v
+            end
           else
             _options[key] = v
           end
@@ -1239,7 +1333,7 @@ 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.
-    def validate_options!(addresses = nil)
+    def validate_options!(addresses = nil, is_srv: nil)
       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
@@ -1349,6 +1443,26 @@ module Mongo
           end
         end
       end
+
+      if options[:srv_max_hosts] && options[:srv_max_hosts] > 0
+        if options[:replica_set]
+          raise ArgumentError, ":srv_max_hosts > 0 cannot be used with :replica_set option"
+        end
+
+        if options[:load_balanced]
+          raise ArgumentError, ":srv_max_hosts > 0 cannot be used with :load_balanced=true"
+        end
+      end
+
+      unless is_srv.nil? || is_srv
+        if options[:srv_max_hosts]
+          raise ArgumentError, ":srv_max_hosts cannot be used on non-SRV URI"
+        end
+
+        if options[:srv_service_name]
+          raise ArgumentError, ":srv_service_name cannot be used on non-SRV URI"
+        end
+      end
     end
 
     # Validates all authentication-related options after they are set on the client
@@ -1442,7 +1556,9 @@ module Mongo
     def validate_max_min_pool_size!(option, opts)
       if option == :min_pool_size && opts[:min_pool_size]
         max = opts[:max_pool_size] || Server::ConnectionPool::DEFAULT_MAX_SIZE
-        raise Error::InvalidMinPoolSize.new(opts[:min_pool_size], max) unless opts[:min_pool_size] <= max
+        if max != 0 && opts[:min_pool_size] > max
+          raise Error::InvalidMinPoolSize.new(opts[:min_pool_size], max)
+        end
       end
       true
     end

data/lib/mongo/client_encryption.rb

@@ -31,13 +31,24 @@ module Mongo
     # @option options [ String ] :key_vault_namespace The name of the
     #   key vault collection in the format "database.collection".
     # @option options [ Hash ] :kms_providers A hash of key management service
-    #   configuration information. Valid hash keys are :local or :aws. There
-    #   may be more than one KMS provider specified.
-    def initialize(key_vault_client, options={})
+    #   configuration information.
+    #   @see Mongo::Crypt::KMS::Credentials for list of options for every
+    #   supported provider.
+    #   @note There may be more than one KMS provider specified.
+    # @option options [ Hash ] :kms_tls_options TLS options to connect to KMS
+    #   providers. Keys of the hash should be KSM provider names; values
+    #   should be hashes of TLS connection options. The options are equivalent
+    #   to TLS connection options of Mongo::Client.
+    #   @see Mongo::Client#initialize for list of TLS options.
+    #
+    # @raise [ ArgumentError ] If required options are missing or incorrectly
+    #   formatted.
+    def initialize(key_vault_client, options = {})
       @encrypter = Crypt::ExplicitEncrypter.new(
         key_vault_client,
         options[:key_vault_namespace],
-        options[:kms_providers]
+        Crypt::KMS::Credentials.new(options[:kms_providers]),
+        Crypt::KMS::Validations.validate_tls_options(options[:kms_tls_options])
       )
     end
 
@@ -60,14 +71,19 @@ module Mongo
     #     will not be properly parsed.
     # @option options [ Array<String> ] :key_alt_names An optional array of
     #   strings specifying alternate names for the new data key.
+    # @option options [ String | nil ] :key_material Optional
+    #   96 bytes to use as custom key material for the data key being created.
+    #   If :key_material option is given, the custom key material is used
+    #   for encrypting and decrypting data.
     #
     # @return [ BSON::Binary ] The 16-byte UUID of the new data key as a
     #   BSON::Binary object with type :uuid.
     def create_data_key(kms_provider, options={})
-      @encrypter.create_and_insert_data_key(
-        kms_provider,
-        options
-      )
+      key_document = Crypt::KMS::MasterKeyDocument.new(kms_provider, options)
+
+      key_alt_names = options[:key_alt_names]
+      key_material = options[:key_material]
+      @encrypter.create_and_insert_data_key(key_document, key_alt_names, key_material)
     end
 
     # Encrypts a value using the specified encryption key and algorithm.
@@ -81,14 +97,25 @@ module Mongo
     # @option options [ String ] :key_alt_name The alternate name for the
     #   encryption key.
     # @option options [ String ] :algorithm The algorithm used to encrypt the value.
-    #   Valid algorithms are "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
-    #   or "AEAD_AES_256_CBC_HMAC_SHA_512-Random".
+    #   Valid algorithms are "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
+    #   "AEAD_AES_256_CBC_HMAC_SHA_512-Random", "Indexed", "Unindexed".
+    # @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".
+    # @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".
     #
     # @note The :key_id and :key_alt_name options are mutually exclusive. Only
     #   one is required to perform explicit encryption.
     #
     # @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".
     def encrypt(value, options={})
       @encrypter.encrypt(value, options)
     end
@@ -102,5 +129,81 @@ module Mongo
     def decrypt(value)
       @encrypter.decrypt(value)
     end
+
+    # Adds a key_alt_name for the key in the key vault collection with the given id.
+    #
+    # @param [ BSON::Binary ] id Id of the key to add new key alt name.
+    # @param [ String ] key_alt_name New key alt name to add.
+    #
+    # @return [ BSON::Document | nil ] Document describing the identified key
+    #   before adding the key alt name, or nil if no such key.
+    def add_key_alt_name(id, key_alt_name)
+      @encrypter.add_key_alt_name(id, key_alt_name)
+    end
+
+    # Removes the key with the given id from the key vault collection.
+    #
+    # @param [ BSON::Binary ] id Id of the key to delete.
+    #
+    # @return [ Operation::Result ] The response from the database for the delete_one
+    #   operation that deletes the key.
+    def delete_key(id)
+      @encrypter.delete_key(id)
+    end
+
+    # Finds a single key with the given id.
+    #
+    # @param [ BSON::Binary ] id Id of the key to get.
+    #
+    # @return [ BSON::Document | nil ] The found key document or nil
+    #   if not found.
+    def get_key(id)
+      @encrypter.get_key(id)
+    end
+
+    # Returns a key in the key vault collection with the given key_alt_name.
+    #
+    # @param [ String ] key_alt_name Key alt name to find a key.
+    #
+    # @return [ BSON::Document | nil ] The found key document or nil
+    #   if not found.
+    def get_key_by_alt_name(key_alt_name)
+      @encrypter.get_key_by_alt_name(key_alt_name)
+    end
+
+    # Returns all keys in the key vault collection.
+    #
+    # @return [ Collection::View ] Keys in the key vault collection.
+    def get_keys
+      @encrypter.get_keys
+    end
+    alias :keys :get_keys
+
+    # Removes a key_alt_name from a key in the key vault collection with the given id.
+    #
+    # @param [ BSON::Binary ] id Id of the key to remove key alt name.
+    # @param [ String ] key_alt_name Key alt name to remove.
+    #
+    # @return [ BSON::Document | nil ] Document describing the identified key
+    #   before removing the key alt name, or nil if no such key.
+    def remove_key_alt_name(id, key_alt_name)
+      @encrypter.remove_key_alt_name(id, key_alt_name)
+    end
+
+    # Decrypts multiple data keys and (re-)encrypts them with a new master_key,
+    #   or with their current master_key if a new one is not given.
+    #
+    # @param [ Hash ] filter Filter used to find keys to be updated.
+    # @param [ Hash ] options
+    #
+    # @option options [ String ] :provider KMS provider to encrypt keys.
+    # @option options [ Hash | nil ] :master_key Document describing master key
+    #   to encrypt keys.
+    #
+    # @return [ Crypt::RewrapManyDataKeyResult ] Result of the operation.
+    def rewrap_many_data_key(filter, opts = {})
+      @encrypter.rewrap_many_data_key(filter, opts)
+    end
+
   end
 end

data/lib/mongo/cluster/reapers/cursor_reaper.rb

@@ -192,9 +192,19 @@ module Mongo
 
           options = {
             server_api: server.options[:server_api],
-            service_id: kill_spec.service_id,
+            connection_global_id: kill_spec.connection_global_id,
           }
           op.execute(server, context: Operation::Context.new(options: options))
+
+          if session = kill_spec.session
+            if session.ended?
+              if Lint.enabled?
+                raise Error::LintError, "Ended session for a garbage collected cursor"
+              end
+            elsif session.implicit?
+              session.end_session
+            end
+          end
         end
       end
       alias :execute :kill_cursors

data/lib/mongo/cluster.rb

@@ -280,20 +280,22 @@ module Mongo
     # Create a cluster for the provided client, for use when we don't want the
     # client's original cluster instance to be the same.
     #
-    # @api private
-    #
     # @example Create a cluster for the client.
     #   Cluster.create(client)
     #
     # @param [ Client ] client The client to create on.
+    # @param [ Monitoring | nil ] monitoring. The monitoring instance to use
+    #   with the new cluster. If nil, a new instance of Monitoring will be
+    #   created.
     #
     # @return [ Cluster ] The cluster.
     #
     # @since 2.0.0
-    def self.create(client)
+    # @api private
+    def self.create(client, monitoring: nil)
       cluster = Cluster.new(
         client.cluster.addresses.map(&:to_s),
-        Monitoring.new,
+        monitoring || Monitoring.new,
         client.cluster_options,
       )
       client.instance_variable_set(:@cluster, cluster)
@@ -937,11 +939,21 @@ module Mongo
     # is connected to does not support sessions.
     #
     # Session support may change over time, for example due to servers in the
-    # deployment being upgraded or downgraded. If the client is currently not
-    # connected to any data bearing servers, this method considers the state
-    # of session support as of when the client was last connected to at
-    # least one server. If the client has never connected to any servers,
-    # the deployment is considered to not support sessions.
+    # deployment being upgraded or downgraded.  If the client isn't connected to
+    # any servers and doesn't find any servers
+    # for the duration of server selection timeout, this method will raise
+    # NoServerAvailable. This method is called from the operation execution flow,
+    # and if it raises NoServerAvailable the entire operation will fail
+    # with that exception, since the operation execution has waited for
+    # the server selection timeout for any server to become available
+    # (which would be a superset of the servers suitable for the operation being
+    # attempted) and none materialized.
+    #
+    # @raise [ Error::SessionsNotAvailable ] If the deployment that the driver
+    #   is connected to does not support sessions.
+    # @raise [ Error::NoServerAvailable ] If the client isn't connected to
+    #   any servers and doesn't find any servers for the duration of
+    #   server selection timeout.
     #
     # @api private
     def validate_session_support!
@@ -962,25 +974,11 @@ module Mongo
       # No data bearing servers known - perform server selection to try to
       # get a response from at least one of them, to return an accurate
       # assessment of whether sessions are currently supported.
-      begin
-        ServerSelector.get(mode: :primary_preferred).select_server(self)
-        @state_change_lock.synchronize do
-          @sdam_flow_lock.synchronize do
-            unless topology.logical_session_timeout
-              raise_sessions_not_supported
-            end
-          end
-        end
-      rescue Error::NoServerAvailable
-        # We haven't been able to contact any servers - use last known
-        # value for session support.
-        @state_change_lock.synchronize do
-          @sdam_flow_lock.synchronize do
-            @update_lock.synchronize do
-              unless @sessions_supported
-                raise_sessions_not_supported
-              end
-            end
+      ServerSelector.get(mode: :primary_preferred).select_server(self)
+      @state_change_lock.synchronize do
+        @sdam_flow_lock.synchronize do
+          unless topology.logical_session_timeout
+            raise_sessions_not_supported
           end
         end
       end

data/lib/mongo/collection/helpers.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2014-2022 MongoDB Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  class Collection
+    # This module contains helper methods collection class.
+    #
+    # @api private
+    module Helpers
+      # Executes drop operation and and ignores NamespaceNotFound error.
+      #
+      # @param [ Operation::Drop ] operation Drop operation to be executed.
+      # @param [ Session ] session Session to be use for execution.
+      # @param [ Operation::Context ] context Context to use for execution.
+      #
+      # @return [ Result ] The result of the execution.
+      def do_drop(operation, session, context)
+        operation.execute(next_primary(nil, session), context: context)
+      rescue Error::OperationFailure => ex
+        # NamespaceNotFound
+        if ex.code == 26 || ex.code.nil? && ex.message =~ /ns not found/
+          false
+        else
+          raise
+        end
+      end
+    end
+  end
+end