mongo 2.24.0 → 2.25.0

data/lib/mongo/server_selector/base.rb

@@ -37,6 +37,8 @@ module Mongo
       #   reads on the server. Hedged reads are not enabled by default. When
       #   specifying this option, it must be in the format: { enabled: true },
       #   where the value of the :enabled key is a boolean value.
+      #   @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #     be removed in a future version.
       #
       # @raise [ Error::InvalidServerPreference ] If tag sets are specified
       #   but not allowed.
@@ -51,6 +53,14 @@ module Mongo
         @hedge = options[:hedge]
 
         validate!
+
+        return if @hedge.nil?
+
+        Mongo::Deprecations.warn(
+          :hedge_read_preference,
+          'The hedge read preference option is deprecated. Hedged reads are ' \
+          'deprecated in MongoDB Server 8.0 and will be removed in a future version.'
+        )
       end
 
       # @return [ Hash ] options The options.
@@ -67,6 +77,9 @@ module Mongo
 
       # @return [ Hash | nil ] hedge The document specifying whether to enable
       #   hedged reads.
+      #
+      # @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #   be removed in a future version.
       attr_reader :hedge
 
       # Get the timeout for server selection.
@@ -226,7 +239,7 @@ module Mongo
 
           session.unpin unless session.in_transaction?
 
-          if server = session.pinned_server
+          if (server = session.pinned_server)
             # Here we assume that a mongos stays in the topology indefinitely.
             # This will no longer be the case once SRV polling is implemented.
 
@@ -385,9 +398,7 @@ module Mongo
       # @api private
       def candidates(cluster, deprioritized = [])
         servers = cluster.servers.reject { |s| deprioritized.include?(s) }
-        if cluster.single?
-          servers
-        elsif cluster.sharded?
+        if cluster.single? || cluster.sharded?
           servers
         elsif cluster.replica_set?
           select_in_replica_set(servers)
@@ -676,8 +687,7 @@ module Mongo
         msg = ''
         dead_monitors = []
         cluster.servers_list.each do |server|
-          thread = server.monitor.instance_variable_get(:@thread)
-          dead_monitors << server if thread.nil? || !thread.alive?
+          dead_monitors << server unless server.monitor&.running?
         end
         if dead_monitors.any?
           msg += ". The following servers have dead monitor threads: #{dead_monitors.map(&:summary).join(', ')}"

data/lib/mongo/server_selector/nearest.rb

@@ -59,6 +59,9 @@ module Mongo
       # Whether the hedge option is allowed to be defined for this server preference.
       #
       # @return [ true ] true
+      #
+      # @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #   be removed in a future version.
       def hedge_allowed?
         true
       end

data/lib/mongo/server_selector/primary.rb

@@ -59,6 +59,9 @@ module Mongo
       # Whether the hedge option is allowed to be defined for this server preference.
       #
       # @return [ false ] false
+      #
+      # @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #   be removed in a future version.
       def hedge_allowed?
         false
       end

data/lib/mongo/server_selector/primary_preferred.rb

@@ -59,6 +59,9 @@ module Mongo
       # Whether the hedge option is allowed to be defined for this server preference.
       #
       # @return [ true ] true
+      #
+      # @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #   be removed in a future version.
       def hedge_allowed?
         true
       end

data/lib/mongo/server_selector/secondary.rb

@@ -59,6 +59,9 @@ module Mongo
       # Whether the hedge option is allowed to be defined for this server preference.
       #
       # @return [ true ] true
+      #
+      # @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #   be removed in a future version.
       def hedge_allowed?
         true
       end

data/lib/mongo/server_selector/secondary_preferred.rb

@@ -59,6 +59,9 @@ module Mongo
       # Whether the hedge option is allowed to be defined for this server preference.
       #
       # @return [ true ] true
+      #
+      # @deprecated Hedged reads are deprecated in MongoDB Server 8.0 and will
+      #   be removed in a future version.
       def hedge_allowed?
         true
       end
@@ -98,7 +101,10 @@ module Mongo
       #
       # @since 2.0.0
       def select_in_replica_set(candidates)
