mongo 2.16.4 → 2.20.0

data/lib/mongo/server_selector/primary.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #

data/lib/mongo/server_selector/primary_preferred.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #

data/lib/mongo/server_selector/secondary.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #

data/lib/mongo/server_selector/secondary_preferred.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #

data/lib/mongo/server_selector.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #

data/lib/mongo/session/server_session/dirtyable.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2024 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
+  class Session
+    class ServerSession
+      # Functionality for manipulating and querying a session's
+      # "dirty" state, per the last paragraph at
+      # https://github.com/mongodb/specifications/blob/master/source/sessions/driver-sessions.rst#server-session-pool
+      #
+      #   If a driver has a server session pool and a network error is
+      #   encountered when executing any command with a ClientSession, the
+      #   driver MUST mark the associated ServerSession as dirty. Dirty server
+      #   sessions are discarded when returned to the server session pool. It is
+      #   valid for a dirty session to be used for subsequent commands (e.g. an
+      #   implicit retry attempt, a later command in a bulk write, or a later
+      #   operation on an explicit session), however, it MUST remain dirty for
+      #   the remainder of its lifetime regardless if later commands succeed.
+      #
+      # @api private
+      module Dirtyable
+        # Query whether the server session has been marked dirty or not.
+        #
+        # @return [ true | false ] the server session's dirty state
+        def dirty?
+          @dirty
+        end
+
+        # Mark the server session as dirty (the default) or clean.
+        #
+        # @param [ true | false ] mark whether the mark the server session
+        #   dirty or not.
+        def dirty!(mark = true)
+          @dirty = mark
+        end
+      end
+    end
+  end
+end

data/lib/mongo/session/server_session.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2017-2020 MongoDB Inc.
 #
@@ -15,6 +15,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require 'mongo/session/server_session/dirtyable'
+
 module Mongo
 
   class Session
@@ -25,6 +27,7 @@ module Mongo
     #
     # @since 2.5.0
     class ServerSession
+      include Dirtyable
 
       # Regex for removing dashes from the UUID string.
       #

data/lib/mongo/session/session_pool.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2017-2020 MongoDB Inc.
 #
@@ -25,21 +25,6 @@ module Mongo
     #
     # @since 2.5.0
     class SessionPool
-
-      # Create a SessionPool.
-      #
-      # @example
-      #   SessionPool.create(cluster)
-      #
-      # @param [ Mongo::Cluster ] cluster The cluster that will be associated with this
-      #   session pool.
-      #
-      # @since 2.5.0
-      def self.create(cluster)
-        pool = new(cluster)
-        cluster.instance_variable_set(:@session_pool, pool)
-      end
-
       # Initialize a SessionPool.
       #
       # @example
@@ -99,11 +84,13 @@ 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)
-            @queue.unshift(session)
-          end
+          @queue.unshift(session) if return_to_queue?(session)
         end
       end
 
@@ -132,7 +119,22 @@ module Mongo
 
       private
 
+      # Query whether the given session is okay to return to the
+      # pool's queue.
+      #
+      # @param [ Session::ServerSession ] session the session to query
+      #
+      # @return [ true | false ] whether to return the session to the
+      #   queue.
+      def return_to_queue?(session)
+        !session.dirty? && !about_to_expire?(session)
+      end
+
       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.

data/lib/mongo/session.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2017-2020 MongoDB Inc.
 #
@@ -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.
     #
-    # @example
-    #   Session.new(server_session, client, options)
+    # 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.
+    #
+    # @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,11 +112,34 @@ 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
     attr_reader :operation_time
 
+    # Sets the dirty state to the given value for the underlying server
+    # session. If there is no server session, this does nothing.
+    #
+    # @param [ true | false ] mark whether to mark the server session as
+    #   dirty, or not.
+    def dirty!(mark = true)
+      @server_session&.dirty!(mark)
+    end
+
+    # @return [ true | false | nil ] whether the underlying server session is
+    #   dirty. If no server session exists for this session, returns nil.
+    #
+    # @api private
+    def dirty?
+      @server_session&.dirty?
+    end
+
     # @return [ Hash ] The options for the transaction currently being executed
     # on this session.
     #
@@ -148,11 +200,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 +234,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,11 +270,11 @@ module Mongo
     # @api private
     attr_reader :pinned_server
 
-    # @return [ Object | nil ] The service id that this session is pinned to,
+    # @return [ Integer | nil ] The connection global id that this session is pinned to,
     #   if any.
     #
     # @api private
