mongo 2.19.2 → 2.20.0

data/lib/mongo/operation/shared/specifiable.rb

@@ -260,6 +260,13 @@ module Mongo
         spec[INDEX]
       end
 
+      # Get the index id from the spec.
+      #
+      # @return [ String ] The index id.
+      def index_id
+        spec[:index_id]
+      end
+
       # Get the index name from the spec.
       #
       # @example Get the index name.

data/lib/mongo/operation/update_search_index/op_msg.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Mongo
+  module Operation
+    class UpdateSearchIndex
+      # A MongoDB updateSearchIndex operation sent as an op message.
+      #
+      # @api private
+      class OpMsg < OpMsgBase
+        include ExecutableTransactionLabel
+
+        private
+
+        # Returns the command to send to the database, describing the
+        # desired updateSearchIndex operation.
+        #
+        # @param [ Mongo::Server ] _server the server that will receive the
+        #   command
+        #
+        # @return [ Hash ] the selector
+        def selector(_server)
+          {
+            updateSearchIndex: coll_name,
+            :$db => db_name,
+            definition: index,
+          }.tap do |sel|
+            sel[:id] = index_id if index_id
+            sel[:name] = index_name if index_name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongo/operation/update_search_index.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'mongo/operation/update_search_index/op_msg'
+
+module Mongo
+  module Operation
+    # A MongoDB updateSearchIndex command operation.
+    #
+    # @api private
+    class UpdateSearchIndex
+      include Specifiable
+      include OpMsgExecutable
+    end
+  end
+end

data/lib/mongo/operation.rb

@@ -51,6 +51,9 @@ require 'mongo/operation/update_user'
 require 'mongo/operation/remove_user'
 require 'mongo/operation/create_index'
 require 'mongo/operation/drop_index'
+require 'mongo/operation/create_search_indexes'
+require 'mongo/operation/drop_search_index'
+require 'mongo/operation/update_search_index'
 
 module Mongo
 

data/lib/mongo/retryable/read_worker.rb

@@ -190,12 +190,13 @@ module Mongo
       #
       # @return [ Result ] The result of the operation.
       def modern_read_with_retry(session, server_selector, &block)
-        yield select_server(cluster, server_selector, session)
+        server = select_server(cluster, server_selector, session)
+        yield server
       rescue *retryable_exceptions, Error::OperationFailure, Auth::Unauthorized, Error::PoolError => e
         e.add_notes('modern retry', 'attempt 1')
         raise e if session.in_transaction?
         raise e if !is_retryable_exception?(e) && !e.write_retryable?
-        retry_read(e, session, server_selector, &block)
+        retry_read(e, session, server_selector, failed_server: server, &block)
       end
   
       # Attempts to do a "legacy" read with retry. The operation will be
@@ -257,12 +258,14 @@ module Mongo
       #   being run on.
       # @param [ Mongo::ServerSelector::Selectable ] server_selector Server
       #   selector for the operation.
+      # @param [ Mongo::Server ] failed_server The server on which the original
+      #   operation failed.
       # @param [ Proc ] block The block to execute.
       # 
       # @return [ Result ] The result of the operation.
-      def retry_read(original_error, session, server_selector, &block)
+      def retry_read(original_error, session, server_selector, failed_server: nil, &block)
         begin
-          server = select_server(cluster, server_selector, session)
+          server = select_server(cluster, server_selector, session, failed_server)
         rescue Error, Error::AuthError => e
           original_error.add_note("later retry failed: #{e.class}: #{e}")
           raise original_error
@@ -289,8 +292,6 @@ module Mongo
           raise original_error
         end
       end
-  
     end
-
   end
 end

data/lib/mongo/retryable/write_worker.rb

@@ -103,8 +103,9 @@ module Mongo
       def nro_write_with_retry(write_concern, context:, &block)
         session = context.session
         server = select_server(cluster, ServerSelector.primary, session)
+        options = session&.client&.options || {}
         
-        if session&.client.options[:retry_writes]
+        if options[:retry_writes]
           begin
             server.with_connection(connection_global_id: context.connection_global_id) do |connection|
               yield connection, nil, context
@@ -240,7 +241,7 @@ module Mongo
 
         # Context#with creates a new context, which is not necessary here
         # but the API is less prone to misuse this way.
-        retry_write(e, txn_num, context: context.with(is_retry: true), &block)
+        retry_write(e, txn_num, context: context.with(is_retry: true), failed_server: server, &block)
       end
 
       # Called after a failed write, this will retry the write no more than
@@ -250,9 +251,11 @@ module Mongo
       #   retry.
       # @param [ Number ] txn_num The transaction number.
       # @param [ Operation::Context ] context The context for the operation.
