mongo 2.19.3 → 2.20.0

data/lib/mongo/server/app_metadata/environment.rb

@@ -18,9 +18,12 @@ module Mongo
   class Server
     class AppMetadata
       # Implements the logic from the handshake spec, for deducing and
-      # reporting the current FaaS environment in which the program is
+      # reporting the current environment in which the program is
       # executing.
       #
+      # This includes FaaS environment checks, as well as checks for the
+      # presence of a container (Docker) and/or orchestrator (Kubernetes).
+      #
       # @api private
       class Environment
         # Error class for reporting that too many discriminators were found
@@ -39,6 +42,10 @@ module Mongo
         # Error class for reporting that the value for a field is too long.
         class ValueTooLong < Mongo::Error; end
 
+        # The name and location of the .dockerenv file that will signal the
+        # presence of Docker.
+        DOCKERENV_PATH = '/.dockerenv'
+
         # This value is not explicitly specified in the spec, only implied to be
         # less than 512.
         MAXIMUM_VALUE_LENGTH = 500
@@ -102,9 +109,11 @@ module Mongo
         # if the environment contains invalid or contradictory state, it will
         # be initialized with {{name}} set to {{nil}}.
         def initialize
+          @fields = {}
           @error = nil
           @name = detect_environment
-          populate_fields
+          populate_faas_fields
+          detect_container
         rescue TooManyEnvironments => e
           self.error = "too many environments detected: #{e.message}"
         rescue MissingVariable => e
@@ -115,6 +124,23 @@ module Mongo
           self.error = "value for #{e.message} is too long"
         end
 
+        # Queries the detected container information.
+        #
+        # @return [ Hash | nil ] the detected container information, or
+        #    nil if no container was detected.
+        def container
+          fields[:container]
+        end
+
+        # Queries whether any environment information was able to be
+        # detected.
+        #
+        # @return [ true | false ] if any environment information was
+        #   detected.
+        def present?
+          @name || fields.any?
+        end
+
         # Queries whether the current environment is a valid FaaS environment.
         #
         # @return [ true | false ] whether the environment is a FaaS
@@ -159,14 +185,11 @@ module Mongo
           @name == 'vercel'
         end
 
-        # Compiles the detected environment information into a Hash. It will
-        # always include a {{name}} key, but may include other keys as well,
-        # depending on the detected FaaS environment. (See the handshake
-        # spec for details.)
+        # Compiles the detected environment information into a Hash.
         #
         # @return [ Hash ] the detected environment information.
         def to_h
-          fields.merge(name: name)
+          name ? fields.merge(name: name) : fields
         end
 
         private
@@ -192,6 +215,38 @@ module Mongo
           names.first
         end
 
+        # Looks for the presence of a container. Currently can detect
+        # Docker (by the existence of a .dockerenv file in the root
+        # directory) and Kubernetes (by the existence of the KUBERNETES_SERVICE_HOST
+        # environment variable).
+        def detect_container
+          runtime = docker_present? && 'docker'
+          orchestrator = kubernetes_present? && 'kubernetes'
+
+          return unless runtime || orchestrator
+
+          fields[:container] = {}
+          fields[:container][:runtime] = runtime if runtime
+          fields[:container][:orchestrator] = orchestrator if orchestrator
+        end
+
+        # Checks for the existence of a .dockerenv in the root directory.
+        def docker_present?
+          File.exist?(dockerenv_path)
+        end
+
+        # Implementing this as a method so that it can be mocked in tests, to
+        # test the presence or absence of Docker.
+        def dockerenv_path
+          DOCKERENV_PATH
+        end
+
+        # Checks for the presence of a non-empty KUBERNETES_SERVICE_HOST
+        # environment variable.
+        def kubernetes_present?
+          !ENV['KUBERNETES_SERVICE_HOST'].to_s.empty?
+        end
+
         # Determines whether the named environment variable exists, and (if
         # a pattern has been declared for that descriminator) whether the
         # pattern matches the value of the variable.
@@ -212,10 +267,10 @@ module Mongo
         # Extracts environment information from the current environment
         # variables, based on the detected FaaS environment. Populates the
         # {{@fields}} instance variable.
-        def populate_fields
+        def populate_faas_fields
           return unless name
 
