mongo 2.9.2 → 2.10.0.rc0

data/lib/mongo/cluster.rb

@@ -28,6 +28,7 @@ module Mongo
     include Monitoring::Publishable
     include Event::Subscriber
     include Loggable
+    include ClusterTime::Consumer
 
     # The default number of legacy read retries.
     #
@@ -53,6 +54,7 @@ module Mongo
     # The cluster time key in responses from mongos servers.
     #
     # @since 2.5.0
+    # @deprecated
     CLUSTER_TIME = 'clusterTime'.freeze
 
     # Instantiate the new cluster.
@@ -74,18 +76,23 @@ module Mongo
     # @param [ Hash ] options Options. Client constructor forwards its
     #   options to Cluster constructor, although Cluster recognizes
     #   only a subset of the options recognized by Client.
-    # @option options [ true, false ] :scan Whether to scan all seeds
+    # @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 [ true, false ] :monitoring_io For internal driver
+    # @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 cluster or servers under it. Note: setting this option
     #   to false will make the cluster non-functional. It is intended for
     #   use in tests which manually invoke SDAM state transitions.
+    # @option options [ true | false ] :cleanup For internal driver use only.
+    #   Set to false to prevent endSessions command being sent to the server
+    #   to clean up server sessions when the cluster is disconnected, and to
+    #   to not start the periodic executor. If :monitoring_io is false,
+    #   :cleanup automatically defaults to false as well.
     #
     # @since 2.0.0
     def initialize(seeds, monitoring, options = Options::Redacted.new)
@@ -93,6 +100,11 @@ module Mongo
         raise ArgumentError, 'Need server selection semaphore'
       end
 
+      if options[:monitoring_io] == false && !options.key?(:cleanup)
+        options = options.dup
+        options[:cleanup] = false
+      end
+
       @servers = []
       @monitoring = monitoring
       @event_listeners = Event::Listeners.new
@@ -148,12 +160,14 @@ module Mongo
         return
       end
 
-      @cursor_reaper = CursorReaper.new
-      @socket_reaper = SocketReaper.new(self)
-      @periodic_executor = PeriodicExecutor.new(@cursor_reaper, @socket_reaper)
-      @periodic_executor.run!
+      if options[:cleanup] != false
+        @cursor_reaper = CursorReaper.new
+        @socket_reaper = SocketReaper.new(self)
+        @periodic_executor = PeriodicExecutor.new(@cursor_reaper, @socket_reaper)
+        @periodic_executor.run!
 
-      ObjectSpace.define_finalizer(self, self.class.finalize({}, @periodic_executor, @session_pool))
+        ObjectSpace.define_finalizer(self, self.class.finalize({}, @periodic_executor, @session_pool))
+      end
 
       @connecting = false
       @connected = true
@@ -225,11 +239,6 @@ module Mongo
     # @since 2.4.0
     attr_reader :app_metadata
 
-    # @return [ BSON::Document ] The latest cluster time seen.
-    #
-    # @since 2.5.0
-    attr_reader :cluster_time
-
     # @return [ Array<String> ] The addresses of seed servers. Contains
     #   addresses that were given to Cluster when it was instantiated, not
     #   current addresses that the cluster is using as a result of SDAM.
@@ -245,7 +254,14 @@ module Mongo
 
     def_delegators :topology, :replica_set?, :replica_set_name, :sharded?,
                    :single?, :unknown?
-    def_delegators :@cursor_reaper, :register_cursor, :schedule_kill_cursor, :unregister_cursor
+
+    [:register_cursor, :schedule_kill_cursor, :unregister_cursor].each do |m|
+      define_method(m) do |*args|
+        if options[:cleanup] != false
+          @cursor_reaper.send(m, *args)
+        end
+      end
+    end
 
     # Get the maximum number of times the client can retry a read operation
     # when using legacy read retries.
@@ -393,7 +409,12 @@ module Mongo
       unless @connecting || @connected
         return true
       end
-      @periodic_executor.stop!
+      if options[:cleanup] != false
+        if wait
+          session_pool.end_sessions
+        end
+        @periodic_executor.stop!(wait)
+      end
       @servers.each do |server|
         if server.connected?
           server.disconnect!(wait)
@@ -519,16 +540,16 @@ module Mongo
     # @example Get the next primary server.
     #   cluster.next_primary
     #
-    # @param [ true, false ] ping Whether to ping the server before selection. Deprecated,
-    #   not necessary with the implementation of the Server Selection specification.
-    #
+    # @param [ true, false ] ping Whether to ping the server before selection.
+    #   Deprecated and ignored.
+    # @param [ Session | nil ] session Optional session to take into account
+    #   for mongos pinning.
     #
     # @return [ Mongo::Server ] A primary server.
     #
     # @since 2.0.0
