mongo 2.10.5 → 2.15.1

data/lib/mongo/crypt/status.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+## Copyright (C) 2019-2020 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.
+
+require 'ffi'
+
+module Mongo
+  module Crypt
+
+    # A wrapper around mongocrypt_status_t, representing the status of
+    # a mongocrypt_t handle.
+    #
+    # @api private
+    class Status
+      # Create a new Status object
+      #
+      # @param [ FFI::Pointer | nil ] pointer A pointer to an existing
+      #   mongocrypt_status_t object. Defaults to nil.
+      #
+      # @note When initializing a Status object with a pointer, it is
+      # recommended that you use the #self.from_pointer method
+      def initialize(pointer: nil)
+        # If a pointer is passed in, this class is not responsible for
+        # destroying that pointer and deallocating data.
+        #
+        # FFI::AutoPointer uses a custom release strategy to automatically free
+        # the pointer once this object goes out of scope
+        @status = pointer || FFI::AutoPointer.new(
+                              Binding.mongocrypt_status_new,
+                              Binding.method(:mongocrypt_status_destroy)
+                            )
+      end
+
+      # Initialize a Status object from an existing pointer to a
+      # mongocrypt_status_t object.
+      #
+      # @param [ FFI::Pointer ] pointer A pointer to an existing
+      #   mongocrypt_status_t object
+      #
+      # @return [ Mongo::Crypt::Status ] A new Status object
+      def self.from_pointer(pointer)
+        self.new(pointer: pointer)
+      end
+
+      # Set a label, code, and message on the Status
+      #
+      # @param [ Symbol ] label One of :ok, :error_client, or :error_kms
+      # @param [ Integer ] code
+      # @param [ String ] message
+      #
+      # @return [ Mongo::Crypt::Status ] returns self
+      def update(label, code, message)
+        unless [:ok, :error_client, :error_kms].include?(label)
+          raise ArgumentError.new(
+            "#{label} is an invalid value for a Mongo::Crypt::Status label. " +
+            "Label must have one of the following values: :ok, :error_client, :error_kms"
+          )
+        end
+
+        message_length = message ? message.bytesize + 1 : 0
+        Binding.mongocrypt_status_set(@status, label, code, message, message_length)
+
+        self
+      end
+
+      # Return the label of the status
+      #
+      # @return [ Symbol ] The status label, either :ok, :error_kms, or :error_client,
+      #   defaults to :ok
+      def label
+        Binding.mongocrypt_status_type(@status)
+      end
+
+      # Return the integer code associated with the status
+      #
+      # @return [ Integer ] The status code, defaults to 0
+      def code
+        Binding.mongocrypt_status_code(@status)
+      end
+
+      # Return the status message
+      #
+      # @return [ String ] The status message, defaults to empty string
+      def message
+        message = Binding.mongocrypt_status_message(@status, nil)
+        message || ''
+      end
+
+      # Checks whether the status is labeled :ok
+      #
+      # @return [ Boolean ] Whether the status is :ok
+      def ok?
+        Binding.mongocrypt_status_ok(@status)
+      end
+
+      # Returns the reference to the underlying mongocrypt_status_t
+      # object
+      #
+      # @return [ FFI::Pointer ] Pointer to the underlying mongocrypt_status_t oject
+      def ref
+        @status
+      end
+
+      # Raises a Mongo::Error:CryptError corresponding to the
+      # information stored in this status
+      #
+      # Does nothing if self.ok? is true
+      def raise_crypt_error
+        return if ok?
+
+        if label == :error_kms
+          error = Error::KmsError.new(message, code: code)
+        else
+          error = Error::CryptError.new(message, code: code)
+        end
+
+        raise error
+      end
+    end
+  end
+end

data/lib/mongo/crypt.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2019-2020 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
+  module Crypt
+    autoload(:Binding, 'mongo/crypt/binding')
+    autoload(:Binary, 'mongo/crypt/binary')
+    autoload(:Status, 'mongo/crypt/status')
+    autoload(:Hooks, 'mongo/crypt/hooks')
+    autoload(:Handle, 'mongo/crypt/handle')
+    autoload(:KmsContext, 'mongo/crypt/kms_context')
+    autoload(:Context, 'mongo/crypt/context')
+    autoload(:DataKeyContext, 'mongo/crypt/data_key_context')
+    autoload(:ExplicitEncryptionContext, 'mongo/crypt/explicit_encryption_context')
+    autoload(:AutoEncryptionContext, 'mongo/crypt/auto_encryption_context')
+    autoload(:ExplicitDecryptionContext, 'mongo/crypt/explicit_decryption_context')
+    autoload(:AutoDecryptionContext, 'mongo/crypt/auto_decryption_context')
+    autoload(:EncryptionIO, 'mongo/crypt/encryption_io')
+    autoload(:ExplicitEncrypter, 'mongo/crypt/explicit_encrypter')
+    autoload(:AutoEncrypter, 'mongo/crypt/auto_encrypter')
+  end
+end