-        near_servers(secondaries(candidates)) + primary(candidates)
+        eligible = secondaries(candidates)
+        return near_servers(eligible) unless eligible.empty?
+
+        primary(candidates)
       end
 
       def max_staleness_allowed?

data/lib/mongo/session.rb

@@ -74,6 +74,8 @@ module Mongo
     #     and *:nearest*.
     # @option options [ true | false ] :snapshot Set up the session for
     #   snapshot reads.
+    # @option options [ BSON::Timestamp ] :snapshot_time The desired snapshot
+    #   time for snapshot reads. Only valid when :snapshot is true.
     #
     # @since 2.5.0
     # @api private
@@ -82,6 +84,14 @@ module Mongo
         raise ArgumentError, ':causal_consistency and :snapshot options cannot be both set on a session'
       end
 
+      if options[:snapshot_time] && !options[:snapshot]
+        raise ArgumentError, ':snapshot_time can only be set when :snapshot is true'
+      end
+
+      if options[:snapshot_time] && !options[:snapshot_time].is_a?(BSON::Timestamp)
+        raise ArgumentError, ':snapshot_time must be a BSON::Timestamp'
+      end
+
       if options[:implicit]
         unless server_session.nil?
           raise ArgumentError, 'Implicit session cannot reference server session during construction'
@@ -104,6 +114,7 @@ module Mongo
       @with_transaction_deadline = nil
       @with_transaction_timeout_ms = nil
       @inside_with_transaction = false
+      @snapshot_timestamp = options[:snapshot_time]
     end
 
     # @return [ Hash ] The options for this session.
@@ -448,13 +459,9 @@ module Mongo
       @inside_with_transaction = true
       @with_transaction_timeout_ms = options&.dig(:timeout_ms) || @options[:default_timeout_ms] || @client.timeout_ms
       @with_transaction_deadline = calculate_with_transaction_deadline(options)
-      deadline = if @with_transaction_deadline
-                   # CSOT enabled, so we have a customer defined deadline.
-                   @with_transaction_deadline
-                 else
-                   # CSOT not enabled, so we use the default deadline, 120 seconds.
-                   Utils.monotonic_time + 120
-                 end
+      # When CSOT is enabled we have a customer defined deadline; otherwise
+      # fall back to the default deadline, 120 seconds.
+      deadline = @with_transaction_deadline || (Utils.monotonic_time + 120)
       transaction_in_progress = false
       transaction_attempt = 0
       last_error = nil
@@ -936,6 +943,13 @@ module Mongo
     #
     # @api private
     def unpin(connection = nil)
+      # Idempotent: if there is no pinned state to clear, do nothing. Nested
+      # unpin_maybe handlers (e.g. in BulkWrite#execute_operation wrapping an
+      # OpMsg execution that already calls unpin_maybe in its own do_execute)
+      # can call this method twice for the same error; checking the connection
+      # back into the pool a second time would raise from the pool.
+      return if @pinned_server.nil? && @pinned_connection.nil? && @pinned_connection_global_id.nil?
+
       @pinned_server = nil
       @pinned_connection_global_id = nil
       conn = connection || @pinned_connection
@@ -1036,7 +1050,7 @@ module Mongo
           # even if transaction's read concern is not set.
           # Read concern here is the one sent to the server and may
           # include afterClusterTime.
-          if rc = c[:readConcern]
+          if (rc = c[:readConcern])
             rc = rc.dup
             rc.delete(:level)
           end
@@ -1183,7 +1197,7 @@ module Mongo
     def process(result)
       unless implicit?
         set_operation_time(result)
-        if cluster_time_doc = result.cluster_time
+        if (cluster_time_doc = result.cluster_time)
           advance_cluster_time(cluster_time_doc)
         end
       end
@@ -1266,8 +1280,23 @@ module Mongo
       @server_session.txn_num
     end
 
