mongo 2.15.0 → 2.18.1

data/lib/mongo/server.rb

@@ -54,6 +54,9 @@ module Mongo
     #   done by this server. Note: setting this option to false will make
     #   the server non-functional. It is intended for use in tests which
     #   manually invoke SDAM state transitions.
+    # @option options [ true | false ] :load_balancer Whether this server
+    #   is a load balancer.
+    # @option options [ String ] :connect The client connection mode.
     #
     # @since 2.0.0
     def initialize(address, cluster, monitoring, event_listeners, options = {})
@@ -69,7 +72,10 @@ module Mongo
       end
       @scan_semaphore = DistinguishingSemaphore.new
       @round_trip_time_averager = RoundTripTimeAverager.new
-      @description = Description.new(address, {})
+      @description = Description.new(address, {},
+        load_balancer: !!@options[:load_balancer],
+        force_load_balancer: force_load_balancer?,
+      )
       @last_scan = nil
       @last_scan_monotime = nil
       unless options[:monitoring_io] == false
@@ -107,6 +113,15 @@ module Mongo
     #   description the monitor refreshes.
     attr_reader :description
 
+    # Returns whether this server is forced to be a load balancer.
+    #
+    # @return [ true | false ] Whether this server is forced to be a load balancer.
+    #
+    # @api private
+    def force_load_balancer?
+      options[:connect] == :load_balanced
+    end
+
     # @return [ Time | nil ] last_scan The time when the last server scan
     #   completed, or nil if the server has not been scanned yet.
     #
@@ -180,6 +195,7 @@ module Mongo
                    :secondary?,
                    :standalone?,
                    :unknown?,
+                   :load_balancer?,
                    :last_write_date,
                    :logical_session_timeout
 
@@ -222,20 +238,6 @@ module Mongo
       address == other.address
     end
 
-    # Get a new context for this server in which to send messages.
-    #
-    # @example Get the server context.
-    #   server.context
-    #
-    # @return [ Mongo::Server::Context ] context The server context.
-    #
-    # @since 2.0.0
-    #
-    # @deprecated Will be removed in version 3.0
-    def context
-      Context.new(self)
-    end
-
     # Determine if a connection to the server is able to be established and
     # messages can be sent to it.
     #
@@ -301,13 +303,20 @@ module Mongo
     #
     # @api private
     def start_monitoring
+      publish_opening_event
+      if options[:monitoring_io] != false
+        monitor.run!
+      end
+    end
+
+    # Publishes the server opening event.
+    #
+    # @api private
+    def publish_opening_event
       publish_sdam_event(
         Monitoring::SERVER_OPENING,
         Monitoring::Event::ServerOpening.new(address, cluster.topology)
       )
-      if options[:monitoring_io] != false
-        monitor.run!
-      end
     end
 
     # Get a pretty printed server inspection.
@@ -327,6 +336,8 @@ module Mongo
     # @api private
     def status
       case
+      when load_balancer?
+        'LB'
       when primary?
         'PRIMARY'
       when secondary?
@@ -433,8 +444,8 @@ module Mongo
     # @return [ Object ] The result of the block execution.
     #
     # @since 2.3.0
-    def with_connection(&block)
-      pool.with_connection(&block)
+    def with_connection(connection_global_id: nil, &block)
+      pool.with_connection(connection_global_id: connection_global_id, &block)
     end
 
     # Handle handshake failure.
@@ -444,7 +455,11 @@ module Mongo
     def handle_handshake_failure!
       yield
     rescue Mongo::Error::SocketError, Mongo::Error::SocketTimeoutError => e
-      unknown!(generation: e.generation, stop_push_monitor: true)
+      unknown!(
+        generation: e.generation,
+        service_id: e.service_id,
+        stop_push_monitor: true,
+      )
       raise
     end
 
@@ -467,7 +482,11 @@ module Mongo
       raise
     rescue Mongo::Error::SocketError => e
       # non-timeout network error