data/lib/mongo/cursor/builder/get_more_command.rb

@@ -1,4 +1,7 @@
-# Copyright (C) 2015-2019 MongoDB, Inc.
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2015-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/cursor/builder/kill_cursors_command.rb

@@ -1,4 +1,7 @@
-# Copyright (C) 2015-2019 MongoDB, Inc.
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2015-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/cursor/builder/op_get_more.rb

@@ -1,4 +1,7 @@
-# Copyright (C) 2015-2019 MongoDB, Inc.
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2015-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/cursor/builder/op_kill_cursors.rb

@@ -1,4 +1,7 @@
-# Copyright (C) 2015-2019 MongoDB, Inc.
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2015-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/cursor/builder.rb

@@ -1,4 +1,7 @@
-# Copyright (C) 2015-2019 MongoDB, Inc.
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2015-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/mongo/cursor.rb

@@ -1,4 +1,7 @@
-# Copyright (C) 2014-2019 MongoDB, Inc.
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2014-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -19,8 +22,9 @@ module Mongo
   # Client-side representation of an iterator over a query result set on
   # the server.
   #
-  # A +Cursor+ is not created directly by a user. Rather, +CollectionView+
-  # creates a +Cursor+ in an Enumerable module method.
+  # +Cursor+ objects are not directly exposed to application code. Rather,
+  # +Collection::View+ exposes the +Enumerable+ interface to the applications,
+  # and the enumerator is backed by a +Cursor+ instance.
   #
   # @example Get an array of 5 users named Emily.
   #   users.find({:name => 'Emily'}).limit(5).to_a
@@ -28,8 +32,7 @@ module Mongo
   # @example Call a block on each user doc.
   #   users.find.each { |doc| puts doc }
   #
-  # @note The +Cursor+ API is semipublic.
-  # @api semipublic
+  # @api private
   class Cursor
     extend Forwardable
     include Enumerable
@@ -69,13 +72,16 @@ module Mongo
       @view = view
       @server = server
       @initial_result = result
+      @namespace = result.namespace
       @remaining = limit if limited?
       @cursor_id = result.cursor_id
-      @coll_name = nil
+      if @cursor_id.nil?
+        raise ArgumentError, 'Cursor id must be present in the result'
+      end
       @options = options
       @session = @options[:session]