-    def next_primary(ping = true)
-      @primary_selector ||= ServerSelector.get(ServerSelector::PRIMARY)
-      @primary_selector.select_server(self)
+    def next_primary(ping = nil, session = nil)
+      ServerSelector.primary.select_server(self, nil, session)
     end
 
     # Get the connection pool for the server.
@@ -559,11 +580,7 @@ module Mongo
     def update_cluster_time(result)
       if cluster_time_doc = result.cluster_time
         @cluster_time_lock.synchronize do
-          if @cluster_time.nil?
-            @cluster_time = cluster_time_doc
-          elsif cluster_time_doc[CLUSTER_TIME] > @cluster_time[CLUSTER_TIME]
-            @cluster_time = cluster_time_doc
-          end
+          advance_cluster_time(cluster_time_doc)
         end
       end
     end
@@ -670,6 +687,11 @@ module Mongo
     # @note If the cluster has no data bearing servers, for example because
     #   the deployment is in the middle of a failover, this method returns
     #   false.
+    #
+    # @note This method returns as soon as the driver connects to any single
+    #   server in the deployment. Whether deployment overall supports sessions
+    #   can change depending on how many servers have been contacted, if
+    #   the servers are configured differently.
     def sessions_supported?
       if topology.data_bearing_servers?
         return !!topology.logical_session_timeout

data/lib/mongo/cluster/topology/replica_set_no_primary.rb

@@ -74,7 +74,7 @@ module Mongo
         #
         # @since 2.4.0
         def has_readable_server?(cluster, server_selector = nil)
-          (server_selector || ServerSelector.get(mode: :primary)).candidates(cluster).any?
+          (server_selector || ServerSelector.primary).candidates(cluster).any?
         end
 
         # Determine if the topology would select a writable server for the

data/lib/mongo/cluster_time.rb

@@ -0,0 +1,139 @@
+# Copyright (C) 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.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Mongo
+  # ClusterTime encapsulates cluster time storage and operations.
+  #
+  # The primary operation performed on the cluster time is advancing it:
+  # given another cluster time, pick the newer of the two.
+  #
+  # This class provides comparison methods that are used to figure out which
+  # cluster time is newer, and provides diagnostics in lint mode when
+  # the actual time is missing from a cluster time document.
+  #
+  # @api private
+  class ClusterTime < BSON::Document
+    def initialize(elements = nil)
+      super
+
+      if Lint.enabled? && !self['clusterTime']
+        raise ArgumentError, 'Creating a cluster time without clusterTime field'
+      end
+    end
+
+    # Advances the cluster time in the receiver to the cluster time in +other+.
+    #
+    # +other+ can be nil or be behind the cluster time in the receiver; in
+    # these cases the receiver is returned unmodified. If receiver is advanced,
+    # a new ClusterTime object is returned.
+    #
+    # Return value is nil or a ClusterTime instance.
+    def advance(other)
+      if self['clusterTime'] && other['clusterTime'] &&
+        other['clusterTime'] > self['clusterTime']
+      then
+        ClusterTime[other]
+      else
+        self
+      end
+    end
+
+    # Compares two ClusterTime instances by comparing their timestamps.
+    def <=>(other)
+      if self['clusterTime'] && other['clusterTime']
+        self['clusterTime'] <=> other['clusterTime']
+      elsif !self['clusterTime']
+        raise ArgumentError, "Cannot compare cluster times when receiver is missing clusterTime key: #{inspect}"
+      else other['clusterTime']
+        raise ArgumentError, "Cannot compare cluster times when other is missing clusterTime key: #{other.inspect}"
+      end
+    end
+
+    # Older Rubies do not implement other logical operators through <=>.
+    # TODO revise whether these methods are needed when
+    # https://jira.mongodb.org/browse/RUBY-1622 is implemented.
+    def >=(other)
+      (self <=> other) != -1
+    end
+    def >(other)
+      (self <=> other) == 1
+    end
+    def <=(other)
+      (self <=> other) != 1
+    end
+    def <(other)
+      (self <=> other) == -1
+    end
+
+    # Compares two ClusterTime instances by comparing their timestamps.
+    def ==(other)
+      if self['clusterTime'] && other['clusterTime'] &&
+        self['clusterTime'] == other['clusterTime']
+      then
+        true
+      else
+        false
+      end
+    end
+
+    class << self
+      # Converts a BSON::Document to a ClusterTime.
+      #
+      # +doc+ can be nil, in which case nil is returned.
+      def [](doc)
+        if doc.nil? || doc.is_a?(ClusterTime)
+          doc
+        else
+          ClusterTime.new(doc)
+        end
+      end
+    end
+
+    # This module provides common cluster time tracking behavior.
+    #
+    # @note Although attributes and methods defined in this module are part of
+    #   the public API for the classes including this module, the fact that
+    #   the methods are defined on this module and not directly on the
+    #   including classes is not part of the public API.
+    module Consumer
+
+      # The cluster time tracked by the object including this module.
+      #
+      # @return [ nil | ClusterTime ] The cluster time.
+      #
+      # Changed in version 2.9.0: This attribute became an instance of
+      # ClusterTime, which is a subclass of BSON::Document.
+      # Previously it was an instance of BSON::Document.
+      #
+      # @since 2.5.0
+      attr_reader :cluster_time
+
+      # Advance the tracked cluster time document for the object including
+      # this module.
+      #
+      # @param [ BSON::Document ] new_cluster_time The new cluster time document.
+      #
+      # @return [ ClusterTime ] The resulting cluster time.
+      #
+      # @since 2.5.0
+      def advance_cluster_time(new_cluster_time)
+        if @cluster_time
+          @cluster_time = @cluster_time.advance(new_cluster_time)
+        else
+          @cluster_time = ClusterTime[new_cluster_time]
+        end
+      end
+    end
+  end
+end