+      # @param [ Mongo::Server ] failed_server The server on which the original
+      #   operation failed.
       #
       # @return [ Result ] The result of the operation.
-      def retry_write(original_error, txn_num, context:, &block)
+      def retry_write(original_error, txn_num, context:, failed_server: nil, &block)
         session = context.session
 
         # We do not request a scan of the cluster here, because error handling
@@ -260,7 +263,7 @@ module Mongo
         # server description and/or topology as necessary (specifically,
         # a socket error or a not master error should have marked the respective
         # server unknown). Here we just need to wait for server selection.
-        server = select_server(cluster, ServerSelector.primary, session)
+        server = select_server(cluster, ServerSelector.primary, session, failed_server)
         
         unless server.retry_writes?
           # Do not need to add "modern retry" here, it should already be on

data/lib/mongo/retryable.rb

@@ -46,8 +46,8 @@ module Mongo
     # @api private
     #
     # @return [ Mongo::Server ] A server matching the server preference.
-    def select_server(cluster, server_selector, session)
-      server_selector.select_server(cluster, nil, session)
+    def select_server(cluster, server_selector, session, failed_server = nil)
+      server_selector.select_server(cluster, nil, session, deprioritized: [failed_server].compact)
     end
 
     # Returns the read worker for handling retryable reads.

