mongo 2.19.2 → 2.19.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 455d5b9685fd2cefa18a1c37e81ddb97a177ac8e40b9298945e4f126ac9ce093
-  data.tar.gz: fab0630edde803ab5125536159e8fbd12d3f0bac233e87d40ea1e414287145ac
+  metadata.gz: '0916a285c62c2e70c94532ca2ed61af6bfcb1ead971a2be825aefbde560209c3'
+  data.tar.gz: a9db987bb6f1e2b7e9882c86472bc2c8b10eca0d4bdca9de2a37968de086d8f3
 SHA512:
-  metadata.gz: f3db945520bf825c31fcd7a21295b03257b1ee01d3d2eb6903f69ae6dfdbb0834516c8214227196702f88e087754780a876941eb5a3ac8f0861bff40a3e55a07
-  data.tar.gz: 73ea3f0a4fc86ba9922c1054f925db03eab8ac3da47bd9b9daae5006af1f32299c3d1a45104623126db5c89e41bf3ddbfe82dd641ea77dce6d8936a5297a1880
+  metadata.gz: ab6a8e7e008174f346f1acd96bb073a39cd4fbdd2a70e44f63f8dcdc421c4d38ba9277cc9c50099c944599886e53230597bdab8bd4c861de29af2bd66dd2be76
+  data.tar.gz: 8fe9155b17bbb9b57021eabd7e2211baf2cb0002b211900e8564e0b1c2f9e894bf726a037b1e8b72e6dd55251edefe1e81fd8c3ea61aacd0fd5d7eb76cbc4163

data/lib/mongo/collection.rb

@@ -725,13 +725,35 @@ module Mongo
     #
     # @option options [ Session ] :session The session to use.
     #
-    # @return [ View::Index ] The index view.
+    # @return [ Index::View ] The index view.
     #
     # @since 2.0.0
     def indexes(options = {})
       Index::View.new(self, options)
     end
 
