mongo 2.11.4 → 2.18.1

data/lib/mongo/client.rb

@@ -1,4 +1,7 @@
-# Copyright (C) 2014-2019 MongoDB, Inc.
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2014-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the 'License');
 # you may not use this file except in compliance with the License.
@@ -27,6 +30,7 @@ module Mongo
     #
     # @since 2.1.0
     CRUD_OPTIONS = [
+      :auto_encryption_options,
       :database,
       :read, :read_concern,
       :write, :write_concern,
@@ -53,13 +57,17 @@ module Mongo
       :auth_mech,
       :auth_mech_properties,
       :auth_source,
+      :auto_encryption_options,
+      :bg_error_backtrace,
       :cleanup,
       :compressors,
+      :direct_connection,
       :connect,
       :connect_timeout,
       :database,
       :heartbeat_frequency,
       :id_generator,
+      :load_balanced,
       :local_threshold,
       :logger,
       :log_prefix,
@@ -81,8 +89,11 @@ module Mongo
       :retry_writes,
       :scan,
       :sdam_proc,
+      :server_api,
       :server_selection_timeout,
       :socket_timeout,
+      :srv_max_hosts,
+      :srv_service_name,
       :ssl,
       :ssl_ca_cert,
       :ssl_ca_cert_object,
@@ -97,9 +108,11 @@ module Mongo
       :ssl_verify,
       :ssl_verify_certificate,
       :ssl_verify_hostname,
+      :ssl_verify_ocsp_endpoint,
       :truncate_logs,
       :user,
       :wait_queue_timeout,
+      :wrapping_libraries,
       :write,
       :write_concern,
       :zlib_compression_level,
@@ -108,7 +121,16 @@ module Mongo
     # The compression algorithms supported by the driver.
     #
     # @since 2.5.0
-    VALID_COMPRESSORS = [ Mongo::Protocol::Compressed::ZLIB ].freeze
+    VALID_COMPRESSORS = [
+      Mongo::Protocol::Compressed::ZSTD,
+      Mongo::Protocol::Compressed::SNAPPY,
+      Mongo::Protocol::Compressed::ZLIB
+    ].freeze
+
+    # The known server API versions.
+    VALID_SERVER_API_VERSIONS = %w(
+      1
+    ).freeze
 
     # @return [ Mongo::Cluster ] cluster The cluster of servers for the client.
     attr_reader :cluster
@@ -119,6 +141,10 @@ module Mongo
     # @return [ Hash ] options The configuration options.
     attr_reader :options
 
+    # @return [ Mongo::Crypt::AutoEncrypter ] The object that encapsulates
+    #   auto-encryption behavior
+    attr_reader :encrypter
+
     # Delegate command and collections execution to the current database.
     def_delegators :@database, :command, :collections
 
@@ -199,7 +225,6 @@ module Mongo
     #   connection string is also provided, these options take precedence over any
     #   analogous options present in the URI string.
     #
-    #
     # @option options [ String, Symbol ] :app_name Application name that is
     #   printed to the mongod logs upon establishing a connection in server
     #   versions >= 3.4.
@@ -207,20 +232,33 @@ module Mongo
     #   use. One of :mongodb_cr, :mongodb_x509, :plain, :scram, :scram256
     # @option options [ Hash ] :auth_mech_properties
     # @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
+    #   background threads. Set to false or nil to not log backtraces. Provide
+    #   a positive integer to log up to that many backtrace lines.
     # @option options [ Array<String> ] :compressors A list of potential
     #   compressors to use, in order of preference. The driver chooses the
     #   first compressor that is also supported by the server. Currently the
-    #   driver only supports 'zlib'.
-    # @option options [ Symbol ] :connect The connection method to use. This
+    #   driver only supports 'zstd, 'snappy' and 'zlib'.
+    # @option options [ true | false ] :direct_connection Whether to connect
+    #   directly to the specified seed, bypassing topology discovery. Exactly
+    #   one seed must be provided.
+    # @option options [ Symbol ] :connect Deprecated - use :direct_connection
+    #   option instead of this option. The connection method to use. This
     #   forces the cluster to behave in the specified way instead of
-    #   auto-discovering. One of :direct, :replica_set, :sharded
+    #   auto-discovering. One of :direct, :replica_set, :sharded,
+    #   :load_balanced. If :connect is set to :load_balanced, the driver
+    #   will behave as if the server is a load balancer even if it isn't
+    #   connected to a load balancer.
     # @option options [ Float ] :connect_timeout The timeout, in seconds, to
     #   attempt a connection.
     # @option options [ String ] :database The database to connect to.
     # @option options [ Float ] :heartbeat_frequency The interval, in seconds,
-    #   for the server monitor to refresh its description via ismaster.
+    #   for the server monitor to refresh its description via hello.
     # @option options [ Object ] :id_generator A custom object to generate ids
     #   for documents. Must respond to #generate.
+    # @option options [ true | false ] :load_balanced Whether to expect to
+    #   connect to a load balancer.
     # @option options [ Integer ] :local_threshold The local threshold boundary
     #   in seconds for selecting a near server for an operation.
     # @option options [ Logger ] :logger A custom logger to use.
@@ -230,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
@@ -288,18 +326,30 @@ module Mongo
     #   will ignore it and will never scan seeds in the constructor.
     # @option options [ Proc ] :sdam_proc A Proc to invoke with the client
     #   as the argument prior to performing server discovery and monitoring.
-    #   Use this to set up SDAM event listeners to receive events dispatched
+    #   Use this to set up SDAM event listeners to receive events published
     #   during client construction.
     #
     #   Note: the client is not fully constructed when sdam_proc is invoked,
     #   in particular the cluster is nil at this time. sdam_proc should
     #   limit itself to calling #subscribe and #unsubscribe methods on the
     #   client only.
+    # @option options [ Hash ] :server_api The requested server API version.
+    #   This hash can have the following items:
+    #   - *:version* -- string
+    #   - *:strict* -- boolean
+    #   - *:deprecation_errors* -- boolean
     # @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.
-    # @option options [ true, false ] :ssl Whether to use SSL.
+    # @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
     #   other end of the connection. Intermediate certificates should NOT be
@@ -360,6 +410,10 @@ module Mongo
     # @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.
+    # @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.
+    #    Allowed hash keys: :name, :version, :platform.
     # @option options [ Hash ] :write Deprecated. Equivalent to :write_concern
     #   option.
     # @option options [ Hash ] :write_concern The write concern options.
@@ -369,6 +423,60 @@ module Mongo
     #   See Ruby's Zlib module for valid levels.
     # @option options [ Hash ] :resolv_options For internal driver use only.
     #   Options to pass through to Resolv::DNS constructor for SRV lookups.
+    # @option options [ Hash ] :auto_encryption_options Auto-encryption related
+    #   options.
+    #   - :key_vault_client => Client | nil, a client connected to the MongoDB
+    #     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 (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. 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
+    #       result in an error.
+    #     - Note: Supplying a schema_map provides more security than relying on
+    #       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
+    #     to operations on a collection.
+    #   - Automatic encryption is not supported for operations on a database or
+    #     view.
+    #   - Automatic encryption requires the authenticated user to have the
+    #     listCollections privilege.
+    #   - At worst, automatic encryption may triple the number of connections
+    #     used by the Client at any one time.
+    #   - If automatic encryption fails on an operation, use a MongoClient
+    #     configured with bypass_auto_encryption: true and use
+    #     ClientEncryption.encrypt to manually encrypt values.
+    #   - Enabling Client Side Encryption reduces the maximum write batch size
+    #     and may have a negative performance impact.
     #
     # @since 2.0.0
     def initialize(addresses_or_uri, options = nil)
@@ -395,14 +503,51 @@ module Mongo
         @srv_records = uri.srv_records
       else
         addresses = addresses_or_uri
+        addresses.each do |addr|
+          if addr =~ /\Amongodb(\+srv)?:\/\//i
+            raise ArgumentError, "Host '#{addr}' should not contain protocol. Did you mean to not use an array?"
+          end
+        end
+
         @srv_records = nil
       end
 
+      options = self.class.canonicalize_ruby_options(options)
+
+      # The server API version is specified to be a string.
+      # However, it is very annoying to always provide the number 1 as a string,
+      # therefore cast to the string type here.
+      if server_api = options[:server_api]
+        if server_api.is_a?(Hash)
+          server_api = Options::Redacted.new(server_api)
+          if (version = server_api[:version]).is_a?(Integer)
+            options[:server_api] = server_api.merge(version: version.to_s)
+          end
+        end
+      end
+
       # Special handling for sdam_proc as it is only used during client
       # construction
       sdam_proc = options.delete(:sdam_proc)
 
-      options = default_options(options).merge(options)
+      # For gssapi service_name, the default option is given in a hash
+      # (one level down from the top level).
+      merged_options = default_options(options)
+      options.each do |k, v|
+        default_v = merged_options[k]
+        if Hash === default_v
+          v = default_v.merge(v)
+        end
+        merged_options[k] = v
+      end
+      options = merged_options
+
+      options.keys.each do |k|
+        if options[k].nil?
+          options.delete(k)
+        end
+      end
+
       @options = validate_new_options!(options)
 =begin WriteConcern object support
       if @options[:write_concern].is_a?(WriteConcern::Base)
@@ -412,10 +557,12 @@ module Mongo
       end
 =end
       @options.freeze
-      validate_options!
+      validate_options!(addresses, is_srv: uri.is_a?(URI::SRVProtocol))
       validate_authentication_options!
 
-      @database = Database.new(self, @options[:database], @options)
+      database_options = @options.dup
+      database_options.delete(:server_api)
+      @database = Database.new(self, @options[:database], database_options)
 
       # Temporarily set monitoring so that event subscriptions can be
       # set up without there being a cluster
@@ -425,12 +572,39 @@ module Mongo
         sdam_proc.call(self)
       end
 
-      @cluster = Cluster.new(addresses, @monitoring, cluster_options.merge(srv_uri: srv_uri))
+      @connect_lock = Mutex.new
+      @connect_lock.synchronize do
+        @cluster = Cluster.new(addresses, @monitoring,
+          cluster_options.merge(srv_uri: srv_uri))
+      end
 
-      # Unset monitoring, it will be taken out of cluster from now on
-      remove_instance_variable('@monitoring')
+      begin
+        # Unset monitoring, it will be taken out of cluster from now on
+        remove_instance_variable('@monitoring')
+
+        if @options[:auto_encryption_options]
+          @connect_lock.synchronize do
+            build_encrypter
+          end
+        end
+
+      rescue
+        begin
+          @cluster.disconnect!
+        rescue => e
+          log_warn("Eror disconnecting cluster in client constructor's exception handler: #{e.class}: #{e}")
+          # Drop this exception so that the original exception is raised
+        end
+        raise
+      end
 
-      yield(self) if block_given?
+      if block_given?
+        begin
+          yield(self)
+        ensure
+          close
+        end
+      end
     end
 
     # @api private
@@ -503,15 +677,12 @@ module Mongo
 
     # Get a summary of the client state.
     #
-    # @note This method is experimental and subject to change.
-    #
-    # @example Inspect the client.
-    #   client.summary
+    # @note The exact format and layout of the returned summary string is
+    #   not part of the driver's public API and may be changed at any time.
     #
-    # @return [ String ] Summary string.
+    # @return [ String ] The summary string.
     #
     # @since 2.7.0
-    # @api experimental
     def summary
       "#<Client cluster=#{cluster.summary}>"
     end
@@ -541,7 +712,7 @@ module Mongo
     #
     # @return [ BSON::Document ] The user-defined read preference.
     #   The document may have the following fields:
-    #   - *:read* -- read preference specified as a symbol; valid values are
+    #   - *:mode* -- read preference specified as a symbol; valid values are
     #     *:primary*, *:primary_preferred*, *:secondary*, *:secondary_preferred*
     #     and *:nearest*.
     #   - *:tag_sets* -- an array of hashes.
@@ -589,14 +760,14 @@ module Mongo
     # @return [ Mongo::Client ] A new client instance.
     #
     # @since 2.0.0
-    def with(new_options = Options::Redacted.new)
+    def with(new_options = nil)
       clone.tap do |client|
-        opts = client.update_options(new_options)
+        opts = client.update_options(new_options || Options::Redacted.new)
         Database.create(client)
         # 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
@@ -616,6 +787,10 @@ module Mongo
     #
     # @api private
     def update_options(new_options)
+      old_options = @options
+
+      new_options = self.class.canonicalize_ruby_options(new_options || {})
+
       validate_new_options!(new_options).tap do |opts|
         # Our options are frozen
         options = @options.dup
@@ -625,8 +800,29 @@ module Mongo
         if options[:write_concern] && opts[:write]
           options.delete(:write_concern)
         end
+
         options.update(opts)
         @options = options.freeze
+
+        auto_encryption_options_changed =
+          @options[:auto_encryption_options] != old_options[:auto_encryption_options]
+
+        # If there are new auto_encryption_options, create a new encrypter.
+        # Otherwise, allow the new client to share an encrypter with the
+        # original client.
+        #
+        # If auto_encryption_options are nil, set @encrypter to nil, but do not
+        # close the encrypter because it may still be used by the original client.
+        if @options[:auto_encryption_options] && auto_encryption_options_changed
+          @connect_lock.synchronize do
+            build_encrypter
+          end
+        elsif @options[:auto_encryption_options].nil?
+          @connect_lock.synchronize do
+            @encrypter = nil
+          end
+        end
+
         validate_options!
         validate_authentication_options!
       end
@@ -644,7 +840,6 @@ module Mongo
       options[:read_concern]
     end
 
-
     # Get the write concern for this client. If no option was provided, then a
     # default single server acknowledgement will be used.
     #
@@ -664,7 +859,18 @@ module Mongo
     #
     # @since 2.1.0
     def close
-      @cluster.disconnect!
+      @connect_lock.synchronize do
+        do_close
+      end
+      true
+    end
+
+    # Close encrypter and clean up auto-encryption resources.
+    #
+    # @return [ true ] Always true.
+    def close_encrypter
+      @encrypter.close if @encrypter
+
       true
     end
 
@@ -679,9 +885,16 @@ module Mongo
     def reconnect
       addresses = cluster.addresses.map(&:to_s)
 
-      @cluster.disconnect! rescue nil
+      @connect_lock.synchronize do
+        do_close rescue nil
+
+        @cluster = Cluster.new(addresses, monitoring, cluster_options)
+
+        if @options[:auto_encryption_options]
+          build_encrypter
+        end
+      end
 
-      @cluster = Cluster.new(addresses, monitoring, cluster_options)
       true
     end
 
@@ -693,6 +906,16 @@ module Mongo
     # @param [ Hash ] filter The filter criteria for getting a list of databases.
     # @param [ Hash ] opts The command options.
     #
+    # @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://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.
     #
     # @since 2.0.5
@@ -709,6 +932,16 @@ module Mongo
     # @param [ true, false ] name_only Whether to only return each database name without full metadata.
     # @param [ Hash ] opts The command options.
     #
+    # @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://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.
     #
     # @since 2.0.5
@@ -716,6 +949,7 @@ module Mongo
       cmd = { listDatabases: 1 }
       cmd[:nameOnly] = !!name_only
       cmd[:filter] = filter unless filter.empty?
+      cmd[:authorizedDatabases] = true if opts[:authorized_databases]
       use(Database::ADMIN).database.read_command(cmd, opts).first[Database::DATABASES]
     end
 
@@ -727,6 +961,10 @@ module Mongo
     # @param [ Hash ] filter The filter criteria for getting a list of databases.
     # @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.
     #
     # @since 2.5.0
@@ -756,8 +994,16 @@ module Mongo
     #
     # @since 2.5.0
     def start_session(options = {})
-      get_session(options.merge(implicit: false)) or
-        raise Error::InvalidSession.new(Session::SESSIONS_NOT_SUPPORTED)
+      session = get_session!(options.merge(implicit: false))
+      if block_given?
+        begin
+          yield session
+        ensure
+          session.end_session
+        end
+      else
+        session
+      end
     end
 
     # As of version 3.6 of the MongoDB server, a ``$changeStream`` pipeline stage is supported
@@ -769,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'.
     #
-    # @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
+    #   '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'.
+    #
+    #   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
@@ -785,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
@@ -796,15 +1073,103 @@ 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)
     end
 