-    attr_reader :pinned_service_id
+    attr_reader :pinned_connection_global_id
 
     # @return [ BSON::Document | nil ] Recovery token for the sharded
     #   transaction being executed on this session, if any.
@@ -313,10 +375,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.
@@ -474,7 +539,7 @@ module Mongo
     #
     # @option options [ Integer ] :max_commit_time_ms The maximum amount of
     #   time to allow a single commitTransaction command to run, in milliseconds.
-    # @option options [ Hash ] read_concern The read concern options hash,
+    # @option options [ Hash ] :read_concern The read concern options hash,
     #   with the following optional keys:
     #   - *:level* -- the read preference level as a symbol; valid values
     #      are *:local*, *:majority*, and *:snapshot*
@@ -490,6 +555,8 @@ module Mongo
     #
     # @since 2.6.0
     def start_transaction(options = nil)
+      check_transactions_supported!
+
       if options
         Lint.validate_read_concern_option(options[:read_concern])
 
@@ -506,6 +573,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)
@@ -575,8 +646,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
@@ -592,7 +667,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
@@ -633,14 +708,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
@@ -714,27 +792,32 @@ module Mongo
       @pinned_server = server
     end
 
-    # Pins this session to the specified service.
+    # Pins this session to the specified connection.
     #
-    # @param [ Object ] service_id The service id to pin this session to.
+    # @param [ Integer ] connection_global_id The global id of connection to pin
+    # this session to.
     #
     # @api private
-    def pin_to_service(service_id)
-      if service_id.nil?
-        raise ArgumentError, 'Cannot pin to a nil service id'
+    def pin_to_connection(connection_global_id)
+      if connection_global_id.nil?
+        raise ArgumentError, 'Cannot pin to a nil connection id'
       end
-      @pinned_service_id = service_id
+      @pinned_connection_global_id = connection_global_id
     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.
+    #
+    # @param [ Connection | nil ] connection Connection to unpin from.
     #
     # @api private
-    def unpin
+    def unpin(connection = nil)
       @pinned_server = nil
-      @pinned_service_id = 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.
     #
@@ -742,19 +825,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
 
@@ -991,6 +1075,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.
@@ -1024,6 +1135,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.
@@ -1090,5 +1204,18 @@ module Mongo
         raise Mongo::Error::InvalidSession.new(MISMATCHED_CLUSTER_ERROR_MSG)
       end
     end
+
+    def check_transactions_supported!
+      raise Mongo::Error::TransactionsNotSupported, "standalone topology" if cluster.single?
+
+      cluster.next_primary.with_connection do |conn|
+        if cluster.replica_set? && !conn.features.transactions_enabled?
+          raise Mongo::Error::TransactionsNotSupported, "server version is < 4.0"
+        end
+        if cluster.sharded? && !conn.features.sharded_transactions_enabled?
+          raise Mongo::Error::TransactionsNotSupported, "sharded transactions require server version >= 4.2"
+        end
+      end
+    end
   end
 end

data/lib/mongo/socket/ocsp_cache.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2020 MongoDB Inc.
 #
@@ -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|

data/lib/mongo/socket/ocsp_verifier.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2020 MongoDB Inc.
 #
@@ -238,6 +238,10 @@ module Mongo
         end
 
         resp = resp.find_response(cert_id)
+        unless resp
+          @resp_errors << "OCSP response from #{report_uri(original_uri, uri)} did not include information about the requested certificate"
+          return false
+        end
         # TODO make a new class instead of patching the stdlib one?
         resp.instance_variable_set('@uri', uri)
         resp.instance_variable_set('@original_uri', original_uri)
@@ -245,11 +249,6 @@ module Mongo
           attr_reader :uri, :original_uri
         end
 
-        unless resp
-          @resp_errors << "OCSP response from #{report_uri(original_uri, uri)} did not include information about the requested certificate"
-          return false
-        end
-
         unless resp.check_validity
           @resp_errors << "OCSP response from #{report_uri(original_uri, uri)} was invalid: this_update was in the future or next_update time has passed"
           return false

data/lib/mongo/socket/ssl.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #

data/lib/mongo/socket/tcp.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #
@@ -46,6 +46,9 @@ module Mongo
       # @since 2.0.0
       # @api private
       def initialize(host, port, timeout, family, options = {})
+        if family.nil?
+          raise ArgumentError, 'family must be specified'
+        end
         super(timeout, options)
         @host, @port = host, port
         @family = family

data/lib/mongo/socket/unix.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #