mongo 2.6.4 → 2.7.0.rc0

data/lib/mongo/auth/stringprep/tables.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2018 MongoDB, Inc.
+# Copyright (C) 2018-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/auth/user.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB Inc.
+# Copyright (C) 2014-2019 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

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

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB, Inc.
+# Copyright (C) 2014-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,7 +16,7 @@ module Mongo
   module Auth
     class User
 
-      # Defines behaviour for user related operation on databases.
+      # Defines behavior for user related operation on databases.
       #
       # @since 2.0.0
       class View

data/lib/mongo/auth/x509.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB Inc.
+# Copyright (C) 2014-2019 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -17,7 +17,7 @@ require 'mongo/auth/x509/conversation'
 module Mongo
   module Auth
 
-    # Defines behaviour for x.509 authentication.
+    # Defines behavior for x.509 authentication.
     #
     # @since 2.0.0
     class X509

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

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB Inc.
+# Copyright (C) 2014-2019 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,7 +16,7 @@ module Mongo
   module Auth
     class X509
 
-      # Defines behaviour around a single x.509 conversation between the
+      # Defines behavior around a single x.509 conversation between the
       # client and server.
       #
       # @since 2.0.0
@@ -69,7 +69,7 @@ module Mongo
             selector[Protocol::Msg::DATABASE_IDENTIFIER] = user.auth_source
             cluster_time = connection.mongos? && connection.cluster_time
             selector[Operation::CLUSTER_TIME] = cluster_time if cluster_time
-            Protocol::Msg.new([:none], {}, selector)
+            Protocol::Msg.new([], {}, selector)
           else
             Protocol::Query.new(
               Auth::EXTERNAL,

data/lib/mongo/bson.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2018 MongoDB, Inc.
+# Copyright (C) 2015-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/bulk_write.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB, Inc.
+# Copyright (C) 2014-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/bulk_write/combineable.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2018 MongoDB, Inc.
+# Copyright (C) 2015-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -15,7 +15,7 @@
 module Mongo
   class BulkWrite
 
-    # Defines behaviour around combiners
+    # Defines behavior around combiners
     #
     # @api private
     #

data/lib/mongo/bulk_write/ordered_combiner.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2018 MongoDB, Inc.
+# Copyright (C) 2015-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/bulk_write/result.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2018 MongoDB, Inc.
+# Copyright (C) 2015-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/bulk_write/result_combiner.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2018 MongoDB, Inc.
+# Copyright (C) 2015-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/bulk_write/transformable.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2018 MongoDB, Inc.
+# Copyright (C) 2015-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -15,7 +15,7 @@
 module Mongo
   class BulkWrite
 
-    # Defines behaviour around transformations.
+    # Defines behavior around transformations.
     #
     # @api private
     #

data/lib/mongo/bulk_write/unordered_combiner.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2018 MongoDB, Inc.
+# Copyright (C) 2015-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/bulk_write/validatable.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2018 MongoDB, Inc.
+# Copyright (C) 2015-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -15,7 +15,7 @@
 module Mongo
   class BulkWrite
 
-    # Defines behaviour around validations.
+    # Defines behavior around validations.
     #
     # @api private
     #

data/lib/mongo/client.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB, Inc.
+# Copyright (C) 2014-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the 'License');
 # you may not use this file except in compliance with the License.
@@ -22,11 +22,11 @@ module Mongo
     extend Forwardable
     include Loggable
 
-    # The options that do not affect the behaviour of a cluster and its
+    # The options that do not affect the behavior of a cluster and its
     # subcomponents.
     #
     # @since 2.1.0
-    CRUD_OPTIONS = [ :database, :read, :write ].freeze
+    CRUD_OPTIONS = [ :database, :read, :write, :retry_writes ].freeze
 
     # Valid client options.
     #
@@ -36,9 +36,9 @@ module Mongo
       :auth_mech,
       :auth_mech_properties,
       :auth_source,
+      :compressors,
       :connect,
       :connect_timeout,
-      :compressors,
       :database,
       :heartbeat_frequency,
       :id_generator,
@@ -49,6 +49,7 @@ module Mongo
       :max_read_retries,
       :min_pool_size,
       :monitoring,
+      :monitoring_io,
       :password,
       :platform,
       :read,
@@ -56,25 +57,29 @@ module Mongo
       :read_retry_interval,
       :replica_set,
       :retry_writes,
+      :scan,
+      :sdam_proc,
       :server_selection_timeout,
       :socket_timeout,
       :ssl,
       :ssl_ca_cert,
-      :ssl_ca_cert_string,
       :ssl_ca_cert_object,
+      :ssl_ca_cert_string,
       :ssl_cert,
-      :ssl_cert_string,
       :ssl_cert_object,
+      :ssl_cert_string,
       :ssl_key,
-      :ssl_key_string,
       :ssl_key_object,
       :ssl_key_pass_phrase,
+      :ssl_key_string,
       :ssl_verify,
+      :ssl_verify_certificate,
+      :ssl_verify_hostname,
       :truncate_logs,
       :user,
       :wait_queue_timeout,
       :write,
-      :zlib_compression_level
+      :zlib_compression_level,
     ].freeze
 
     # The compression algorithms supported by the driver.