+    # Returns a session to use for operations if possible.
+    #
+    # If :session option is set, validates that session and returns it.
+    # Otherwise, if deployment supports sessions, creates a new session and
+    # returns it. When a new session is created, the session will be implicit
+    # (lifecycle is managed by the driver) if the :implicit option is given,
+    # otherwise the session will be explicit (lifecycle managed by the
+    # application). If deployment does not support session, returns nil.
+    #
+    # @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.
+    #
+    # @return [ Session | nil ] Session object or nil if sessions are not
+    #   supported by the deployment.
+    #
+    # @api private
+    def get_session(options = {})
+      get_session!(options)
+    rescue Error::SessionsNotSupported
+      nil
+    end
+
+    # Creates a session to use for operations if possible and yields it to
+    # the provided block.
+    #
+    # If :session option is set, validates that session and uses it.
+    # Otherwise, if deployment supports sessions, creates a new session and
+    # uses it. When a new session is created, the session will be implicit
+    # (lifecycle is managed by the driver) if the :implicit option is given,
+    # otherwise the session will be explicit (lifecycle managed by the
+    # application). If deployment does not support session, yields nil to
+    # the block.
+    #
+    # When the block finishes, if the session was created and was implicit,
+    # or if an implicit session was passed in, the session is ended which
+    # returns it to the pool of available sessions.
+    #
+    # @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.
+    #
+    # @api private
+    def with_session(options = {}, &block)
+      session = get_session(options)
+
+      yield session
+    ensure
+      if session && session.implicit?
+        session.end_session
+      end
+    end
+
+    class << self
+      # Lowercases auth mechanism properties, if given, in the specified
+      # options, then converts the options to an instance of Options::Redacted.
+      #
+      # @api private
+      def canonicalize_ruby_options(options)
+        Options::Redacted.new(Hash[options.map do |k, v|
+          if k == :auth_mech_properties || k == 'auth_mech_properties'
+            if v
+              v = Hash[v.map { |pk, pv| [pk.downcase, pv] }]
+            end
+          end
+          [k, v]
+        end])
+      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
+    def build_encrypter
+      @encrypter = Crypt::AutoEncrypter.new(
+        @options[:auto_encryption_options].merge(client: self)
+      )
+    end
+
     # Generate default client options based on the URI and options
     # passed into the Client constructor.
     def default_options(options)