-      unknown!(generation: e.generation, stop_push_monitor: true)
+      unknown!(
+        generation: e.generation,
+        service_id: e.service_id,
+        stop_push_monitor: true,
+      )
       raise
     rescue Auth::Unauthorized
       # auth error, keep server description and topology as they are
@@ -492,9 +511,15 @@ module Mongo
     # @note Retryable writes are only available on server versions 3.6+ and with
     #   sharded clusters or replica sets.
     #
+    # @note Some of the conditions in this method automatically return false for
+    #       for load balanced topologies. The conditions in this method should
+    #       always be true, since load-balanced topologies are only available on
+    #       MongoDB 5.0+, and not for standalone topologies. Therefore, we can
+    #       assume that retry writes are enabled.
+    #
     # @since 2.5.0
     def retry_writes?
-      !!(features.sessions_enabled? && logical_session_timeout && !standalone?)
+      !!(features.sessions_enabled? && logical_session_timeout && !standalone?) || load_balancer?
     end
 
     # Marks server unknown and publishes the associated SDAM event
@@ -517,9 +542,27 @@ module Mongo
     #   of the error response that is causing the server to be marked unknown.
     # @option options [ true | false ] :stop_push_monitor Whether to stop
     #   the PushMonitor associated with the server, if any.
+    # @option options [ Object ] :service_id Discard state for the specified
+    #   service id only.
     #
     # @since 2.4.0, SDAM events are sent as of version 2.7.0
     def unknown!(options = {})
+      if load_balancer?
+        # When the client is in load-balanced topology, servers (the one and
+        # only that can be) starts out as a load balancer and stays as a
+        # load balancer indefinitely. As such it is not marked unknown.
+        #
+        # However, this method also clears connection pool for the server
+        # when the latter is marked unknown, and this part needs to happen
+        # when the server is a load balancer.
+        if service_id = options[:service_id]
+          pool.disconnect!(service_id: service_id)
+        elsif Lint.enabled?
+          raise Error::LintError, 'Load balancer was asked to be marked unknown without a service id'
+        end
+        return
+      end
+
       if options[:generation] && options[:generation] < pool.generation
         return
       end
@@ -537,10 +580,16 @@ module Mongo
       # SDAM flow will update description on the server without in-place
       # mutations and invoke SDAM transitions as needed.
       config = {}
+      if options[:service_id]
+        config['serviceId'] = options[:service_id]
+      end
       if options[:topology_version]
         config['topologyVersion'] = options[:topology_version]
       end
-      new_description = Description.new(address, config)
+      new_description = Description.new(address, config,
+        load_balancer: load_balancer?,
+        force_load_balancer: options[:connect] == :load_balanced,
+      )
       cluster.run_sdam_flow(description, new_description, options)
     end
 
@@ -549,11 +598,14 @@ module Mongo
       @description = description
     end
 
+    # @param [ Object ] :service_id Close connections with the specified
+    #   service id only.
+    #
     # @api private
-    def clear_connection_pool
+    def clear_connection_pool(service_id: nil)
       @pool_lock.synchronize do
         if @pool
-          @pool.disconnect!
+          @pool.disconnect!(service_id: service_id)
         end
       end
     end
@@ -577,7 +629,6 @@ require 'mongo/server/connection_base'
 require 'mongo/server/pending_connection'
 require 'mongo/server/connection'
 require 'mongo/server/connection_pool'
-require 'mongo/server/context'
 require 'mongo/server/description'
 require 'mongo/server/monitor'
 require 'mongo/server/round_trip_time_averager'

data/lib/mongo/server_selector/base.rb

@@ -162,6 +162,8 @@ module Mongo
       #   Deprecated and ignored.
       # @param [ Session | nil ] session Optional session to take into account
       #   for mongos pinning. Added in version 2.10.0.
