mongo 2.17.4 → 2.21.0

data/lib/mongo/client.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #
@@ -71,6 +71,7 @@ module Mongo
       :local_threshold,
       :logger,
       :log_prefix,
+      :max_connecting,
       :max_idle_time,
       :max_pool_size,
       :max_read_retries,
@@ -80,6 +81,7 @@ module Mongo
       :monitoring_io,
       :password,
       :platform,
+      :populator_io,
       :read,
       :read_concern,
       :read_retry_interval,
@@ -92,6 +94,8 @@ module Mongo
       :server_api,
       :server_selection_timeout,
       :socket_timeout,
+      :srv_max_hosts,
+      :srv_service_name,
       :ssl,
       :ssl_ca_cert,
       :ssl_ca_cert_object,
@@ -107,6 +111,7 @@ module Mongo
       :ssl_verify_certificate,
       :ssl_verify_hostname,
       :ssl_verify_ocsp_endpoint,
+      :timeout_ms,
       :truncate_logs,
       :user,
       :wait_queue_timeout,
@@ -263,10 +268,16 @@ 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_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
+    #  the same client and the application is experiencing timeouts
+    #  while waiting for connections to be established.
+    #  selecting a server for an operation. The default is 2.
     # @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
@@ -339,7 +350,15 @@ module Mongo
     # @option options [ Integer ] :server_selection_timeout The timeout in seconds
     #   for selecting a server for an operation.
     # @option options [ Float ] :socket_timeout The timeout, in seconds, to
-    #   execute operations on a socket.
+    #   execute operations on a socket. This option is deprecated, use
+    #   :timeout_ms instead.
+    # @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
@@ -396,11 +415,15 @@ module Mongo
     # @option options [ true, false ] :ssl_verify_hostname Whether to perform peer hostname
     #   validation. This setting overrides :ssl_verify with respect to whether hostname validation
     #   is performed.
+    # @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 not enabled.
     # @option options [ true, false ] :truncate_logs Whether to truncate the
     #   logs at the default 250 characters.
     # @option options [ String ] :user The user name.
     # @option options [ Float ] :wait_queue_timeout The time to wait, in
     #   seconds, in the connection pool for a connection to be checked in.
+    #   This option is deprecated, use :timeout_ms instead.
     # @option options [ Array<Hash> ] :wrapping_libraries Information about
     #   libraries such as ODMs that are wrapping the driver, to be added to
     #    metadata sent to the server. Specify the lower level libraries first.
@@ -408,7 +431,7 @@ module Mongo
     # @option options [ Hash ] :write Deprecated. Equivalent to :write_concern
     #   option.
     # @option options [ Hash ] :write_concern The write concern options.
-    #   Can be :w => Integer|String, :wtimeout => Integer (in milliseconds),
+    #   Can be :w => Integer|String, :wtimeout => Integer (in milliseconds, deprecated),
     #   :j => Boolean, :fsync => Boolean.
     # @option options [ Integer ] :zlib_compression_level The Zlib compression level to use, if using compression.
     #   See Ruby's Zlib module for valid levels.
@@ -420,11 +443,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 +461,27 @@ 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.
+    #   - :crypt_shared_lib_path => [ String | nil ]  Path that should
+    #     be  the used to load the crypt shared library. Providing this option
+    #     overrides default crypt shared library load paths for libmongocrypt.
+    #   - :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.
     #
     #   Notes on automatic encryption:
     #   - Automatic encryption is an enterprise only feature that only applies
@@ -532,7 +577,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
@@ -565,9 +610,9 @@ module Mongo
 
       rescue
         begin
-          @cluster.disconnect!
+          @cluster.close
         rescue => e
-          log_warn("Eror disconnecting cluster in client constructor's exception handler: #{e.class}: #{e}")
+          log_warn("Eror closing cluster in client constructor's exception handler: #{e.class}: #{e}")
           # Drop this exception so that the original exception is raised
         end
         raise
@@ -742,7 +787,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
@@ -828,6 +873,10 @@ module Mongo
       @write_concern ||= WriteConcern.get(options[:write_concern] || options[:write])
     end
 
+    def closed?
+      !!@closed
+    end
+
     # Close all connections.
     #
     # @return [ true ] Always true.
@@ -835,6 +884,7 @@ module Mongo
     # @since 2.1.0
     def close
       @connect_lock.synchronize do
+        @closed = true
         do_close
       end
       true