@@ -822,34 +1187,59 @@ module Mongo
       end
     end
 
-    # If options[:session] is set, validates that session and returns it.
-    # If deployment supports sessions, creates a new session and returns it.
-    # The session is implicit unless options[:implicit] is given.
-    # If deployment does not support session, returns nil.
+    # Implementation for #close, assumes the connect lock is already acquired.
+    def do_close
+      @cluster.disconnect!
+      close_encrypter
+    end
+
+    # Returns a session to use for operations.
     #
-    # @return [ Session | nil ] Session object or nil if sessions are not
-    #   supported by the deployment.
-    def get_session(options = {})
+    # If :session option is set, validates that session and returns it.
+    # Otherwise, if deployment supports sessions, creates a new session and
+    # returns it. When a new session is created, the session will be implicit
+    # (lifecycle is managed by the driver) if the :implicit option is given,
+    # otherwise the session will be explicit (lifecycle managed by the
+    # application). If deployment does not support session, raises
+    # Error::InvalidSession.
+    #
+    # @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.
+    #
+    # @return [ Session ] A session object.
+    #
+    # @raise Error::SessionsNotSupported if sessions are not supported by
+    #   the deployment.
+    #
+    # @api private
+    def get_session!(options = {})
       if options[:session]
         return options[:session].validate!(self)
       end
 