data/lib/mongo/search_index/view.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Mongo
+  module SearchIndex
+    # A class representing a view of search indexes.
+    class View
+      include Enumerable
+      include Retryable
+      include Collection::Helpers
+
+      # @return [ Mongo::Collection ] the collection this view belongs to
+      attr_reader :collection
+
+      # @return [ nil | String ] the index id to query
+      attr_reader :requested_index_id
+
+      # @return [ nil | String ] the index name to query
+      attr_reader :requested_index_name
+
+      # @return [ Hash ] the options hash to use for the aggregate command
+      #   when querying the available indexes.
+      attr_reader :aggregate_options
+
+      # Create the new search index view.
+      #
+      # @param [ Collection ] collection The collection.
+      # @param [ Hash ] options The options that configure the behavior of the view.
+      #
+      # @option options [ String ] :id The specific index id to query (optional)
+      # @option options [ String ] :name The name of the specific index to query (optional)
+      # @option options [ Hash ] :aggregate The options hash to send to the
+      #   aggregate command when querying the available indexes.
+      def initialize(collection, options = {})
+        @collection = collection
+        @requested_index_id = options[:id]
+        @requested_index_name = options[:name]
+        @aggregate_options = options[:aggregate] || {}
+
+        return if @aggregate_options.is_a?(Hash)
+
+        raise ArgumentError, "The :aggregate option must be a Hash (got a #{@aggregate_options.class})"
+      end
+
+      # Create a single search index with the given definition. If the name is
+      # provided, the new index will be given that name.
+      #
+      # @param [ Hash ] definition The definition of the search index.
+      # @param [ nil | String ] name The name to give the new search index.
+      #
+      # @return [ String ] the name of the new search index.
+      def create_one(definition, name: nil)
+        create_many([ { name: name, definition: definition } ]).first
+      end
+
+      # Create multiple search indexes with a single command.
+      #
+      # @param [ Array<Hash> ] indexes The description of the indexes to
+      #   create. Each element of the list must be a hash with a definition
+      #   key, and an optional name key.
+      #
+      # @return [ Array<String> ] the names of the new search indexes.
+      def create_many(indexes)
+        spec = spec_with(indexes: indexes.map { |v| validate_search_index!(v) })
+        result = Operation::CreateSearchIndexes.new(spec).execute(next_primary, context: execution_context)
+        result.first['indexesCreated'].map { |idx| idx['name'] }
+      end
+
+      # Drop the search index with the given id, or name. One or the other must
+      # be specified, but not both.
+      #
+      # @param [ String ] id the id of the index to drop
+      # @param [ String ] name the name of the index to drop
+      #
+      # @return [ Mongo::Operation::Result | false ] the result of the
+      #    operation, or false if the given index does not exist.
+      def drop_one(id: nil, name: nil)
+        validate_id_or_name!(id, name)
+
+        spec = spec_with(index_id: id, index_name: name)
+        op = Operation::DropSearchIndex.new(spec)
+
+        # per the spec:
+        # Drivers MUST suppress NamespaceNotFound errors for the
+        # ``dropSearchIndex`` helper.  Drop operations should be idempotent.
+        do_drop(op, nil, execution_context)
+      end
+
+      # Iterate over the search indexes.
+      #
+      # @param [ Proc ] block if given, each search index will be yieleded to
+      #    the block.
+      #
+      # @return [ self | Enumerator ] if a block is given, self is returned.
+      #    Otherwise, an enumerator will be returned.
+      def each(&block)
+        @result ||= begin
+          spec = {}.tap do |s|
+            s[:id] = requested_index_id if requested_index_id
+            s[:name] = requested_index_name if requested_index_name
+          end
+
+          collection.aggregate(
+            [ { '$listSearchIndexes' => spec } ],
+            aggregate_options
+          )
+        end
+
+        return @result.to_enum unless block
+
+        @result.each(&block)
+        self
+      end
+
+      # Update the search index with the given id or name. One or the other
+      # must be provided, but not both.
+      #
+      # @param [ Hash ] definition the definition to replace the given search
+      #    index with.
+      # @param [ nil | String ] id the id of the search index to update
+      # @param [ nil | String ] name the name of the search index to update
+      #
+      # @return [ Mongo::Operation::Result ] the result of the operation
+      def update_one(definition, id: nil, name: nil)
+        validate_id_or_name!(id, name)
+
+        spec = spec_with(index_id: id, index_name: name, index: definition)
+        Operation::UpdateSearchIndex.new(spec).execute(next_primary, context: execution_context)
+      end
+
+      # The following methods are to make the view act more like an array,
+      # without having to explicitly make it an array...
+
+      # Queries whether the search index enumerable is empty.
+      #
+      # @return [ true | false ] whether the enumerable is empty or not.
+      def empty?
+        count.zero?
+      end
+
+      private
+
+      # A helper method for building the specification document with certain
+      # values pre-populated.
+      #
+      # @param [ Hash ] extras the values to put into the specification
+      #
+      # @return [ Hash ] the specification document
+      def spec_with(extras)
+        {
+          coll_name: collection.name,
+          db_name: collection.database.name,
+        }.merge(extras)
+      end
+
+      # A helper method for retrieving the primary server from the cluster.
+      #
+      # @return [ Mongo::Server ] the server to use
+      def next_primary(ping = nil, session = nil)
+        collection.cluster.next_primary(ping, session)
+      end
+
+      # A helper method for constructing a new operation context for executing
+      # an operation.
+      #
+      # @return [ Mongo::Operation::Context ] the operation context
+      def execution_context
+        Operation::Context.new(client: collection.client)
+      end
+
+      # Validates the given id and name, ensuring that exactly one of them
+      # is non-nil.
+      #
+      # @param [ nil | String ] id the id to validate
+      # @param [ nil | String ] name the name to validate
+      #
+      # @raise [ ArgumentError ] if neither or both arguments are nil
+      def validate_id_or_name!(id, name)
+        return unless (id.nil? && name.nil?) || (!id.nil? && !name.nil?)
+
+        raise ArgumentError, 'exactly one of id or name must be specified'
+      end
+
+      # Validates the given search index document, ensuring that it has no
+      # extra keys, and that the name and definition are valid.
+      #
+      # @param [ Hash ] doc the document to validate
+      #
+      # @raise [ ArgumentError ] if the document is invalid.
+      def validate_search_index!(doc)
+        validate_search_index_keys!(doc.keys)
+        validate_search_index_name!(doc[:name] || doc['name'])
+        validate_search_index_definition!(doc[:definition] || doc['definition'])
+        doc
+      end
+
+      # Validates the keys of a search index document, ensuring that
+      # they are all valid.
+      #
+      # @param [ Array<String | Hash> ] keys the keys of a search index document
+      #
+      # @raise [ ArgumentError ] if the list contains any invalid keys
+      def validate_search_index_keys!(keys)
+        extras = keys - [ 'name', 'definition', :name, :definition ]
+
+        raise ArgumentError, "invalid keys in search index creation: #{extras.inspect}" if extras.any?
+      end
+
+      # Validates the name of a search index, ensuring that it is either a
+      # String or nil.
+      #
+      # @param [ nil | String ] name the name of a search index
+      #
+      # @raise [ ArgumentError ] if the name is not valid
+      def validate_search_index_name!(name)
+        return if name.nil? || name.is_a?(String)
+
+        raise ArgumentError, "search index name must be nil or a string (got #{name.inspect})"
+      end
+
+      # Validates the definition of a search index.
+      #
+      # @param [ Hash ] definition the definition of a search index
+      #
+      # @raise [ ArgumentError ] if the definition is not valid
+      def validate_search_index_definition!(definition)
+        return if definition.is_a?(Hash)
+
+        raise ArgumentError, "search index definition must be a Hash (got #{definition.inspect})"
+      end
+    end
+  end
+end

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).
       #