data/lib/mongo/collection.rb

@@ -53,7 +53,7 @@ module Mongo
     # Options that can be updated on a new Collection instance via the #with method.
     #
     # @since 2.1.0
-    CHANGEABLE_OPTIONS = [ :read, :read_concern, :write ].freeze
+    CHANGEABLE_OPTIONS = [ :read, :read_concern, :write, :write_concern ].freeze
 
     # Check if a collection is equal to another object. Will check the name and
     # the database for equality.
@@ -80,12 +80,28 @@ module Mongo
     # @param [ String, Symbol ] name The collection name.
     # @param [ Hash ] options The collection options.
     #
+    # @option options [ Hash ] :write Deprecated. Equivalent to :write_concern
+    #   option.
+    # @option options [ Hash ] :write_concern The write concern options.
+    #   Can be :w => Integer|String, :fsync => Boolean, :j => Boolean.
+    #
     # @since 2.0.0
     def initialize(database, name, options = {})
       raise Error::InvalidCollectionName.new unless name
+      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
       @database = database
       @name = name.to_s.freeze
-      @options = options.freeze
+      @options = options.dup
+=begin WriteConcern object support
+      if @options[:write_concern].is_a?(WriteConcern::Base)
+        # Cache the instance so that we do not needlessly reconstruct it.
+        @write_concern = @options[:write_concern]
+        @options[:write_concern] = @write_concern.options
+      end
+=end
+      @options.freeze
     end
 
     # Get the read concern for this collection instance.
@@ -133,17 +149,40 @@ module Mongo
     #
     # @since 2.0.0
     def write_concern
-      @write_concern ||= WriteConcern.get(options[:write] || database.write_concern)
+      @write_concern ||= WriteConcern.get(
+        options[:write_concern] || options[:write] || database.write_concern)
+    end
+
+    # Get the write concern for the collection, given the session.
+    #
+    # If the session is in a transaction and the collection
+    # has an unacknowledged write concern, remove the write
+    # concern's :w option. Otherwise, return the unmodified
+    # write concern.
+    #
+    # @return [ Mongo::WriteConcern ] The write concern.
+    #
+    # @api private
+    def write_concern_with_session(session)
+      wc = write_concern
+      if session && session.in_transaction?
+        if wc && !wc.acknowledged?
+          opts = wc.options.dup
+          opts.delete(:w)
+          return WriteConcern.get(opts)
+        end
+      end
+      wc
     end
 
     # Provides a new collection with either a new read preference or new write concern
     # merged over the existing read preference / write concern.
     #
-    # @example Get a collection with changed read preference.
-    #   collection.with(:read => { :mode => :primary_preferred })
+    # @example Get a collection with a changed read preference.
+    #   collection.with(read: { mode: :primary_preferred })
     #
-    # @example Get a collection with changed write concern.
-    #   collection.with(:write => { w:  3 })
+    # @example Get a collection with a changed write concern.
+    #   collection.with(write_concern: { w:  3 })
 
     # @param [ Hash ] new_options The new options to use.
     #
@@ -154,7 +193,14 @@ module Mongo
       new_options.keys.each do |k|
         raise Error::UnchangeableCollectionOption.new(k) unless CHANGEABLE_OPTIONS.include?(k)
       end
-      Collection.new(database, name, options.merge(new_options))
+      options = @options.dup
+      if options[:write] && new_options[:write_concern]
+        options.delete(:write)
+      end
+      if options[:write_concern] && new_options[:write]
+        options.delete(:write_concern)
+      end
+      Collection.new(database, name, options.update(new_options))
     end
 
     # Is the collection capped?
@@ -166,7 +212,7 @@ module Mongo
     #
     # @since 2.0.0
     def capped?
-      database.read_command(:collstats => name).documents[0][CAPPED]
+      database.command(:collstats => name).documents[0][CAPPED]
     end
 
     # Force the collection to be created in the database.