-          @fields = FIELDS[name].each_with_object({}) do |(var, defn), fields|
+          FIELDS[name].each_with_object(@fields) do |(var, defn), fields|
             fields[defn[:field]] = extract_field(var, defn)
           end
         end

data/lib/mongo/server/app_metadata.rb

@@ -187,13 +187,14 @@ module Mongo
         }
       end
 
-      # Returns the environment doc describing the current FaaS environment.
+      # Returns the environment doc describing the current execution
+      # environment.
       #
-      # @return [ Hash | nil ] the environment doc (or nil if not in a FaaS
-      #   environment).
+      # @return [ Hash | nil ] the environment doc (or nil if no relevant
+      #    environment info was detected)
       def env_doc
         env = Environment.new
-        env.faas? ? env.to_h : nil
+        env.present? ? env.to_h : nil
       end
 
       def type

data/lib/mongo/server/description/features.rb

@@ -48,6 +48,7 @@ module Mongo
           # provided by the client during findAndModify operations, requiring the
           # driver to raise client-side errors when those options are provided.
           find_and_modify_option_validation: 8,
+          sharded_transactions: 8,
           transactions: 7,
           scram_sha_256: 7,
           array_filters: 6,

data/lib/mongo/server_selector/base.rb

@@ -164,6 +164,10 @@ module Mongo
       #   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.
+      # @param [ Array<Server> ] deprioritized A list of servers that should
+      #   be selected from only if no other servers are available. This is
+      #   used to avoid selecting the same server twice in a row when
+      #   retrying a command.
       #
       # @return [ Mongo::Server ] A server matching the server preference.
       #
@@ -174,8 +178,8 @@ module Mongo
       #   lint mode is enabled.
       #
       # @since 2.0.0
-      def select_server(cluster, ping = nil, session = nil, write_aggregation: false)
-        select_server_impl(cluster, ping, session, write_aggregation).tap do |server|
+      def select_server(cluster, ping = nil, session = nil, write_aggregation: false, deprioritized: [])
+        select_server_impl(cluster, ping, session, write_aggregation, deprioritized).tap do |server|
           if Lint.enabled? && !server.pool.ready?
             raise Error::LintError, 'Server selector returning a server with a pool which is not ready'
           end
@@ -183,7 +187,7 @@ module Mongo
       end
 
       # Parameters and return values are the same as for select_server.
-      private def select_server_impl(cluster, ping, session, write_aggregation)
+      private def select_server_impl(cluster, ping, session, write_aggregation, deprioritized)
         if cluster.topology.is_a?(Cluster::Topology::LoadBalanced)
           return cluster.servers.first
         end
@@ -266,7 +270,7 @@ module Mongo
             end
           end
 
-          server = try_select_server(cluster, write_aggregation: write_aggregation)
+          server = try_select_server(cluster, write_aggregation: write_aggregation, deprioritized: deprioritized)
 
           if server
             unless cluster.topology.compatible?
@@ -321,11 +325,15 @@ module Mongo
       #   an eligible server.
       # @param [ true | false ] write_aggregation Whether we need a server that
       #   supports writing aggregations (e.g. with $merge/$out) on secondaries.
+      # @param [ Array<Server> ] deprioritized A list of servers that should
+      #   be selected from only if no other servers are available. This is
+      #   used to avoid selecting the same server twice in a row when
+      #   retrying a command.
       #
       # @return [ Server | nil ] A suitable server, if one exists.
       #
       # @api private
-      def try_select_server(cluster, write_aggregation: false)
+      def try_select_server(cluster, write_aggregation: false, deprioritized: [])
         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|
@@ -347,7 +355,7 @@ module Mongo
         # by the selector (e.g. for secondary preferred, the first
         # server may be a secondary and the second server may be primary)
         # and we should take the first server here respecting the order
-        server = servers.first
+        server = suitable_server(servers, deprioritized)
 
         if server
           if Lint.enabled?
@@ -418,6 +426,24 @@ module Mongo
 
       private
 
+      # Returns a server from the list of servers that is suitable for
+      # executing the operation.
+      #
+      # @param [ Array<Server> ] servers The candidate servers.
+      # @param [ Array<Server> ] deprioritized A list of servers that should
+      #  be selected from only if no other servers are available.
+      #
+      # @return [ Server | nil ] The suitable server or nil if no suitable
+      #  server is available.
+      def suitable_server(servers, deprioritized)
+        preferred = servers - deprioritized
+        if preferred.empty?
+          servers.first
+        else
+          preferred.first
+        end
+      end
+
       # Convert this server preference definition into a format appropriate
       #   for sending to a MongoDB server (i.e., as a command field).
       #

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