+      # @param [ true | false ] write_aggregation Whether we need a server that
+      #   supports writing aggregations (e.g. with $merge/$out) on secondaries.
       #
       # @return [ Mongo::Server ] A server matching the server preference.
       #
@@ -172,7 +174,11 @@ module Mongo
       #   lint mode is enabled.
       #
       # @since 2.0.0
-      def select_server(cluster, ping = nil, session = nil)
+      def select_server(cluster, ping = nil, session = nil, write_aggregation: false)
+        if cluster.topology.is_a?(Cluster::Topology::LoadBalanced)
+          return cluster.servers.first
+        end
+
         server_selection_timeout = cluster.options[:server_selection_timeout] || SERVER_SELECTION_TIMEOUT
 
         # Special handling for zero timeout: if we have to select a server,
@@ -239,7 +245,7 @@ module Mongo
 =end
 
         loop do
-          server = try_select_server(cluster)
+          server = try_select_server(cluster, write_aggregation: write_aggregation)
 
           if server
             unless cluster.topology.compatible?
@@ -247,7 +253,7 @@ module Mongo
             end
 
             if session && session.starting_transaction? && cluster.sharded?
-              session.pin(server)
+              session.pin_to_server(server)
             end
 
             return server
@@ -290,11 +296,31 @@ module Mongo
       # Tries to find a suitable server, returns the server if one is available
       # or nil if there isn't a suitable server.
       #
+      # @param [ Mongo::Cluster ] cluster The cluster from which to select
+      #   an eligible server.
+      # @param [ true | false ] write_aggregation Whether we need a server that
+      #   supports writing aggregations (e.g. with $merge/$out) on secondaries.
+      #
       # @return [ Server | nil ] A suitable server, if one exists.
       #
       # @api private
-      def try_select_server(cluster)
-        servers = suitable_servers(cluster)
+      def try_select_server(cluster, write_aggregation: false)
+        servers = if write_aggregation && cluster.replica_set?
+          # 1. Check if ALL servers in cluster support secondary writes.
+          is_write_supported = cluster.servers.reduce(true) do |res, server|
+            res && server.features.merge_out_on_secondary_enabled?
+          end
+
+          if is_write_supported
+            # 2. If all servers support secondary writes, we respect read preference.
+            suitable_servers(cluster)
+          else
+            # 3. Otherwise we fallback to primary for replica set.
+            [cluster.servers.detect(&:primary?)]
+          end
+        else
+          suitable_servers(cluster)
+        end
 
         # This list of servers may be ordered in a specific way
         # by the selector (e.g. for secondary preferred, the first

data/lib/mongo/session/session_pool.rb

@@ -99,6 +99,10 @@ module Mongo
       #
       # @since 2.5.0
       def checkin(session)
+        if session.nil?
+          raise ArgumentError, 'session cannot be nil'
+        end
+
         @mutex.synchronize do
           prune!
           unless about_to_expire?(session)
@@ -133,6 +137,17 @@ module Mongo
       private
 
       def about_to_expire?(session)
+        if session.nil?
+          raise ArgumentError, 'session cannot be nil'
+        end
+
+        # Load balancers spec explicitly requires to ignore the logical session
+        # timeout value.
+        # No rationale is provided as of the time of this writing.
+        if @cluster.load_balanced?
+          return false
+        end
+
         logical_session_timeout = @cluster.logical_session_timeout
 
         if logical_session_timeout
@@ -142,6 +157,10 @@ module Mongo
       end
 
       def prune!
+        # Load balancers spec explicitly requires not to prune sessions.
+        # No rationale is provided as of the time of this writing.
+        return if @cluster.load_balanced?
+
         while !@queue.empty?
           if about_to_expire?(@queue[-1])
             @queue.pop

data/lib/mongo/session.rb

@@ -35,12 +35,23 @@ module Mongo
 
     # Initialize a Session.
     #