+    # @return [ BSON::Timestamp | nil ] The snapshot time for this session.
+    #   nil if the session is not a snapshot session, or if it is a snapshot
+    #   session for which no :snapshot_time option was provided and no read
+    #   has yet captured atClusterTime from the server.
+    attr_reader :snapshot_timestamp
+
+    # Sets the snapshot time for the session. Once set, subsequent
+    # assignments are ignored: snapshotTime is established at most once per
+    # session, either from the :snapshot_time option at construction or from
+    # the atClusterTime returned by the first find/aggregate/distinct
+    # response. This keeps the property effectively read-only for callers,
+    # per the snapshot-sessions spec rationale.
+    #
     # @api private
-    attr_accessor :snapshot_timestamp
+    def snapshot_timestamp=(value)
+      @snapshot_timestamp ||= value
+    end
 
     # @return [ Integer | nil ] The deadline for the current transaction, if any.
     # @api private
@@ -1279,8 +1308,6 @@ module Mongo
       @inside_with_transaction
     end
 
-    private
-
     # Get the read concern the session will use when starting a transaction.
     #
     # This is a driver style hash with underscore keys.
@@ -1291,11 +1318,24 @@ module Mongo
     # @return [ Hash ] The read concern used for starting transactions.
     #
     # @since 2.9.0
+    # @api private
     def txn_read_concern
       # Read concern is inherited from client but not db or collection.
       txn_options[:read_concern] || @client.read_concern
     end
 
+    # Returns causal consistency document if the last operation time is
+    # known and causal consistency is enabled, otherwise returns nil.
+    #
+    # @api private
+    def causal_consistency_doc
+      return unless operation_time && causal_consistency?
+
+      { afterClusterTime: operation_time }
+    end
+
+    private
+
     def within_states?(*states)
       states.include?(@state)
     end
@@ -1313,14 +1353,6 @@ module Mongo
         (@client.write_concern && @client.write_concern.options)
     end
 
-    # Returns causal consistency document if the last operation time is
-    # known and causal consistency is enabled, otherwise returns nil.
-    def causal_consistency_doc
-      return unless operation_time && causal_consistency?
-
-      { afterClusterTime: operation_time }
-    end
-
     def causal_consistency?
       @causal_consistency ||= if @options.key?(:causal_consistency)
                                 !!@options[:causal_consistency]
@@ -1358,9 +1390,9 @@ module Mongo
             raise Mongo::Error::InvalidTransactionOperation,
                   'timeoutMS cannot be overridden inside a withTransaction callback'
           end
-        elsif timeout_ms = opts[:timeout_ms]
+        elsif (timeout_ms = opts[:timeout_ms])
           result[:operation_timeout_ms] = timeout_ms
-        elsif default_timeout_ms = options[:default_timeout_ms]
+        elsif (default_timeout_ms = options[:default_timeout_ms])
           result[:operation_timeout_ms] = default_timeout_ms
         end
       end
@@ -1374,9 +1406,9 @@ module Mongo
           Utils.monotonic_time + (timeout / 1000.0)
         end
       }
-      if timeout_ms = opts&.dig(:timeout_ms)
+      if (timeout_ms = opts&.dig(:timeout_ms))
         calc.call(timeout_ms)
-      elsif default_timeout_ms = @options[:default_timeout_ms]
+      elsif (default_timeout_ms = @options[:default_timeout_ms])
         calc.call(default_timeout_ms)
       elsif @client.timeout_ms
         calc.call(@client.timeout_ms)

data/lib/mongo/socket/ssl.rb

@@ -359,7 +359,7 @@ module Mongo
         if options[:ssl_cert]
           cert_text = File.read(options[:ssl_cert])
           cert_object = nil
-        elsif cert_text = options[:ssl_cert_string]
+        elsif (cert_text = options[:ssl_cert_string])
           cert_object = nil
         else
           cert_object = options[:ssl_cert_object]
@@ -421,13 +421,13 @@ module Mongo
         # https://github.com/jruby/jruby-openssl/issues/176
         if BSON::Environment.jruby?
           [ OpenSSL::PKey::RSA, OpenSSL::PKey::DSA ].each do |cls|
-            return cls.send(:new, *args)
+            return cls.new(*args)
           rescue OpenSSL::PKey::PKeyError
             # ignore
           end
           # Neither RSA nor DSA worked, fall through to trying PKey
         end