@@ -868,6 +918,8 @@ module Mongo
         if @options[:auto_encryption_options]
           build_encrypter
         end
+
+        @closed = false
       end
 
       true
@@ -885,9 +937,14 @@ 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 opts [ Object ] :comment A user-provided
+    #   comment to attach to this command.
+    # @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 not enabled.
     #
     # @return [ Array<String> ] The names of the databases.
     #
@@ -907,11 +964,18 @@ module Mongo
     #
     # @option opts [ true, false ] :authorized_databases A flag that determines
     #   which databases are returned based on user privileges when access control
-    #   is enabled
-    #
-    #   See https://docs.mongodb.com/manual/reference/command/listDatabases/
+    #   is enabled.
+    # @option opts [ Object ] :comment A user-provided
+    #   comment to attach to this command.
+    # @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 not enabled.
+    #
+    #   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 +997,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 +1050,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.
     #
-    # @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.
+    #   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'.
+    #
+    #   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 +1090,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 +1108,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[:cursor_type] = :tailable_await 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)
@@ -1062,6 +1162,9 @@ module Mongo
     #
     # @api private
     def with_session(options = {}, &block)
+      # TODO: Add this back in RUBY-3174.
+      # assert_not_closed
+
       session = get_session(options)
 
       yield session
@@ -1088,6 +1191,30 @@ 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
+
+    # @return [ Integer | nil ] Value of timeout_ms option if set.
+    # @api private
+    def timeout_ms
+      @options[:timeout_ms]
+    end
+
+    # @return [ Float | nil ] Value of timeout_ms option converted to seconds.
+    # @api private
+    def timeout_sec
+      if timeout_ms.nil?
+        nil
+      else
+        timeout_ms / 1_000.0
+      end
+    end
+
     private
 
     # Create a new encrypter object using the client's auto encryption options
@@ -1116,7 +1243,7 @@ module Mongo
 
     # Implementation for #close, assumes the connect lock is already acquired.
     def do_close
-      @cluster.disconnect!
+      @cluster.close
       close_encrypter
     end
 
@@ -1133,6 +1260,8 @@ module Mongo
     # @option options [ true | false ] :implicit When no session is passed in,
     #   whether to create an implicit session.
     # @option options [ Session ] :session The session to validate and return.
+    # @option options [ Operation::Context | nil ] :context Context of the
+    #   operation the session is used for.
     #
     # @return [ Session ] A session object.
     #
@@ -1145,13 +1274,28 @@ module Mongo
         return options[:session].validate!(self)
       end
 
-      cluster.validate_session_support!
+      cluster.validate_session_support!(timeout: timeout_sec)
 
-      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
@@ -1213,6 +1357,7 @@ module Mongo
         key = k.to_sym
         if VALID_OPTIONS.include?(key)
           validate_max_min_pool_size!(key, opts)
+          validate_max_connecting!(key, opts)
           validate_read!(key, opts)
           if key == :compressors
             compressors = valid_compressors(v)
@@ -1226,6 +1371,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 +1390,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 +1500,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 +1613,26 @@ 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
+
+    # Validates whether the max_connecting option is valid.
+    #
+    # @param [ Symbol ] option The option to validate.
+    # @param [ Hash ] opts The client options.
+    #
+    # @return [ true ] If the option is valid.
+    # @raise [ Error::InvalidMaxConnecting ] If the option is invalid.
+    def validate_max_connecting!(option, opts)
+      if option == :max_connecting && opts.key?(:max_connecting)
+        max_connecting = opts[:max_connecting] || Server::ConnectionPool::DEFAULT_MAX_CONNECTING
+        if max_connecting <= 0
+          raise Error::InvalidMaxConnecting.new(opts[:max_connecting])
+        end
       end
       true
     end
@@ -1454,7 +1644,7 @@ module Mongo
         # for custom classes implementing key access ([]).
         # Instead reject common cases of strings and symbols.
         if read.is_a?(String) || read.is_a?(Symbol)
-          raise Error::InvalidReadOption.new(read, 'must be a hash')
+          raise Error::InvalidReadOption.new(read, "the read preference must be specified as a hash: { mode: #{read.inspect} }")
         end
 
         if mode = read[:mode]
@@ -1466,5 +1656,11 @@ module Mongo
       end
       true
     end
+
+    def assert_not_closed
+      if closed?
+        raise Error::ClientClosed, "The client was closed and is not usable for operations. Call #reconnect to reset this client instance or create a new client instance"
+      end
+    end
   end
 end