-    # @note Applications should use Client#start_session to begin a session.
+    # A session can be explicit or implicit. Lifetime of explicit sessions is
+    # managed by the application - applications explicitry create such sessions
+    # and explicitly end them. Implicit sessions are created automatically by
+    # the driver when sending operations to servers that support sessions
+    # (3.6+), and their lifetime is managed by the driver.
+    #
+    # When an implicit session is created, it cannot have a server session
+    # associated with it. The server session will be checked out of the
+    # session pool when an operation using this session is actually executed.
+    # When an explicit session is created, it must reference a server session
+    # that is already allocated.
     #
-    # @example
-    #   Session.new(server_session, client, options)
+    # @note Applications should use Client#start_session to begin a session.
+    #   This constructor is for internal driver use only.
     #
-    # @param [ ServerSession ] server_session The server session this session is associated with.
+    # @param [ ServerSession | nil ] server_session The server session this session is associated with.
+    #   If the :implicit option is true, this must be nil.
     # @param [ Client ] client The client through which this session is created.
     # @param [ Hash ] options The options for this session.
     #
@@ -50,21 +61,39 @@ module Mongo
     #   to start_transaction by default, can contain any of the options that
     #   start_transaction accepts.
     # @option options [ true|false ] :implicit For internal driver use only -
-    #   specifies whether the session is implicit.
+    #   specifies whether the session is implicit. If this is true, the server_session
+    #   will be nil. This is done so that the server session is only checked
+    #   out after the connection is checked out.
     # @option options [ Hash ] :read_preference The read preference options hash,
     #   with the following optional keys:
     #   - *:mode* -- the read preference as a string or symbol; valid values are
     #     *:primary*, *:primary_preferred*, *:secondary*, *:secondary_preferred*
     #     and *:nearest*.
+    # @option options [ true | false ] :snapshot Set up the session for
+    #   snapshot reads.
     #
     # @since 2.5.0
     # @api private
     def initialize(server_session, client, options = {})
+      if options[:causal_consistency] && options[:snapshot]
+        raise ArgumentError, ':causal_consistency and :snapshot options cannot be both set on a session'
+      end
+
+      if options[:implicit]
+        unless server_session.nil?
+          raise ArgumentError, 'Implicit session cannot reference server session during construction'
+        end
+      else
+        if server_session.nil?
+          raise ArgumentError, 'Explicit session must reference server session during construction'
+        end
+      end
+
       @server_session = server_session
       options = options.dup
 
       @client = client.use(:admin)
-      @options = options.freeze
+      @options = options.dup.freeze
       @cluster_time = nil
       @state = NO_TRANSACTION_STATE
     end
@@ -83,6 +112,12 @@ module Mongo
       @client.cluster
     end
 
+    # @return [ true | false ] Whether the session is configured for snapshot
+    #   reads.
+    def snapshot?
+      !!options[:snapshot]
+    end
+
     # @return [ BSON::Timestamp ] The latest seen operation time for this session.
     #
     # @since 2.5.0
@@ -148,11 +183,11 @@ module Mongo
     # @return [ true, false ] If writes will be retried.
     #
     # @note Retryable writes are only available on server versions at least 3.6
-    #   and with sharded clusters or replica sets.
+    #   and with sharded clusters, replica sets, or load-balanced topologies.
     #
     # @since 2.5.0
     def retry_writes?
-      !!client.options[:retry_writes] && (cluster.replica_set? || cluster.sharded?)
+      !!client.options[:retry_writes] && (cluster.replica_set? || cluster.sharded? || cluster.load_balanced?)
     end
 
     # Get the read preference the session will use in the currently
@@ -182,23 +217,33 @@ module Mongo
     #
     # @since 2.5.0
     def ended?
-      @server_session.nil?
+      !!@ended
     end
 