-      if cluster.sessions_supported?
-        Session.new(cluster.session_pool.checkout, self, { implicit: true }.merge(options))
-      end
-    end
+      cluster.validate_session_support!
 
-    def with_session(options = {}, &block)
-      session = get_session(options)
-      yield(session)
-    ensure
-      if session && session.implicit?
-        session.end_session
+      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
@@ -869,8 +1259,42 @@ module Mongo
     # The argument may contain a subset of options that the client will
     # eventually have; this method validates each of the provided options
     # but does not check for interactions between combinations of options.
-    def validate_new_options!(opts = Options::Redacted.new)
+    def validate_new_options!(opts)
       return Options::Redacted.new unless opts
+      if opts[:read_concern]
+        # Raise an error for non user-settable options
+        if opts[:read_concern][:after_cluster_time]
+          raise Mongo::Error::InvalidReadConcern.new(
+            'The after_cluster_time read_concern option cannot be specified by the user'
+          )
+        end
+
+        given_keys = opts[:read_concern].keys.map(&:to_s)
+        allowed_keys = ['level']
+        invalid_keys = given_keys - allowed_keys
+        # Warn that options are invalid but keep it and forward to the server
+        unless invalid_keys.empty?
+          log_warn("Read concern has invalid keys: #{invalid_keys.join(',')}.")
+        end
+      end
+
+      if server_api = opts[:server_api]
+        unless server_api.is_a?(Hash)
+          raise ArgumentError, ":server_api value must be a hash: #{server_api}"
+        end
+
+        extra_keys = server_api.keys - %w(version strict deprecation_errors)
+        unless extra_keys.empty?
+          raise ArgumentError, "Unknown keys under :server_api: #{extra_keys.map(&:inspect).join(', ')}"
+        end
+
+        if version = server_api[:version]
+          unless VALID_SERVER_API_VERSIONS.include?(version)
+            raise ArgumentError, "Unknown server API version: #{version}"
+          end
+        end
+      end
+
       Lint.validate_underscore_read_preference(opts[:read])
       Lint.validate_read_concern_option(opts[:read_concern])
       opts.each.inject(Options::Redacted.new) do |_options, (k, v)|