@@ -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

@@ -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
@@ -105,9 +90,7 @@ module Mongo
 
         @mutex.synchronize do
           prune!
-          unless about_to_expire?(session)
-            @queue.unshift(session)
-          end
+          @queue.unshift(session) if return_to_queue?(session)
         end
       end
 
@@ -136,6 +119,17 @@ 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'

data/lib/mongo/session.rb

@@ -123,6 +123,23 @@ module Mongo
     # @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.
     #
@@ -538,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])
 
@@ -1185,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/uri.rb

@@ -377,10 +377,6 @@ module Mongo
         raise_invalid_error!("Options contain an unescaped question mark (?), or the database name contains a question mark and was not escaped")
       end
 
-      if options && !hosts_and_db.index('/')
-        raise_invalid_error!("MongoDB URI must have a slash (/) after the hosts if options are given")
-      end
-
       hosts, db = hosts_and_db.split('/', 2)
       if db && db.index('/')
         raise_invalid_error!("Database name contains an unescaped slash (/): #{db}")

data/lib/mongo/version.rb

@@ -20,5 +20,5 @@ module Mongo
   # The current version of the driver.
   #
   # @since 2.0.0
-  VERSION = '2.19.3'.freeze
+  VERSION = '2.20.0'.freeze
 end

data/mongo.gemspec

@@ -41,11 +41,5 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = ">= 2.5"
 
-  # For testing driver against bson master we need to depend on bson < 6.0.0
-  # but in release version we want to depend on bson < 5.0.0.
-  if %w(1 yes true).include?(ENV['MONGO_RUBY_DRIVER_BSON_MASTER'])
-    s.add_dependency 'bson', '>=4.13.0', '<6.0.0'
-  else
-    s.add_dependency 'bson', '>=4.14.1', '<5.0.0'
-  end
+  s.add_dependency 'bson', '>=4.14.1', '<6.0.0'
 end

data/spec/atlas/atlas_connectivity_spec.rb

@@ -11,13 +11,13 @@ describe 'Atlas connectivity' do
 
   describe 'connection to Atlas' do
     it 'runs ismaster successfully' do
-      result = client.database.command(:ismaster => 1)
-      expect(result.documents.first['ismaster']).to be true
+      expect { client.database.command(:hello => 1) }
+        .not_to raise_error
     end
 
     it 'runs findOne successfully' do
-      result = client.use(:test)['test'].find.to_a
-      expect(result).to be_a(Array)
+      expect { client.use(:test)['test'].find.to_a }
+        .not_to raise_error
     end
   end
 end

data/spec/faas/ruby-sam-app/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+gem "httparty"
+gem "mongo"
+
+group :test do
+  gem "test-unit"
+  gem "mocha"
+end

data/spec/faas/ruby-sam-app/mongodb/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+gem "httparty"
+gem "mongo"