+    # Get a view of all search indexes for this collection. Can be iterated or
+    # operated on directly. If id or name are given, the iterator will return
+    # only the indicated index. For all other operations, id and name are
+    # ignored.
+    #
+    # @note Only one of id or name may be given; it is an error to specify both,
+    #   although both may be omitted safely.
+    #
+    # @param [ Hash ] options The options to use to configure the view.
+    #
+    # @option options [ String ] :id The id of the specific index to query (optional)
+    # @option options [ String ] :name The name of the specific index to query (optional)
+    # @option options [ Hash ] :aggregate The options hash to pass to the
+    #    aggregate command (optional)
+    #
+    # @return [ SearchIndex::View ] The search index view.
+    #
+    # @since 2.0.0
+    def search_indexes(options = {})
+      SearchIndex::View.new(self, options)
+    end
+
     # Get a pretty printed string inspection for the collection.
     #
     # @example Inspect the collection.

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Mongo
+  module Operation
+    class CreateSearchIndexes
+      # A MongoDB createSearchIndexes 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 createSearchIndexes operation.
+        #
+        # @param [ Mongo::Server ] _server the server that will receive the
+        #   command
+        #
+        # @return [ Hash ] the selector
+        def selector(_server)
+          {
+            createSearchIndexes: coll_name,
+            :$db => db_name,
+            indexes: indexes,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/mongo/operation/create_search_indexes.rb

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

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mongo
+  module Operation
+    class DropSearchIndex
+      # A MongoDB createSearchIndexes 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 dropSearchIndex operation.
+        #
+        # @param [ Mongo::Server ] _server the server that will receive the
+        #   command
+        #
+        # @return [ Hash ] the selector
+        def selector(_server)
+          {
+            dropSearchIndex: coll_name,
+            :$db => db_name,
+          }.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/drop_search_index.rb

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

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

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

data/lib/mongo.rb

@@ -64,6 +64,7 @@ require 'mongo/client_encryption'
 require 'mongo/dbref'
 require 'mongo/grid'
 require 'mongo/index'
+require 'mongo/search_index/view'
 require 'mongo/lint'
 require 'mongo/query_cache'
 require 'mongo/server'

data/spec/atlas/atlas_connectivity_spec.rb

@@ -7,11 +7,7 @@ describe 'Atlas connectivity' do
   let(:uri) { ENV['ATLAS_URI'] }
   let(:client) { Mongo::Client.new(uri) }
 
-  before do
-    if uri.nil?
-      skip "ATLAS_URI not set in environment"
-    end
-  end
+  require_atlas
 
   describe 'connection to Atlas' do
     it 'runs ismaster successfully' do

data/spec/atlas/operations_spec.rb

@@ -7,11 +7,7 @@ describe 'Operations' do
   let(:uri) { ENV['ATLAS_URI'] }
   let(:client) { Mongo::Client.new(uri) }
 
-  before do
-    if uri.nil?
-      skip "ATLAS_URI not set in environment"
-    end
-  end
+  require_atlas
 
   describe 'ping' do
     it 'works' do

data/spec/integration/search_indexes_prose_spec.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+class SearchIndexHelper
+  attr_reader :client, :collection_name
+
+  def initialize(client)
+    @client = client
+
+    # https://github.com/mongodb/specifications/blob/master/source/index-management/tests/README.rst#id4
+    # "...each test uses a randomly generated collection name.  Drivers may
+    # generate this collection name however they like, but a suggested
+    # implementation is a hex representation of an ObjectId..."
+    @collection_name = BSON::ObjectId.new.to_s
+  end
+
+  # `soft_create` means to create the collection object without forcing it to
+  # be created in the database.
+  def collection(soft_create: false)
+    @collection ||= client.database[collection_name].tap do |collection|
+      collection.create unless soft_create
+    end
+  end
+
+  # Wait for all of the indexes with the given names to be ready; then return
+  # the list of index definitions corresponding to those names.
+  def wait_for(*names, &condition)
+    timeboxed_wait do
+      result = collection.search_indexes
+      return filter_results(result, names) if names.all? { |name| ready?(result, name, &condition) }
+    end
+  end
+
+  # Wait until all of the indexes with the given names are absent from the
+  # search index list.
+  def wait_for_absense_of(*names)
+    names.each do |name|
+      timeboxed_wait do
+        break if collection.search_indexes(name: name).empty?
+      end
+    end
+  end
+
+  private
+
+  def timeboxed_wait(step: 5, max: 300)
+    start = Mongo::Utils.monotonic_time
+
+    loop do
+      yield
+
+      sleep step
+      raise Timeout::Error, 'wait took too long' if Mongo::Utils.monotonic_time - start > max
+    end
+  end
+
+  # Returns true if the list of search indexes includes one with the given name,
+  # which is ready to be queried.
+  def ready?(list, name, &condition)
+    condition ||= ->(index) { index['queryable'] }
+    list.any? { |index| index['name'] == name && condition[index] }
+  end
+
+  def filter_results(result, names)
+    result.select { |index| names.include?(index['name']) }
+  end
+end
+
+describe 'Mongo::Collection#search_indexes prose tests' do
+  # https://github.com/mongodb/specifications/blob/master/source/index-management/tests/README.rst#id5
+  # "These tests must run against an Atlas cluster with a 7.0+ server."
+  require_atlas
+
+  let(:client) do
+    Mongo::Client.new(
+      ENV['ATLAS_URI'],
+      database: SpecConfig.instance.test_db,
+      ssl: true,
+      ssl_verify: true
+    )
+  end
+
+  let(:helper) { SearchIndexHelper.new(client) }
+
+  let(:name) { 'test-search-index' }
+  let(:definition) { { 'mappings' => { 'dynamic' => false } } }
+  let(:create_index) { helper.collection.search_indexes.create_one(definition, name: name) }
+
+  # Case 1: Driver can successfully create and list search indexes
+  context 'when creating and listing search indexes' do
+    let(:index) { helper.wait_for(name).first }
+
+    it 'succeeds' do
+      expect(create_index).to be == name
+      expect(index['latestDefinition']).to be == definition
+    end
+  end
+
+  # Case 2: Driver can successfully create multiple indexes in batch
+  context 'when creating multiple indexes in batch' do
+    let(:specs) do
+      [
+        { 'name' => 'test-search-index-1', 'definition' => definition },
+        { 'name' => 'test-search-index-2', 'definition' => definition }
+      ]
+    end
+
+    let(:names) { specs.map { |spec| spec['name'] } }
+    let(:create_indexes) { helper.collection.search_indexes.create_many(specs) }
+
+    let(:indexes) { helper.wait_for(*names) }
+
+    let(:index1) { indexes[0] }
+    let(:index2) { indexes[1] }
+
+    it 'succeeds' do
+      expect(create_indexes).to be == names
+      expect(index1['latestDefinition']).to be == specs[0]['definition']
+      expect(index2['latestDefinition']).to be == specs[1]['definition']
+    end
+  end
+
+  # Case 3: Driver can successfully drop search indexes
+  context 'when dropping search indexes' do
+    it 'succeeds' do
+      expect(create_index).to be == name
+      helper.wait_for(name)
+
+      helper.collection.search_indexes.drop_one(name: name)
+
+      expect { helper.wait_for_absense_of(name) }.not_to raise_error
+    end
+  end
+
+  # Case 4: Driver can update a search index
+  context 'when updating search indexes' do
+    let(:new_definition) { { 'mappings' => { 'dynamic' => true } } }
+
+    let(:index) do
+      helper
+        .wait_for(name) { |idx| idx['queryable'] && idx['status'] == 'READY' }
+        .first
+    end
+
+    # rubocop:disable RSpec/ExampleLength
+    it 'succeeds' do
+      expect(create_index).to be == name
+      helper.wait_for(name)
+
+      expect do
+        helper.collection.search_indexes.update_one(new_definition, name: name)
+      end.not_to raise_error
+
+      expect(index['latestDefinition']).to be == new_definition
+    end
+    # rubocop:enable RSpec/ExampleLength
+  end
+
+  # Case 5: dropSearchIndex suppresses namespace not found errors
+  context 'when dropping a non-existent search index' do
+    it 'ignores `namespace not found` errors' do
+      collection = helper.collection(soft_create: true)
+      expect { collection.search_indexes.drop_one(name: name) }
+        .not_to raise_error
+    end
+  end
+end