-      register
-      if @cursor_id && @cursor_id > 0
+      unless closed?
+        register
         ObjectSpace.define_finalizer(self, self.class.finalize(@cursor_id,
           cluster,
           kill_cursors_op_spec,
@@ -122,6 +128,10 @@ module Mongo
 
     # Iterate through documents returned from the query.
     #
+    # A cursor may be iterated at most once. Incomplete iteration is also
+    # allowed. Attempting to iterate the cursor more than once raises
+    # InvalidCursorOperation.
+    #
     # @example Iterate over the documents in the cursor.
     #   cursor.each do |doc|
     #     ...
@@ -131,6 +141,7 @@ module Mongo
     #
     # @since 2.0.0
     def each
+
       # If we already iterated past the first batch (i.e., called get_more
       # at least once), the cursor on the server side has advanced past
       # the first batch and restarting iteration from the beginning by
@@ -142,19 +153,29 @@ module Mongo
       # end of previous iteration or would always restart from the
       # beginning.
       if @get_more_called
-        raise NotImplementedError, 'Cannot restart iteration of a cursor which issued a getMore'
+        raise Error::InvalidCursorOperation, 'Cannot restart iteration of a cursor which issued a getMore'
       end
 
       # To maintain compatibility with pre-2.10 driver versions, reset
       # the documents array each time a new iteration is started.
       @documents = nil
 
-      loop do
-        document = try_next
-        yield document if document
+      if block_given?
+        # StopIteration raised by try_next ends this loop.
+        loop do
+          document = try_next
+          yield document if document
+        end
+        self
+      else
+        documents = []
+        # StopIteration raised by try_next ends this loop.
+        loop do
+          document = try_next
+          documents << document if document
+        end
+        documents
       end
-    rescue StopIteration => e
-      return self
     end
 
     # Return one document from the query, if one is available.
@@ -168,6 +189,10 @@ module Mongo
     # @note This method is experimental and subject to change.
     #
     # @return [ BSON::Document | nil ] A document.
+    #
+    # @raise [ StopIteration ] Raised on the calls after the cursor had been
+    #   completely iterated.
+    #
     # @api private
     def try_next
       if @documents.nil?
@@ -184,13 +209,15 @@ module Mongo
         # On empty batches, we cache the batch resume token
         cache_batch_resume_token
 
-        if more?
+        unless closed?
           if exhausted?
-            kill_cursors
+            close
+            @fully_iterated = true
             raise StopIteration
           end
           @documents = get_more
         else
+          @fully_iterated = true
           raise StopIteration
         end
       else
@@ -207,6 +234,9 @@ module Mongo
       # over the last document, or if the batch is empty
       if @documents.size <= 1
         cache_batch_resume_token
+        if closed?
+          @fully_iterated = true
+        end
       end
 
       return @documents.shift
@@ -233,7 +263,29 @@ module Mongo
     #
     # @since 2.2.0
     def closed?
-      !more?
+      # @cursor_id should in principle never be nil
+      @cursor_id.nil? || @cursor_id == 0
+    end
+
+    # Closes this cursor, freeing any associated resources on the client and
+    # the server.
+    #
+    # @return [ nil ] Always nil.
+    #
+    # @raise [ Error::OperationFailure ] If the server cursor close fails.
+    # @raise [ Error::SocketError | Error::SocketTimeoutError ] When there is a network error.
+    def close
+      return if closed?
+
+      unregister
+      read_with_one_retry do
+        kill_cursors_operation.execute(@server, context: Operation::Context.new(client: client, session: @session))
+      end
+
+      nil
+    ensure
+      end_session
+      @cursor_id = 0
     end
 
     # Get the parsed collection name.
@@ -245,7 +297,20 @@ module Mongo
     #
     # @since 2.2.0
     def collection_name
-      @coll_name || collection.name
+      # In most cases, this will be equivalent to the name of the collection
+      # object in the driver. However, in some cases (e.g. when connected
+      # to an Atlas Data Lake), the namespace returned by the find command
+      # may be different, which is why we want to use the collection name based
+      # on the namespace in the command result.
+      if @namespace
+        # Often, the namespace will be in the format "database.collection".
+        # However, sometimes the collection name will contain periods, which
+        # is why this method joins all the namespace components after the first.
+        ns_components = @namespace.split('.')
+        ns_components[1...ns_components.length].join('.')
+      else
+        collection.name
+      end
     end
 
     # Get the cursor id.
@@ -289,7 +354,12 @@ module Mongo
       # doing so may result in silent data loss, the driver no longer retries
       # getMore operations in any circumstance.
       # https://github.com/mongodb/specifications/blob/master/source/retryable-reads/retryable-reads.rst#qa
-      process(get_more_operation.execute(@server))
+      process(get_more_operation.execute(@server, context: Operation::Context.new(client: client, session: @session)))
+    end
+
+    # @api private
+    def fully_iterated?
+      !!@fully_iterated
     end
 
     private
@@ -309,7 +379,7 @@ module Mongo
     end
 
     def get_more_operation
-      if @server.features.find_command_enabled?
+      if @server.with_connection { |connection| connection.features }.find_command_enabled?
         spec = Builder::GetMoreCommand.new(self, @session).specification
       else
         spec = Builder::OpGetMore.new(self).specification
@@ -317,16 +387,6 @@ module Mongo
       Operation::GetMore.new(spec)
     end
 
-    def kill_cursors
-      unregister
-      read_with_one_retry do
-        kill_cursors_operation.execute(@server)
-      end
-    ensure
-      end_session
-      @cursor_id = 0
-    end
-
     def end_session
       @session.end_session if @session && @session.implicit?
     end
@@ -336,7 +396,7 @@ module Mongo
     end
 
     def kill_cursors_op_spec
-      if @server.features.find_command_enabled?
+      if @server.with_connection { |connection| connection.features }.find_command_enabled?
         Builder::KillCursorsCommand.new(self).specification
       else
         Builder::OpKillCursors.new(self).specification
@@ -347,21 +407,20 @@ module Mongo
       limit ? limit > 0 : false
     end
 
-    def more?
-      @cursor_id != 0
-    end
-
     def process(result)
       @remaining -= result.returned_count if limited?
-      @coll_name ||= result.namespace.sub("#{database.name}.", '') if result.namespace
-      unregister if result.cursor_id == 0
+      # #process is called for the first batch of results. In this case
+      # the @cursor_id may be zero (all results fit in the first batch).
+      # Thus we need to check both @cursor_id and the cursor_id of the result
+      # prior to calling unregister here.
+      unregister if !closed? && result.cursor_id == 0
       @cursor_id = result.cursor_id
 
       if result.respond_to?(:post_batch_resume_token)
         @post_batch_resume_token = result.post_batch_resume_token
       end
 
-      end_session if !more?
+      end_session if closed?
 
       # Since our iteration code mutates the documents array by calling #shift
       # on it, duplicate the documents here to permit restarting iteration

data/lib/mongo/database/view.rb

@@ -1,4 +1,7 @@
-# Copyright (C) 2014-2019 MongoDB, Inc.
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2014-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -47,6 +50,13 @@ module Mongo
       #
       # @option options [ Integer ] :batch_size  The batch size for results
       #   returned from the listCollections command.
+      # @option options [ Hash ] :filter A filter on the collections returned.
+      # @option options [ true, false ] :authorized_collections A flag, when
+      #   set to true, that allows a user without the required privilege
+      #   to run the command when access control is enforced
+      #
+      #   See https://docs.mongodb.com/manual/reference/command/listCollections/
+      #   for more information and usage.
       #
       # @return [ Array<String> ] The names of all non-system collections.
       #
@@ -55,10 +65,10 @@ module Mongo
         @batch_size = options[:batch_size]
         session = client.send(:get_session, options)
         cursor = read_with_retry_cursor(session, ServerSelector.primary, self) do |server|
-          send_initial_query(server, session, name_only: true)
+          send_initial_query(server, session, options.merge(name_only: true))
         end
         cursor.map do |info|
-          if cursor.server.features.list_collections_enabled?
+          if cursor.server.with_connection { |connection| connection.features }.list_collections_enabled?
             info['name']
           else
             (info['name'] &&
@@ -78,12 +88,25 @@ module Mongo
       # @example Get info on each collection.
       #   database.list_collections
       #
+      # @param [ Hash ] options
+      #
+      # @option options [ Hash ] :filter A filter on the collections returned.
+      # @option options [ true, false ] :name_only Indicates whether command
+      #   should return just collection/view names and type or return both the
+      #   name and other information
+      # @option options [ true, false ] :authorized_collections A flag, when
+      #   set to true and used with nameOnly: true, that allows a user without the
+      #   required privilege to run the command when access control is enforced
+      #
+      #   See https://docs.mongodb.com/manual/reference/command/listCollections/
+      #   for more information and usage.
+      #
       # @return [ Array<Hash> ] Info for each collection in the database.
       #
       # @since 2.0.5
-      def list_collections
+      def list_collections(options = {})
         session = client.send(:get_session)
-        collections_info(session, ServerSelector.primary)
+        collections_info(session, ServerSelector.primary, options)
       end
 
       # Create the new database view.
@@ -157,7 +180,11 @@ module Mongo
             cursor: batch_size ? { batchSize: batch_size } : {} },
           db_name: @database.name,
           session: session
-        }.tap { |spec| spec[:selector][:nameOnly] = true if options[:name_only] }
+        }.tap do |spec|
+          spec[:selector][:nameOnly] = true if options[:name_only]
+          spec[:selector][:filter] = options[:filter] if options[:filter]
+          spec[:selector][:authorizedCollections] = true if options[:authorized_collections]
+        end
       end
 
       def initial_query_op(session, options = {})
@@ -165,7 +192,7 @@ module Mongo
       end
 
       def send_initial_query(server, session, options = {})
-        initial_query_op(session, options).execute(server)
+        initial_query_op(session, options).execute(server, context: Operation::Context.new(client: client, session: session))
       end
     end
   end