data/spec/faas/ruby-sam-app/mongodb/app.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'mongo'
+require 'json'
+
+class StatsAggregator
+
+  def initialize
+    @open_connections = 0
+    @heartbeats_count = 0
+    @total_heartbeat_time = 0
+    @commands_count = 0
+    @total_command_time = 0
+  end
+
+  def add_command(duration)
+    @commands_count += 1
+    @total_command_time += duration
+  end
+
+  def add_heartbeat(duration)
+    @heartbeats_count += 1
+    @total_heartbeat_time += duration
+  end
+
+  def add_connection
+    @open_connections += 1
+  end
+
+  def remove_connection
+    @open_connections -= 1
+  end
+
+  def average_heartbeat_time
+    if @heartbeats_count == 0
+      0
+    else
+      @total_heartbeat_time / @heartbeats_count
+    end
+  end
+
+  def average_command_time
+    if @commands_count == 0
+      0
+    else
+      @total_command_time / @commands_count
+    end
+  end
+
+  def reset
+    @open_connections = 0
+    @heartbeats_count = 0
+    @total_heartbeat_time = 0
+    @commands_count = 0
+    @total_command_time = 0
+  end
+
+  def result
+    {
+      average_heartbeat_time: average_heartbeat_time,
+      average_command_time: average_command_time,
+      heartbeats_count: @heartbeats_count,
+      open_connections: @open_connections,
+    }
+  end
+end
+
+class CommandMonitor
+
+  def initialize(stats_aggregator)
+    @stats_aggregator = stats_aggregator
+  end
+
+  def started(event); end
+
+  def failed(event)
+    @stats_aggregator.add_command(event.duration)
+  end
+
+  def succeeded(event)
+    @stats_aggregator.add_command(event.duration)
+  end
+end
+
+class HeartbeatMonitor
+
+  def initialize(stats_aggregator)
+    @stats_aggregator = stats_aggregator
+  end
+
+  def started(event); end
+
+  def succeeded(event)
+    @stats_aggregator.add_heartbeat(event.duration)
+  end
+
+  def failed(event)
+    @stats_aggregator.add_heartbeat(event.duration)
+  end
+end
+
+class PoolMonitor
+
+  def initialize(stats_aggregator)
+    @stats_aggregator = stats_aggregator
+  end
+
+  def published(event)
+    case event
+    when Mongo::Monitoring::Event::Cmap::ConnectionCreated
+      @stats_aggregator.add_connection
+    when Mongo::Monitoring::Event::Cmap::ConnectionClosed
+      @stats_aggregator.remove_connection
+    end
+  end
+end
+
+$stats_aggregator = StatsAggregator.new
+
+command_monitor = CommandMonitor.new($stats_aggregator)
+heartbeat_monitor = HeartbeatMonitor.new($stats_aggregator)
+pool_monitor = PoolMonitor.new($stats_aggregator)
+
+sdam_proc = proc do |client|
+  client.subscribe(Mongo::Monitoring::COMMAND, command_monitor)
+  client.subscribe(Mongo::Monitoring::SERVER_HEARTBEAT, heartbeat_monitor)
+  client.subscribe(Mongo::Monitoring::CONNECTION_POOL, pool_monitor)
+end
+
+puts 'Connecting'
+$client = Mongo::Client.new(ENV['MONGODB_URI'], sdam_proc: sdam_proc)
+# Populate the connection pool
+$client.use('lambda_test').database.list_collections
+puts 'Connected'
+
+def lambda_handler(event:, context:)
+  db = $client.use('lambda_test')
+  collection = db[:test_collection]
+  result = collection.insert_one({ name: 'test' })
+  collection.delete_one({ _id: result.inserted_id })
+  response = $stats_aggregator.result.to_json
+  $stats_aggregator.reset
+  puts "Response: #{response}"
+
+  {
+    statusCode: 200,
+    body: response
+  }
+end

data/spec/faas/ruby-sam-app/template.yaml

@@ -0,0 +1,48 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: >
+  Sample SAM Template for ruby-sam-app
+
+# More info about Globals: https://github.com/awslabs/serverless-application-model/blob/master/docs/globals.rst
+Globals:
+  Function:
+    Timeout: 30
+    MemorySize: 128
+
+Parameters:
+  MongoDbUri:
+    Type: String
+    Description: The MongoDB connection string.
+
+Resources:
+  MongoDBFunction:
+    Type: AWS::Serverless::Function # More info about Function Resource: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction
+    Properties:
+      CodeUri: mongodb/
+      Environment:
+        Variables:
+          MONGODB_URI: !Ref MongoDbUri
+      Handler: app.lambda_handler
+      Runtime: ruby3.2
+      Architectures:
+        - x86_64
+      Events:
+        MongoDB:
+          Type: Api # More info about API Event Source: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#api
+          Properties:
+            Path: /mongodb
+            Method: get
+
+Outputs:
+  # ServerlessRestApi is an implicit API created out of Events key under Serverless::Function
+  # Find out more about other implicit resources you can reference within SAM
+  # https://github.com/awslabs/serverless-application-model/blob/master/docs/internals/generated_resources.rst#api
+  MongoDBApi:
+    Description: "API Gateway endpoint URL for Prod stage for MongoDB function"
+    Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/mongodb/"
+  MongoDBFunction:
+    Description: "MongoDB Lambda Function ARN"
+    Value: !GetAtt MongoDBFunction.Arn
+  MongoDBFunctionIamRole:
+    Description: "Implicit IAM Role created for MongoDB function"
+    Value: !GetAtt MongoDBFunctionRole.Arn