mongo 2.17.4 → 2.21.0

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/semaphore.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 # Copyright (C) 2018-2020 MongoDB Inc.
 #
@@ -23,7 +23,7 @@ module Mongo
   class Semaphore
     def initialize
       @lock = Mutex.new
-      @cv = ConditionVariable.new
+      @cv = ::ConditionVariable.new
     end
 
     # Waits for the semaphore to be signaled up to timeout seconds.

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

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2016-2023 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 Server
+    class AppMetadata
+      # Implements the logic from the handshake spec, for deducing and
+      # 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
+        # in the environment. (E.g. if the environment reports that it is
+        # running under both AWS and Azure.)
+        class TooManyEnvironments < Mongo::Error; end
+
+        # Error class for reporting that a required environment variable is
+        # missing.
+        class MissingVariable < Mongo::Error; end
+
+        # Error class for reporting that the wrong type was given for a
+        # field.
+        class TypeMismatch < Mongo::Error; end
+
+        # 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
+
+        # The mapping that determines which FaaS environment is active, based
+        # on which environment variable(s) are present.
+        DISCRIMINATORS = {
+          'AWS_EXECUTION_ENV' => { pattern: /^AWS_Lambda_/, name: 'aws.lambda' },
+          'AWS_LAMBDA_RUNTIME_API' => { name: 'aws.lambda' },
+          'FUNCTIONS_WORKER_RUNTIME' => { name: 'azure.func' },
+          'K_SERVICE' => { name: 'gcp.func' },
+          'FUNCTION_NAME' => { name: 'gcp.func' },
+          'VERCEL' => { name: 'vercel' },
+        }.freeze
+
+        # Describes how to coerce values of the specified type.
+        COERCIONS = {
+          string: ->(v) { String(v) },
+          integer: ->(v) { Integer(v) }
+        }.freeze
+
+        # Describes which fields are required for each FaaS environment,
+        # along with their expected types, and how they should be named in
+        # the handshake document.
+        FIELDS = {
+          'aws.lambda' => {
+            'AWS_REGION' => { field: :region, type: :string },
+            'AWS_LAMBDA_FUNCTION_MEMORY_SIZE' => { field: :memory_mb, type: :integer },
+          },
+
+          'azure.func' => {},
+
+          'gcp.func' => {
+            'FUNCTION_MEMORY_MB' => { field: :memory_mb, type: :integer },
+            'FUNCTION_TIMEOUT_SEC' => { field: :timeout_sec, type: :integer },
+            'FUNCTION_REGION' => { field: :region, type: :string },
+          },
+
+          'vercel' => {
+            'VERCEL_REGION' => { field: :region, type: :string },
+          },
+        }.freeze
+
+        # @return [ String | nil ] the name of the FaaS environment that was
+        #   detected, or nil if no valid FaaS environment was detected.
+        attr_reader :name
+
+        # @return [ Hash | nil ] the fields describing the detected FaaS
+        #   environment.
+        attr_reader :fields
+
+        # @return [ String | nil ] the error message explaining why a valid
+        #   FaaS environment was not detected, or nil if no error occurred.
+        #
+        # @note These error messagess are not to be propogated to the
+        #   user; they are intended only for troubleshooting and debugging.)
+        attr_reader :error
+
+        # Create a new AppMetadata::Environment object, initializing it from
+        # the current ENV variables. If no FaaS environment is detected, or
+        # 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_faas_fields
+          detect_container
+        rescue TooManyEnvironments => e
+          self.error = "too many environments detected: #{e.message}"
+        rescue MissingVariable => e
+          self.error = "missing environment variable: #{e.message}"
+        rescue TypeMismatch => e
+          self.error = e.message
+        rescue ValueTooLong => e
+          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
+        #   environment or not.
+        def faas?
+          @name != nil
+        end
+
+        # Queries whether the current environment is a valid AWS Lambda
+        # environment.
+        #
+        # @return [ true | false ] whether the environment is a AWS Lambda
+        #   environment or not.
+        def aws?
+          @name == 'aws.lambda'
+        end
+
+        # Queries whether the current environment is a valid Azure
+        # environment.
+        #
+        # @return [ true | false ] whether the environment is a Azure
+        #   environment or not.
+        def azure?
+          @name == 'azure.func'
+        end
+
+        # Queries whether the current environment is a valid GCP
+        # environment.
+        #
+        # @return [ true | false ] whether the environment is a GCP
+        #   environment or not.
+        def gcp?
+          @name == 'gcp.func'
+        end
+
+        # Queries whether the current environment is a valid Vercel
+        # environment.
+        #
+        # @return [ true | false ] whether the environment is a Vercel
+        #   environment or not.
+        def vercel?
+          @name == 'vercel'
+        end
+
+        # Compiles the detected environment information into a Hash.
+        #
+        # @return [ Hash ] the detected environment information.
+        def to_h
+          name ? fields.merge(name: name) : fields
+        end
+
+        private
+
+        # Searches the DESCRIMINATORS list to see which (if any) apply to
+        # the current environment.
+        #
+        # @return [ String | nil ] the name of the detected FaaS provider.
+        #
+        # @raise [ TooManyEnvironments ] if the environment contains
+        #   discriminating variables for more than one FaaS provider.
+        def detect_environment
+          matches = DISCRIMINATORS.keys.select { |k| discriminator_matches?(k) }
+          names = matches.map { |m| DISCRIMINATORS[m][:name] }.uniq
+
+          # From the spec:
+          # When variables for multiple ``client.env.name`` values are present,
+          # ``vercel`` takes precedence over ``aws.lambda``; any other
+          # combination MUST cause ``client.env`` to be entirely omitted.
+          return 'vercel' if names.sort == %w[ aws.lambda vercel ]
+          raise TooManyEnvironments, names.join(', ') if names.length > 1
+
+          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.
+        #
+        # @param [ String ] var the name of the environment variable
+        #
+        # @return [ true | false ] if the variable describes the current
+        #   environment or not.
+        def discriminator_matches?(var)
+          return false unless ENV[var]
+
+          disc = DISCRIMINATORS[var]
+          return true unless disc[:pattern]
+
+          disc[:pattern].match?(ENV[var])
+        end
+
+        # Extracts environment information from the current environment
+        # variables, based on the detected FaaS environment. Populates the
+        # {{@fields}} instance variable.
+        def populate_faas_fields
+          return unless name
+
+          FIELDS[name].each_with_object(@fields) do |(var, defn), fields|
+            fields[defn[:field]] = extract_field(var, defn)
+          end
+        end
+
+        # Extracts the named variable from the environment and validates it
+        # against its declared definition.
+        #
+        # @param [ String ] var The name of the environment variable to look
+        #   for.
+        # @param [ Hash ] definition The definition of the field that applies
+        #   to the named variable.
+        #
+        # @return [ Integer | String ] the validated and coerced value of the
+        #   given environment variable.
+        #
+        # @raise [ MissingVariable ] if the environment does not include a
+        #   variable required by the current FaaS provider.
+        # @raise [ ValueTooLong ] if a required variable is too long.
+        # @raise [ TypeMismatch ] if a required variable cannot be coerced to
+        #   the expected type.
+        def extract_field(var, definition)
+          raise MissingVariable, var unless ENV[var]
+          raise ValueTooLong, var if ENV[var].length > MAXIMUM_VALUE_LENGTH
+
+          COERCIONS[definition[:type]].call(ENV[var])
+        rescue ArgumentError
+          raise TypeMismatch,
+                "#{var} must be #{definition[:type]} (got #{ENV[var].inspect})"
+        end
+
+        # Sets the error message to the given value and sets the name to nil.
+        #
+        # @param [ String ] msg The error message to store.
+        def error=(msg)
+          @name = nil
+          @error = msg
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+# Copyright (C) 2016-2023 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 Server
+    class AppMetadata
+      # Implements the logic for building the platform string for the
+      # handshake.
+      #
+      # @api private
+      class Platform
+        # @return [ Mongo::Server::AppMetadata ] the metadata object to
+        #   reference when building the platform string.
+        attr_reader :metadata
+
+        # Create a new Platform object, referencing the given metadata object.
+        #
+        # @param [ Mongo::Server::AppMetadata ] metadata the metadata object
+        #   the reference when building the platform string.
+        def initialize(metadata)
+          @metadata = metadata
+        end
+
+        # Queries whether the current runtime is JRuby or not.
+        #
+        # @return [ true | false ] whether the runtime is JRuby or not.
+        def jruby?
+          BSON::Environment.jruby?
+        end
+
+        # Returns the list of Ruby versions that identify this runtime.
+        #
+        # @return [ Array<String> ] the list of ruby versions
+        def ruby_versions
+          if jruby?
+            [ "JRuby #{JRUBY_VERSION}", "like Ruby #{RUBY_VERSION}" ]
+          else
+            [ "Ruby #{RUBY_VERSION}" ]
+          end
+        end
+
+        # Returns the list of platform identifiers that identify this runtime.
+        #
+        # @return [ Array<String> ] the list of platform identifiers.
+        def platforms
+          [ RUBY_PLATFORM ].tap do |list|
+            list.push "JVM #{java_version}" if jruby?
+          end
+        end
+
+        # Returns the version of the current Java environment, or nil if not
+        # invoked with JRuby.
+        #
+        # @return [ String | nil ] the current Java version
+        def java_version
+          return nil unless jruby?
+
+          java.lang.System.get_property('java.version')
+        end
+
+        # Builds and returns the default platform list, for use when building
+        # the platform string.
+        #
+        # @return [ Array<String> ] the list of platform identifiers
+        def default_platform_list
+          [
+            metadata.platform,
+            *ruby_versions,
+            *platforms,
+            RbConfig::CONFIG['build']
+          ]
+        end
+
+        # Returns a single letter representing the purpose reported to the
+        # metadata, or nil if no purpose was specified.
+        #
+        # @return [ String | nil ] the code representing the purpose
+        def purpose
+          return nil unless metadata.purpose
+
+          metadata.purpose.to_s[0].upcase
+        end
+
+        # Builds and returns the platform string by concatenating relevant
+        # values together.
+        #
+        # @return [ String ] the platform string
+        def to_s
+          primary = [ *default_platform_list, purpose ].compact.join(', ')
+          list = [ primary ]
+
+          metadata.wrapping_libraries&.each do |library|
+            list << (library[:platform] || '')
+          end
+
+          list.join('|')
+        end
+      end
+    end
+  end
+end