@@ -182,13 +228,22 @@ module Mongo
     #
     # @since 2.0.0
     def create(opts = {})
+      # Passing read options to create command causes it to break.
+      # Filter the read options out.
+      # TODO put the list of read options in a class-level constant when
+      # we figure out what the full set of them is.
+      options = Hash[self.options.reject do |key, value|
+        %w(read read_preference).include?(key.to_s)
+      end]
       operation = { :create => name }.merge(options)
       operation.delete(:write)
-      server = next_primary
-      if (options[:collation] || options[Operation::COLLATION]) && !server.features.collation_enabled?
-        raise Error::UnsupportedCollation.new
-      end
+      operation.delete(:write_concern)
       client.send(:with_session, opts) do |session|
+        server = next_primary(nil, session)
+        if (options[:collation] || options[Operation::COLLATION]) && !server.features.collation_enabled?
+          raise Error::UnsupportedCollation
+        end
+
         Operation::Create.new({
                                 selector: operation,
                                 db_name: database.name,
@@ -220,7 +275,7 @@ module Mongo
                               db_name: database.name,
                               write_concern: write_concern,
                               session: session
-                              }).execute(next_primary)
+                              }).execute(next_primary(nil, session))
       end
     rescue Error::OperationFailure => ex
       raise ex unless ex.message =~ /ns not found/
@@ -277,18 +332,21 @@ module Mongo
     # @param [ Array<Hash> ] pipeline The aggregation pipeline.
     # @param [ Hash ] options The aggregation options.
     #
-    # @option options [ true, false ] :allow_disk_use Set to true if disk usage is allowed during
-    #   the aggregation.
-    # @option options [ Integer ] :batch_size The number of documents to return per batch.
-    # @option options [ Integer ] :max_time_ms The maximum amount of time in milliseconds to allow the
-    #   aggregation to run.
-    # @option options [ true, false ] :use_cursor Indicates whether the command will request that the server
-    #   provide results using a cursor. Note that as of server version 3.6, aggregations always provide results
-    #   using a cursor and this option is therefore not valid.
+    # @option options [ true, false ] :allow_disk_use Set to true if disk
+    #   usage is allowed during the aggregation.
+    # @option options [ Integer ] :batch_size The number of documents to return
+    #   per batch.
     # @option options [ true, false ] :bypass_document_validation Whether or
     #   not to skip document level validation.
     # @option options [ Hash ] :collation The collation to use.
     # @option options [ String ] :comment Associate a comment with the aggregation.
+    # @option options [ String ] :hint The index to use for the aggregation.
+    # @option options [ Integer ] :max_time_ms The maximum amount of time in
+    #   milliseconds to allow the aggregation to run.
+    # @option options [ true, false ] :use_cursor Indicates whether the command
+    #   will request that the server provide results using a cursor. Note that
+    #   as of server version 3.6, aggregations always provide results using a
+    #   cursor and this option is therefore not valid.
     # @option options [ Session ] :session The session to use.
     #
     # @return [ Aggregation ] The aggregation object.
@@ -475,6 +533,7 @@ module Mongo
     # @since 2.0.0
     def insert_one(document, opts = {})
       client.send(:with_session, opts) do |session|
+        write_concern = write_concern_with_session(session)
         write_with_retry(session, write_concern) do |server, txn_num|
           Operation::Insert.new(
               :documents => [ document ],
@@ -620,7 +679,7 @@ module Mongo
     #   collection.update_many({ name: 'test'}, '$set' => { name: 'test1' })
     #
     # @param [ Hash ] filter The filter to use.
-    # @param [ Hash ] update The update statement.
+    # @param [ Hash | Array<Hash> ] update The update document or pipeline.
     # @param [ Hash ] options The options.
     #
     # @option options [ true, false ] :upsert Whether to upsert if the
@@ -645,7 +704,7 @@ module Mongo
     #   collection.update_one({ name: 'test'}, '$set' => { name: 'test1'})
     #
     # @param [ Hash ] filter The filter to use.
-    # @param [ Hash ] update The update statement.
+    # @param [ Hash | Array<Hash> ] update The update document or pipeline.
     # @param [ Hash ] options The options.
     #
     # @option options [ true, false ] :upsert Whether to upsert if the
@@ -700,7 +759,7 @@ module Mongo
     #   collection.find_one_and_update({ name: 'test' }, { "$set" => { name: 'test1' }}, :return_document => :after)
     #
     # @param [ Hash ] filter The filter to use.
-    # @param [ BSON::Document ] update The update statement.
+    # @param [ Hash | Array<Hash> ] update The update document or pipeline.
     # @param [ Hash ] options The options.
     #
     # @option options [ Integer ] :max_time_ms The maximum amount of time to allow the command