@@ -880,7 +1304,22 @@ module Mongo
           validate_read!(key, opts)
           if key == :compressors
             compressors = valid_compressors(v)
+
+            if compressors.include?('snappy')
+              validate_snappy_compression!
+            end
+
+            if compressors.include?('zstd')
+              validate_zstd_compression!
+            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
@@ -894,10 +1333,136 @@ 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!
+    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
+
+      connect = options[:connect]&.to_sym
+
+      if connect && !%i(direct replica_set sharded load_balanced).include?(connect)
+        raise ArgumentError, "Invalid :connect option value: #{connect}"
+      end
+
+      if options[:direct_connection]
+        if connect && connect != :direct
+          raise ArgumentError, "Conflicting client options: direct_connection=true and connect=#{connect}"
+        end
+        # When a new client is created, we get the list of seed addresses
+        if addresses && addresses.length > 1
+          raise ArgumentError, "direct_connection=true cannot be used with multiple seeds"
+        end
+        # When a client is copied using #with, we have a cluster
+        if cluster && !cluster.topology.is_a?(Mongo::Cluster::Topology::Single)
+          raise ArgumentError, "direct_connection=true cannot be used with topologies other than Single (this client is #{cluster.topology.class.name.sub(/.*::/, '')})"
+        end
+      end
+
+      if options[:load_balanced]
+        if addresses && addresses.length > 1
+          raise ArgumentError, "load_balanced=true cannot be used with multiple seeds"
+        end
+
+        if options[:direct_connection]
+          raise ArgumentError, "direct_connection=true cannot be used with load_balanced=true"
+        end
+
+        if connect && connect != :load_balanced
+          raise ArgumentError, "connect=#{connect} cannot be used with load_balanced=true"
+        end
+
+        if options[:replica_set]
+          raise ArgumentError, "load_balanced=true cannot be used with replica_set option"
+        end
+      end
+
+      if connect == :load_balanced
+        if addresses && addresses.length > 1
+          raise ArgumentError, "connect=load_balanced cannot be used with multiple seeds"
+        end
+
+        if options[:replica_set]
+          raise ArgumentError, "connect=load_balanced cannot be used with replica_set option"
+        end
+      end
+
+      if options[:direct_connection] == false && connect && connect == :direct
+        raise ArgumentError, "Conflicting client options: direct_connection=false and connect=#{connect}"
+      end
+
+      %i(connect_timeout socket_timeout).each do |key|
+        if value = options[key]
+          unless Numeric === value
+            raise ArgumentError, "#{key} must be a non-negative number: #{value}"
+          end
+          if value < 0
+            raise ArgumentError, "#{key} must be a non-negative number: #{value}"
+          end
+        end
+      end
+
+      if value = options[:bg_error_backtrace]
+        case value
+        when Integer
+          if value <= 0
+            raise ArgumentError, ":bg_error_backtrace option value must be true, false, nil or a positive integer: #{value}"
+          end
+        when true
+          # OK
+        else
+          raise ArgumentError, ":bg_error_backtrace option value must be true, false, nil or a positive integer: #{value}"
+        end
+      end
+
+      if libraries = options[:wrapping_libraries]
+        unless Array === libraries
+          raise ArgumentError, ":wrapping_libraries must be an array of hashes: #{libraries}"
+        end
+
+        libraries = libraries.map do |library|
+          Utils.shallow_symbolize_keys(library)
+        end
+
+        libraries.each do |library|
+          unless Hash === library
+            raise ArgumentError, ":wrapping_libraries element is not a hash: #{library}"
+          end
+
+          if library.empty?
+            raise ArgumentError, ":wrapping_libraries element is empty"
+          end
+
+          unless (library.keys - %i(name platform version)).empty?
+            raise ArgumentError, ":wrapping_libraries element has invalid keys (allowed keys: :name, :platform, :version): #{library}"
+          end
+
+          library.each do |key, value|
+            if value.include?('|')
+              raise ArgumentError, ":wrapping_libraries element value cannot include '|': #{value}"
+            end
+          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
@@ -911,7 +1476,11 @@ module Mongo
 
       if auth_mech.nil?
         if user && user.empty?