-    # Get the server session id of this session, if the session was not ended.
-    # If the session was ended, returns nil.
-    #
-    # @example Get the session id.
-    #   session.session_id
+    # Get the server session id of this session, if the session has not been
+    # ended. If the session had been ended, raises Error::SessionEnded.
     #
     # @return [ BSON::Document ] The server session id.
     #
+    # @raise [ Error::SessionEnded ] If the session had been ended.
+    #
     # @since 2.5.0
     def session_id
       if ended?
         raise Error::SessionEnded
       end
 
+      # An explicit session will always have a session_id, because during
+      # construction a server session must be provided. An implicit session
+      # will not have a session_id until materialized, thus calls to
+      # session_id might fail. An application should not have an opportunity
+      # to experience this failure because an implicit session shouldn't be
+      # accessible to applications due to its lifetime being constrained to
+      # operation execution, which is done entirely by the driver.
+      unless materialized?
+        raise Error::SessionNotMaterialized
+      end
+
       @server_session.session_id
     end
 
@@ -208,6 +253,12 @@ module Mongo
     # @api private
     attr_reader :pinned_server
 
+    # @return [ Integer | nil ] The connection global id that this session is pinned to,
+    #   if any.
+    #
+    # @api private
+    attr_reader :pinned_connection_global_id
+
     # @return [ BSON::Document | nil ] Recovery token for the sharded
     #   transaction being executed on this session, if any.
     #
@@ -307,10 +358,13 @@ module Mongo
           rescue Mongo::Error, Error::AuthError
           end
         end
-        @client.cluster.session_pool.checkin(@server_session)
+        if @server_session
+          @client.cluster.session_pool.checkin(@server_session)
+        end
       end
     ensure
       @server_session = nil
+      @ended = true
     end
 
     # Executes the provided block in a transaction, retrying as necessary.
@@ -430,6 +484,7 @@ module Mongo
                 transaction_in_progress = false
                 raise
               end
+              @state = NO_TRANSACTION_STATE
               next
             else
               transaction_in_progress = false
@@ -499,6 +554,10 @@ module Mongo
 =end
       end
 
+      if snapshot?
+        raise Mongo::Error::SnapshotSessionTransactionProhibited
+      end
+
       check_if_ended!
 
       if within_states?(STARTING_TRANSACTION_STATE, TRANSACTION_IN_PROGRESS_STATE)
@@ -568,8 +627,12 @@ module Mongo
           if write_concern && !write_concern.is_a?(WriteConcern::Base)
             write_concern = WriteConcern.get(write_concern)
           end
-          write_with_retry(self, write_concern, true) do |server, txn_num, is_retry|
-            if is_retry
+
+          context = Operation::Context.new(client: @client, session: self)
+          write_with_retry(write_concern, ending_transaction: true,
+            context: context,
+          ) do |connection, txn_num, context|
+            if context.retry?
               if write_concern
                 wco = write_concern.options.merge(w: :majority)
                 wco[:wtimeout] ||= 10000
@@ -585,7 +648,7 @@ module Mongo
               txn_num: txn_num,
               write_concern: write_concern,
             }
-            Operation::Command.new(spec).execute(server, context: Operation::Context.new(client: @client, session: self))
+            Operation::Command.new(spec).execute_with_connection(connection, context: context)
           end
         end
       ensure
@@ -626,14 +689,17 @@ module Mongo
       begin
         unless starting_transaction?
           @aborting_transaction = true
-          write_with_retry(self, txn_options[:write_concern], true) do |server, txn_num|
+          context = Operation::Context.new(client: @client, session: self)
+          write_with_retry(txn_options[:write_concern],
+            ending_transaction: true, context: context,
+          ) do |connection, txn_num, context|
             begin
               Operation::Command.new(
                 selector: { abortTransaction: 1 },
                 db_name: 'admin',
                 session: self,
                 txn_num: txn_num
-              ).execute(server, context: Operation::Context.new(client: @client, session: self))
+              ).execute_with_connection(connection, context: context)
             ensure
               unpin
             end