@@ -97,9 +102,15 @@ module Mongo
     # Delegate subscription to monitoring.
     def_delegators :monitoring, :subscribe, :unsubscribe
 
-    # Delegate monitoring to cluster.
-    def_delegators :cluster, :monitoring
-
+    # @return [ Monitoring ] monitoring The monitoring.
+    # @api private
+    def monitoring
+      if cluster
+        cluster.monitoring
+      else
+        @monitoring
+      end
+    end
     private :monitoring
 
     # Determine if this client is equivalent to another object.
@@ -163,34 +174,58 @@ module Mongo
     #   form of host:port or a MongoDB URI connection string.
     # @param [ Hash ] options The options to be used by the client.
     #
+    #
+    # @option options [ String, Symbol ] :app_name Application name that is
+    #   printed to the mongod logs upon establishing a connection in server
+    #   versions >= 3.4.
     # @option options [ Symbol ] :auth_mech The authentication mechanism to
     #   use. One of :mongodb_cr, :mongodb_x509, :plain, :scram, :scram256
+    # @option options [ Hash ] :auth_mech_properties
     # @option options [ String ] :auth_source The source to authenticate from.
+    # @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
     #   forces the cluster to behave in the specified way instead of
     #   auto-discovering. One of :direct, :replica_set, :sharded
+    # @option options [ Float ] :connect_timeout The timeout, in seconds, to
+    #   attempt a connection.
     # @option options [ String ] :database The database to connect to.
-    # @option options [ Hash ] :auth_mech_properties
     # @option options [ Float ] :heartbeat_frequency The number of seconds for
     #   the server monitor to refresh it's description via ismaster.
+    # @option options [ Object ] :id_generator A custom object to generate ids
+    #   for documents. Must respond to #generate.
     # @option options [ Integer ] :local_threshold The local threshold boundary
     #   in seconds for selecting a near server for an operation.
-    # @option options [ Integer ] :server_selection_timeout The timeout in seconds
-    #   for selecting a server for an operation.
-    # @option options [ String ] :password The user's password.
+    # @option options [ Logger ] :logger A custom logger if desired.
     # @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.
+    # @option options [ Integer ] :max_read_retries The maximum number of read
+    #   retries on mongos query failures.
     # @option options [ Integer ] :min_pool_size The minimum size of the
     #   connection pool.
-    # @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 [ Float ] :connect_timeout The timeout, in seconds, to
-    #   attempt a connection.
-    # @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 [ true, false ] :monitoring If false is given, the
+    #   client is initialized without global SDAM event subscribers and
+    #   will not publish SDAM events. Command monitoring and legacy events
+    #   will still be published, and the driver will still perform SDAM and
+    #   monitor its cluster in order to perform server selection. Built-in
+    #   driver logging of SDAM events will be disabled because it is
+    #   implemented through SDAM event subscription. Client#subscribe will
+    #   succeed for all event types, but subscribers to SDAM events will
+    #   not be invoked. Values other than false result in default behavior
+    #   which is to perform normal SDAM event publication.
+    # @option options [ true, false ] :monitoring_io For internal driver
+    #   use only. Set to false to prevent SDAM-related I/O from being
+    #   done by this client or servers under it. Note: setting this option
+    #   to false will make the client non-functional. It is intended for
+    #   use in tests which manually invoke SDAM state transitions.
+    # @option options [ String ] :password The user's password.
+    # @option options [ String ] :platform Platform information to include in
+    #   the metadata printed to the mongod logs upon establishing a connection
+    #   in server versions >= 3.4.
     # @option options [ Hash ] :read The read preference options. The hash
     #   may have the following items:
     #   - *:mode* -- read preference specified as a symbol; valid values are