-          raise Mongo::Auth::InvalidConfiguration.new('empty username is not supported for default auth mechanism')
+          raise Mongo::Auth::InvalidConfiguration, 'Empty username is not supported for default auth mechanism'
+        end
+
+        if auth_source == ''
+          raise Mongo::Auth::InvalidConfiguration, 'Auth source cannot be empty for default auth mechanism'
         end
 
         return
@@ -921,24 +1490,35 @@ module Mongo
         raise Mongo::Auth::InvalidMechanism.new(auth_mech)
       end
 
-      if user.nil? && auth_mech != :mongodb_x509
-        raise Mongo::Auth::InvalidConfiguration.new("user is required for mechanism #{auth_mech}")
+      if user.nil? && !%i(aws mongodb_x509).include?(auth_mech)
+        raise Mongo::Auth::InvalidConfiguration, "Username is required for auth mechanism #{auth_mech}"
       end
 
-      if password.nil? && ![:gssapi, :mongodb_x509].include?(auth_mech)
-        raise Mongo::Auth::InvalidConfiguration.new("password is required for mechanism #{auth_mech}")
+      if password.nil? && !%i(aws gssapi mongodb_x509).include?(auth_mech)
+        raise Mongo::Auth::InvalidConfiguration, "Password is required for auth mechanism #{auth_mech}"
       end
 
       if password && auth_mech == :mongodb_x509