-        OpenSSL::PKey.send(:read, *args)
+        OpenSSL::PKey.read(*args)
       end
 
       def set_cert_verification(context, options)

data/lib/mongo/socket.rb

@@ -547,10 +547,6 @@ module Mongo
       !rv.nil?
     end
 
-    def unix_socket?(sock)
-      defined?(UNIXSocket) && sock.is_a?(UNIXSocket)
-    end
-
     DEFAULT_TCP_KEEPINTVL = 10
 
     DEFAULT_TCP_KEEPCNT = 9
@@ -590,9 +586,7 @@ module Mongo
       yield
     rescue Errno::ETIMEDOUT => e
       raise Error::SocketTimeoutError, "#{e.class}: #{e} (for #{human_address})"
-    rescue IOError, SystemCallError, ::SocketError => e
-      raise Error::SocketError, "#{e.class}: #{e} (for #{human_address})"
-    rescue OpenSSL::SSL::SSLError => e
+    rescue IOError, SystemCallError, ::SocketError, OpenSSL::SSL::SSLError => e
       raise Error::SocketError, "#{e.class}: #{e} (for #{human_address})"
     end
 

data/lib/mongo/srv/monitor.rb

@@ -42,10 +42,13 @@ module Mongo
       #   Options to pass through to Resolv::DNS constructor for SRV lookups.
       def initialize(cluster, **opts)
         @cluster = cluster
-        raise ArgumentError, 'SRV URI is required' unless @srv_uri = opts.delete(:srv_uri)
+        raise ArgumentError, 'SRV URI is required' unless (@srv_uri = opts.delete(:srv_uri))
 
         @options = opts.freeze
-        @resolver = Srv::Resolver.new(**opts)
+        # Per the polling-srv-records spec, mismatched-domain records and empty
+        # results MUST be logged and ignored, not raised. Force the polling
+        # resolver into log-and-continue mode regardless of caller options.
+        @resolver = Srv::Resolver.new(**opts, raise_on_invalid: false)
         @last_result = @srv_uri.srv_result
         @stop_semaphore = Semaphore.new
       end
@@ -82,6 +85,12 @@ module Mongo
         rescue Resolv::ResolvError => e
           log_warn("SRV monitor: unable to resolve hostname #{@srv_uri.query_hostname}: #{e.class}: #{e}")
           return
+        rescue Mongo::Error => e
+          # Defense in depth: the polling resolver is configured to log-and-continue
+          # for mismatched-domain and empty-result cases, but if any Mongo::Error
+          # leaks out we MUST NOT let it terminate the SRV monitor thread.
+          log_warn("SRV monitor: error resolving hostname #{@srv_uri.query_hostname}: #{e.class}: #{e}")
+          return
         end
 
         if last_result.empty?

data/lib/mongo/srv/resolver.rb

@@ -142,7 +142,7 @@ module Mongo
       #
       # @return [ Boolean ] Whether an error should be raised.
       def raise_on_invalid?
-        @raise_on_invalid ||= @options[:raise_on_invalid] || true
+        @options.fetch(:raise_on_invalid, true)
       end
     end
   end

data/lib/mongo/srv/result.rb

@@ -123,9 +123,11 @@ module Mongo
           raise Error::MismatchedDomain.new(format(MISMATCHED_DOMAINNAME, record_host, srv_host_domain))
         end
 
-        unless (record_host_parts.size > srv_host_domain.size) && (srv_host_domain == record_host_parts[-srv_host_domain.size..-1])
-          raise Error::MismatchedDomain.new(format(MISMATCHED_DOMAINNAME, record_host, srv_host_domain))
-        end
+        record_matches_domain = (record_host_parts.size > srv_host_domain.size) &&
+                                (srv_host_domain == record_host_parts[-srv_host_domain.size..-1])
+        return if record_matches_domain
+
+        raise Error::MismatchedDomain.new(format(MISMATCHED_DOMAINNAME, record_host, srv_host_domain))
       end
     end
   end