@@ -198,74 +233,93 @@ module Mongo
     #     and *:nearest*.
     #   - *:tag_sets* -- an array of hashes.
     #   - *:local_threshold*.
+    # @option options [ Hash ] :read_concern The read concern option.
+    # @option options [ Float ] :read_retry_interval The interval, in seconds,
+    #   in which reads on a mongos are retried.
     # @option options [ Symbol ] :replica_set The name of the replica set to
     #   connect to. Servers not in this replica set will be ignored.
+    # @option options [ true, false ] :retry_writes Retry writes once when
+    #   connected to a replica set or sharded cluster versions 3.6 and up.
+    # @option options [ true, false ] :scan Whether to scan all seeds
+    #   in constructor. The default in driver version 2.x is to do so;
+    #   driver version 3.x will not scan seeds in constructor. Opt in to the
+    #   new behavior by setting this option to false. *Note:* setting
+    #   this option to nil enables scanning seeds in constructor in driver
+    #   version 2.x. Driver version 3.x will recognize this option but
+    #   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
+    #   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 [ 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 [ String ] :ssl_ca_cert The file containing concatenated
+    #   certificate authority certificates used to validate certs passed from the
+    #   other end of the connection. One of :ssl_ca_cert, :ssl_ca_cert_string or
+    #   :ssl_ca_cert_object (in order of priority) is required for :ssl_verify.
+    # @option options [ Array<OpenSSL::X509::Certificate> ] :ssl_ca_cert_object An array of
+    #   OpenSSL::X509::Certificate representing the certificate authority certificates used
+    #   to validate certs passed from the other end of the connection. One of :ssl_ca_cert,
+    #   :ssl_ca_cert_string or :ssl_ca_cert_object (in order of priority) is required for :ssl_verify.
+    # @option options [ String ] :ssl_ca_cert_string A string containing concatenated
+    #   certificate authority certificates used to validate certs passed from the
+    #   other end of the connection. One of :ssl_ca_cert, :ssl_ca_cert_string or
+    #   :ssl_ca_cert_object (in order of priority) is required for :ssl_verify.
     # @option options [ String ] :ssl_cert The certificate file used to identify
     #   the connection against MongoDB. This option, if present, takes precedence
     #   over the values of :ssl_cert_string and :ssl_cert_object
+    # @option options [ OpenSSL::X509::Certificate ] :ssl_cert_object The OpenSSL::X509::Certificate
+    #   used to identify the connection against MongoDB
     # @option options [ String ] :ssl_cert_string A string containing the PEM-encoded
     #   certificate used to identify the connection against MongoDB. This option, if present,
     #   takes precedence over the value of :ssl_cert_object
-    # @option options [ OpenSSL::X509::Certificate ] :ssl_cert_object The OpenSSL::X509::Certificate
-    #   used to identify the connection against MongoDB
     # @option options [ String ] :ssl_key The private keyfile used to identify the
     #   connection against MongoDB. Note that even if the key is stored in the same
     #   file as the certificate, both need to be explicitly specified. This option,
     #   if present, takes precedence over the values of :ssl_key_string and :ssl_key_object
-    # @option options [ String ] :ssl_key_string A string containing the PEM-encoded private key
-    #   used to identify the connection against MongoDB. This parameter, if present,
-    #   takes precedence over the value of option :ssl_key_object
     # @option options [ OpenSSL::PKey ] :ssl_key_object The private key used to identify the
     #   connection against MongoDB
     # @option options [ String ] :ssl_key_pass_phrase A passphrase for the private key.
-    # @option options [ true, false ] :ssl_verify Whether to do peer certificate
-    #   validation.
-    # @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. One of :ssl_ca_cert, :ssl_ca_cert_string or
-    #   :ssl_ca_cert_object (in order of priority) is required for :ssl_verify.
-    # @option options [ String ] :ssl_ca_cert_string A string containing concatenated
-    #   certificate authority certificates used to validate certs passed from the
-    #   other end of the connection. One of :ssl_ca_cert, :ssl_ca_cert_string or
-    #   :ssl_ca_cert_object (in order of priority) is required for :ssl_verify.
-    # @option options [ Array<OpenSSL::X509::Certificate> ] :ssl_ca_cert_object An array of
-    #   OpenSSL::X509::Certificate representing the certificate authority certificates used
-    #   to validate certs passed from the other end of the connection. One of :ssl_ca_cert,
-    #   :ssl_ca_cert_string or :ssl_ca_cert_object (in order of priority) is required for :ssl_verify.
-    # @option options [ Float ] :socket_timeout The timeout, in seconds, to
-    #   execute operations on a socket.
+    # @option options [ String ] :ssl_key_string A string containing the PEM-encoded private key
+    #   used to identify the connection against MongoDB. This parameter, if present,
+    #   takes precedence over the value of option :ssl_key_object
+    # @option options [ true, false ] :ssl_verify Whether to perform peer certificate validation and
+    #   hostname verification. Note that the decision of whether to validate certificates will be
+    #   overridden if :ssl_verify_certificate is set, and the decision of whether to validate
+    #   hostnames will be overridden if :ssl_verify_hostname is set.
+    # @option options [ true, false ] :ssl_verify_certificate Whether to perform peer certificate
+    #   validation. This setting overrides :ssl_verify with respect to whether certificate
+    #   validation is performed.
+    # @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 [ 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.
     # @option options [ Hash ] :write The write concern options. Can be :w =>
     #   Integer|String, :fsync => Boolean, :j => Boolean.
-    # @option options [ Hash ] :read_concern The read concern option.
-    # @option options [ true, false ] :monitoring Initializes a client without
-    #   any default monitoring if false is provided.
-    # @option options [ Logger ] :logger A custom logger if desired.
-    # @option options [ true, false ] :truncate_logs Whether to truncate the
-    #   logs at the default 250 characters.
-    # @option options [ Integer ] :max_read_retries The maximum number of read
-    #   retries on mongos query failures.
-    # @option options [ Float ] :read_retry_interval The interval, in seconds,
-    #   in which reads on a mongos are retried.
-    # @option options [ Object ] :id_generator A custom object to generate ids
-    #   for documents. Must respond to #generate.
-    # @option options [ String, Symbol ] :app_name Application name that is printed to the
-    #   mongod logs upon establishing a connection in server versions >= 3.4.
-    # @option options [ String ] :platform Platform information to include in the
-    #   metadata printed to the mongod logs upon establishing a connection in server versions >= 3.4.
     # @option options [ Integer ] :zlib_compression_level The Zlib compression level to use, if using compression.
     #   See Ruby's Zlib module for valid levels.
-    # @option options [ true, false ] :retry_writes Retry writes once when
-    #   connected to a replica set or sharded cluster versions 3.6 and up.
-    # @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
-    #   during client construction.
     #
     # @since 2.0.0
-    def initialize(addresses_or_uri, options = Options::Redacted.new)
-      Mongo::Lint.validate_underscore_read_preference(options[:read])
+    def initialize(addresses_or_uri, options = nil)
+      if options
+        options = options.dup
+      else
+        options = {}
+      end
+      Lint.validate_underscore_read_preference(options[:read])
+      Lint.validate_read_concern_option(options[:read_concern])
       if addresses_or_uri.is_a?(::String)
         uri = URI.get(addresses_or_uri, options)
         addresses = uri.servers
@@ -273,21 +327,39 @@ module Mongo
       else
         addresses = addresses_or_uri
       end
-      options = options.dup
       # Special handling for sdam_proc as it is only used during client
       # construction
       sdam_proc = options.delete(:sdam_proc)
       @options = validate_options!(Database::DEFAULT_OPTIONS.merge(options)).freeze
       @database = Database.new(self, @options[:database], @options)
-      monitoring = Monitoring.new(@options)
+      # Temporarily set monitoring so that event subscriptions can be
+      # set up without there being a cluster
+      @monitoring = Monitoring.new(@options)
       if sdam_proc
-        @cluster = Cluster.new([], monitoring, @options)
         sdam_proc.call(self)
       end
-      @cluster = Cluster.new(addresses, monitoring, @options)
+      @server_selection_semaphore = Semaphore.new
+      @cluster = Cluster.new(addresses, @monitoring, cluster_options)
+      # Unset monitoring, it will be taken out of cluster from now on
+      remove_instance_variable('@monitoring')
+
       yield(self) if block_given?
     end
 