-        raise Mongo::Auth::InvalidConfiguration.new('password is not supported for mongodb_x509')
+        raise Mongo::Auth::InvalidConfiguration, 'Password is not supported for :mongodb_x509 auth mechanism'
+      end
+
+      if auth_mech == :aws && user && !password
+        raise Mongo::Auth::InvalidConfiguration, 'Username is provided but password is not provided for :aws auth mechanism'
       end
 
-      if !['$external', nil].include?(auth_source) && [:gssapi, :mongodb_x509].include?(auth_mech)
-        raise Mongo::Auth::InvalidConfiguration.new("#{auth_source} is an invalid auth source for #{auth_mech}; valid options are $external and nil")
+      if %i(aws gssapi mongodb_x509).include?(auth_mech)
+        if !['$external', nil].include?(auth_source)
+          raise Mongo::Auth::InvalidConfiguration, "#{auth_source} is an invalid auth source for #{auth_mech}; valid options are $external and nil"
+        end
+      else
+        # Auth source is the database name, and thus cannot be the empty string.
+        if auth_source == ''
+          raise Mongo::Auth::InvalidConfiguration, "Auth source cannot be empty for auth mechanism #{auth_mech}"
+        end
       end
 
-      if mech_properties && auth_mech != :gssapi
-        raise Mongo::Auth::InvalidConfiguration.new("mechanism_properties are not supported for #{auth_mech}")
+      if mech_properties && !%i(aws gssapi).include?(auth_mech)
+        raise Mongo::Auth::InvalidConfiguration, ":mechanism_properties are not supported for auth mechanism #{auth_mech}"
       end
     end
 
@@ -949,15 +1529,36 @@ module Mongo
                        "This compressor will not be used.")
           false
         else
+
           true
         end
       end
     end
 
+    def validate_snappy_compression!
+      return if defined?(Snappy)
+      require 'snappy'
+    rescue LoadError => e
+      raise Error::UnmetDependency, "Cannot enable snappy compression because the snappy gem " \
+        "has not been installed. Add \"gem 'snappy'\" to your Gemfile and run " \
+        "\"bundle install\" to install the gem. (#{e.class}: #{e})"
+    end
+
+    def validate_zstd_compression!
+      return if defined?(Zstd)
+      require 'zstd-ruby'
+    rescue LoadError => e
+      raise Error::UnmetDependency, "Cannot enable zstd compression because the zstd-ruby gem " \
+        "has not been installed. Add \"gem 'zstd-ruby'\" to your Gemfile and run " \
+        "\"bundle install\" to install the gem. (#{e.class}: #{e})"
+    end
+
     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