data/lib/mongo/timeout.rb

@@ -18,8 +18,7 @@ module Mongo
   # @api private
   module Timeout
     # A wrapper around Ruby core's Timeout::timeout method that provides
-    # a standardized API for Ruby versions older and newer than 2.4.0,
-    # which is when the third argument was introduced.
+    # a standardized API for calling it.
     #
     # @param [ Numeric ] sec The number of seconds before timeout.
     # @param [ Class ] klass The exception class to raise on timeout, optional.
@@ -28,19 +27,15 @@ module Mongo
     #   on timeout, optional. When no error message is provided, the default
     #   error message for the exception class is used.
     def timeout(sec, klass = nil, message = nil, &block)
-      if message && RUBY_VERSION < '2.94.0'
-        begin
-          ::Timeout.timeout(sec, &block)
-        rescue ::Timeout::Error
-          raise klass, message
-        end
-      else
-        # Jruby Timeout::timeout method does not support passing nil arguments.
-        # Remove the nil arguments before passing them along to the core
-        # Timeout::timeout method.
-        optional_args = [ klass, message ].compact
-        ::Timeout.timeout(sec, *optional_args, &block)
-      end
+      # provide a default error class if the message is present; otherwise,
+      # the message will be interpreted as the error class, if klass is nil
+      klass ||= ::Timeout::Error if message
+
+      # Jruby Timeout::timeout method does not support passing nil arguments.
+      # Remove the nil arguments before passing them along to the core
+      # Timeout::timeout method.
+      optional_args = [ klass, message ].compact
+      ::Timeout.timeout(sec, *optional_args, &block)
     end
     module_function :timeout
   end

data/lib/mongo/tracing/open_telemetry/command_tracer.rb

@@ -21,6 +21,15 @@ module Mongo
       #
       # @api private
       class CommandTracer
+        include Mongo::Monitoring::Event::Secure
+
+        # Commands for which a span MUST NOT be created. The OpenTelemetry spec
+        # requires drivers to skip command spans for sensitive commands listed in
+        # the Command Logging and Monitoring spec. We additionally skip hello /
+        # legacy hello in all forms — these are handshake/heartbeat traffic and
+        # would only add noise to traces.
+        HELLO_COMMANDS = %w[hello ismaster isMaster].freeze
+
         # Initializes a new CommandTracer.
         #
         # @param otel_tracer [ OpenTelemetry::Trace::Tracer ] the OpenTelemetry tracer.
@@ -57,6 +66,8 @@ module Mongo
         # @return [ Object ] the result of the command.
         # rubocop:disable Lint/RescueException
         def trace_command(message, _operation_context, connection)
+          return yield if skip_tracing?(message)
+
           # Commands should always be nested under their operation span, not directly under
           # the transaction span. Don't pass with_parent to use automatic parent resolution
           # from the currently active span (the operation span).
@@ -76,6 +87,22 @@ module Mongo
 
         private
 
+        # Determines whether the command must not be traced. Sensitive auth
+        # commands carry credentials in their payloads (SCRAM proofs, cleartext
+        # passwords, etc.) and the OpenTelemetry spec requires drivers to skip
+        # command spans for them. Hello / legacy hello are also skipped to keep
+        # handshake traffic out of traces.
+        #
+        # @param message [ Mongo::Protocol::Message ] the command message.
+        #
+        # @return [ Boolean ] true when no command span should be created.
+        def skip_tracing?(message)
+          name = command_name(message)
+          return true if HELLO_COMMANDS.include?(name)
+
+          sensitive?(command_name: name, document: message.documents.first)
+        end
+
         # Creates a span for a command.
         #
         # @param message [ Mongo::Protocol::Message ] the command message.
@@ -179,9 +206,23 @@ module Mongo
         # @param _context [ OpenTelemetry::Context ] the context (unused).
         # @param span [ OpenTelemetry::Trace::Span ] the current span.
         def process_cursor_context(result, _cursor_id, _context, span)
-          return unless result.has_cursor_id? && result.cursor_id.positive?
+          cursor_id = normalize_cursor_id(result.cursor_id)
+          return unless cursor_id.positive?
+
+          span.set_attribute('db.mongodb.cursor_id', cursor_id)
+        end
 