+    # @api private
+    def cluster_options
+      # We share clusters when a new client with different CRUD_OPTIONS
+      # is requested; therefore, cluster should not be getting any of these
+      # options upon instantiation
+      options.reject do |key, value|
+        CRUD_OPTIONS.include?(key.to_sym)
+      end.merge(
+        server_selection_semaphore: @server_selection_semaphore,
+        # but need to put the database back in for auth...
+        database: options[:database],
+      )
+    end
+
     # Get an inspection of the client as a string.
     #
     # @example Inspect the client.
@@ -297,7 +369,22 @@ module Mongo
     #
     # @since 2.0.0
     def inspect
-      "#<Mongo::Client:0x#{object_id} cluster=#{cluster.addresses.join(', ')}>"
+      "#<Mongo::Client:0x#{object_id} cluster=#{cluster.summary}>"
+    end
+
+    # Get a summary of the client state.
+    #
+    # @note This method is experimental and subject to change.
+    #
+    # @example Inspect the client.
+    #   client.summary
+    #
+    # @return [ String ] Summary string.
+    #
+    # @since 2.7.0
+    # @api experimental
+    def summary
+      "#<Client cluster=#{cluster.summary}>"
     end
 
     # Get the server selector. It either uses the read preference
@@ -332,25 +419,35 @@ module Mongo
       @read_preference ||= options[:read]
     end
 
-    # Use the database with the provided name. This will switch the current
-    # database the client is operating on.
+    # Creates a new client configured to use the database with the provided
+    # name, and using the other options configured in this client.
     #
-    # @example Use the provided database.
+    # @note The new client shares the cluster with the original client,
+    #   and as a result also shares the monitoring instance and monitoring
+    #   event subscribers.
+    #
+    # @example Create a client for the `users' database.
     #   client.use(:users)
     #
     # @param [ String, Symbol ] name The name of the database to use.
     #
-    # @return [ Mongo::Client ] The new client with new database.
+    # @return [ Mongo::Client ] A new client instance.
     #
     # @since 2.0.0
     def use(name)
       with(database: name)
     end
 
-    # Provides a new client with the passed options merged over the existing
+    # Creates a new client with the passed options merged over the existing
     # options of this client. Useful for one-offs to change specific options
     # without altering the original client.
     #
+    # @note Depending on options given, the returned client may share the
+    #   cluster with the original client or be created with a new cluster.
+    #   If a new cluster is created, the monitoring event subscribers on
+    #   the new client are set to the default event subscriber set and
+    #   none of the subscribers on the original client are copied over.
+    #
     # @example Get a client with changed options.
     #   client.with(:read => { :mode => :primary_preferred })
     #
@@ -381,7 +478,7 @@ module Mongo
     #
     # @since 2.6.0
     def read_concern
-      @read_concern ||= options[:read_concern]
+      options[:read_concern]
     end
 
 
@@ -403,11 +500,15 @@ module Mongo
     # @example Disconnect the client.
     #   client.close
     #
+    # @param [ Boolean ] wait Whether to wait for background threads to
+    #   finish running.
+    #
     # @return [ true ] Always true.
     #
     # @since 2.1.0
-    def close
-      @cluster.disconnect! and true
+    def close(wait=false)
+      @cluster.disconnect!(wait)
+      true
     end
 
     # Reconnect the client.
@@ -420,11 +521,10 @@ module Mongo
     # @since 2.1.0
     def reconnect
       addresses = cluster.addresses.map(&:to_s)
-      monitoring = cluster.monitoring
 
       @cluster.disconnect! rescue nil
 
-      @cluster = Cluster.new(addresses, monitoring, options)
+      @cluster = Cluster.new(addresses, monitoring, cluster_options)
       true
     end
 
@@ -481,6 +581,11 @@ module Mongo
 
     # Start a session.
     #
+    # If the deployment does not support sessions, raises
+    # Mongo::Error::InvalidSession. This exception can also be raised when
+    # the driver is not connected to a data-bearing server, for example
+    # during failover.
+    #
     # @example Start a session.
     #   client.start_session(causal_consistency: true)
     #
@@ -542,6 +647,13 @@ module Mongo
 
     private
 
+    # 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.
+    #
+    # @note This method will return nil if deployment has no data-bearing
+    #   servers at the time of the call.
     def get_session(options = {})
       cluster.send(:get_session, self, options)
     end