@@ -695,7 +761,7 @@ module Mongo
     # @param [ Server ] server The server to pin this session to.
     #
     # @api private
-    def pin(server)
+    def pin_to_server(server)
       if server.nil?
         raise ArgumentError, 'Cannot pin to a nil server'
       end
@@ -707,14 +773,32 @@ module Mongo
       @pinned_server = server
     end
 
-    # Unpins this session from the pinned server, if the session was pinned.
+    # Pins this session to the specified connection.
+    #
+    # @param [ Integer ] connection_global_id The global id of connection to pin
+    # this session to.
     #
     # @api private
-    def unpin
+    def pin_to_connection(connection_global_id)
+      if connection_global_id.nil?
+        raise ArgumentError, 'Cannot pin to a nil connection id'
+      end
+      @pinned_connection_global_id = connection_global_id
+    end
+
+    # Unpins this session from the pinned server or connection,
+    # if the session was pinned.
+    #
+    # @param [ Connection | nil ] connection Connection to unpin from.
+    #
+    # @api private
+    def unpin(connection = nil)
       @pinned_server = nil
+      @pinned_connection_global_id = nil
+      connection.unpin unless connection.nil?
     end
 
-    # Unpins this session from the pinned server, if the session was pinned
+    # Unpins this session from the pinned server or connection, if the session was pinned
     # and the specified exception instance and the session's transaction state
     # require it to be unpinned.
     #
@@ -722,19 +806,20 @@ module Mongo
     # (both client- and server-side generated ones).
     #
     # @param [ Error ] error The exception instance to process.
+    # @param [ Connection | nil ] connection Connection to unpin from.
     #
     # @api private
-    def unpin_maybe(error)
+    def unpin_maybe(error, connection = nil)
       if !within_states?(Session::NO_TRANSACTION_STATE) &&
         error.label?('TransientTransactionError')
       then
-        unpin
+        unpin(connection)
       end
 
       if committing_transaction? &&
         error.label?('UnknownTransactionCommitResult')
       then
-        unpin
+        unpin(connection)
       end
     end
 
@@ -971,6 +1056,33 @@ module Mongo
       end
     end
 
+    # If not already set, populate a session objects's server_session by
+    # checking out a session from the session pool.
+    #
+    # @return [ Session ] Self.
+    #
+    # @api private
+    def materialize_if_needed
+      if ended?
+        raise Error::SessionEnded
+      end
+
+      return unless implicit? && !@server_session
+
+      @server_session = cluster.session_pool.checkout
+
+      self
+    end
+
+    # @api private
+    def materialized?
+      if ended?
+        raise Error::SessionEnded
+      end
+
+      !@server_session.nil?
+    end
+
     # Increment and return the next transaction number.
     #
     # @example Get the next transaction number.
@@ -1004,6 +1116,9 @@ module Mongo
       @server_session.txn_num
     end
 
+    # @api private
+    attr_accessor :snapshot_timestamp
+
     private
 
     # Get the read concern the session will use when starting a transaction.

data/lib/mongo/socket/ocsp_cache.rb

@@ -21,8 +21,7 @@ module Mongo
     # This module caches OCSP responses for their indicated validity time.
     #
     # The key is the CertificateId used for the OCSP request.
-    # The value is the SingleResponse on Ruby 2.4+, or the OpenStruct
-    # emulation of it on Ruby 2.3.
+    # The value is the SingleResponse.
     #
     # @api private
     module OcspCache
@@ -40,7 +39,7 @@ module Mongo
       # expire by the time caller uses them. The caller should not perform
       # update time checks on the returned response.
       #
-      # @return [ OpenSSL::OCSP::SingleResponse | OpenStruct ] The previously
+      # @return [ OpenSSL::OCSP::SingleResponse ] The previously
       #   retrieved response.
       module_function def get(cert_id)
         resp = responses.detect do |resp|