-          span.set_attribute('db.mongodb.cursor_id', result.cursor_id)
+        # Normalizes a cursor id to a plain Integer.
+        #
+        # OP_MSG replies deserialized in :bson mode expose the cursor id as a
+        # BSON::Int64, which does not implement Numeric#positive? and is not a
+        # valid OpenTelemetry attribute type.
+        #
+        # @param cursor_id [ Integer | BSON::Int64 ] the raw cursor id.
+        #
+        # @return [ Integer ] the cursor id as an Integer.
+        def normalize_cursor_id(cursor_id)
+          cursor_id.is_a?(BSON::Int64) ? cursor_id.value : cursor_id
         end
 
         # Records error status code if the command failed.

data/lib/mongo/uri/options_mapper.rb

@@ -87,7 +87,7 @@ module Mongo
           strategy = URI_OPTION_MAP[key.downcase]
           if strategy.nil?
             log_warn("Unsupported URI option '#{key}' on URI '#{@string}'. It will be ignored.")
-            return
+            next
           end
 
           group = strategy[:group]
@@ -125,7 +125,7 @@ module Mongo
           end
           next if v.nil?
 
-          if type = spec[:type]
+          if (type = spec[:type])
             v = send("revert_#{type}", v)
           end
           canonical_key = URI_OPTION_CANONICAL_NAMES[uri_key]
@@ -163,7 +163,7 @@ module Mongo
           end
           next if v.nil?
 
-          if type = spec[:type]
+          if (type = spec[:type])
             v = send("stringify_#{type}", v)
           end
           canonical_key = URI_OPTION_CANONICAL_NAMES[uri_key]
@@ -354,13 +354,25 @@ module Mongo
 
       # Converts the value into a boolean and returns it wrapped in an array.
       #
-      # @param [ String ] name Name of the URI option being processed.
+      # tls and ssl are the only repeated_bool options. An invalid value is
+      # preserved as a nil element rather than warned-and-dropped, so that
+      # URI#validate_uri_options! can detect it and raise instead of silently
+      # falling back to a plaintext connection (RUBY-3832).
+      #
+      # @param [ String ] _name Name of the URI option being processed.
       # @param [ String ] value URI option value.
       #
-      # @return [ Array<true | false> | nil ] The boolean value parsed and wraped
-      #   in an array.
-      def convert_repeated_bool(name, value)
-        [ convert_bool(name, value) ]
+      # @return [ Array<true | false | nil> ] The boolean value parsed and
+      #   wrapped in an array.
+      def convert_repeated_bool(_name, value)
+        case value
+        when true, 'true', 'TRUE'
+          [ true ]
+        when false, 'false', 'FALSE'
+          [ false ]
+        else
+          [ nil ]
+        end
       end
 
       # Reverts a repeated boolean type.
@@ -379,7 +391,7 @@ module Mongo
       # @return [ Array<true | false> | nil ] The string.
       def stringify_repeated_bool(value)
         rep = revert_repeated_bool(value)
-        if rep&.is_a?(Array)
+        if rep.is_a?(Array)
           rep.join(',')
         else
           rep

data/lib/mongo/uri/srv_protocol.rb

@@ -117,14 +117,14 @@ module Mongo
         raise Error::InvalidURI.new(@string, details, FORMAT)
       end
 
-      # Gets the SRV resolver.
-      # If domain verification fails or no SRV records are found,
-      # an error must not be raised per the spec; instead, a warning is logged.
+      # Gets the SRV resolver used for initial URI parsing.
+      # Per the Initial DNS Seedlist Discovery spec, the driver MUST raise an
+      # error if domain verification fails or no SRV records are found, so
+      # raise_on_invalid is left at its default of true.
       #
       # @return [ Mongo::Srv::Resolver ]
       def resolver
         @resolver ||= Srv::Resolver.new(
-          raise_on_invalid: false,
           resolv_options: options[:resolv_options],
           timeout: options[:connect_timeout]
         )