mongo 2.17.3 → 2.18.0.beta1

data/lib/mongo/crypt/kms/local.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2019-2021 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
+    module KMS
+      module Local
+        # Local KMS Credentials object contains credentials for using local KMS provider.
+        #
+        # @api private
+        class Credentials
+          include KMS::Validations
+
+          # @return [ String ] Master key.
+          attr_reader :key
+
+          FORMAT_HINT = "Local KMS provider options must be in the format: " +
+                        "{ key: 'MASTER-KEY' }"
+
+          # Creates a local KMS credentials object form a parameters hash.
+          #
+          # @param [ Hash ] opts A hash that contains credentials for
+          #   local KMS provider
+          # @option opts [ String ] :key Master key.
+          #
+          # @raise [ ArgumentError ] If required options are missing or incorrectly
+          #   formatted.
+          def initialize(opts)
+            @key = validate_param(:key, opts, FORMAT_HINT)
+          end
+
+          # @return [ BSON::Document ] Local KMS credentials in libmongocrypt format.
+          def to_document
+            BSON::Document.new({
+              key: BSON::Binary.new(@key, :generic),
+            })
+          end
+        end
+
+        # Local KMS master key document object contains KMS master key parameters.
+        #
+        # @api private
+        class MasterKeyDocument
+
+          # Creates a master key document object form a parameters hash.
+          # This empty method is to keep a uniform interface for all KMS providers.
+          def initialize(_opts)
+          end
+
+          # Convert master key document object to a BSON document in libmongocrypt format.
+          #
+          # @return [ BSON::Document ] Local KMS credentials in libmongocrypt format.
+          def to_document
+            BSON::Document.new({ provider: "local" })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongo/crypt/kms/master_key_document.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2019-2021 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
+    module KMS
+
+      # KMS master key document object contains KMS master key parameters
+      # that are used for creation of data keys.
+      #
+      # @api private
+      class MasterKeyDocument
+
+        # Known KMS provider names.
+        KMS_PROVIDERS = %w(aws azure gcp kmip local).freeze
+
+        # Creates a master key document object form a parameters hash.
+        #
+        # @param [ String ] kms_provider. KMS provider name.
+        # @param [ Hash ] options A hash that contains master key options for
+        #   the KMS provider.
+        #   Required parameters for KMS providers are described in corresponding
+        #   classes inside Mongo::Crypt::KMS module.
+        #
+        # @raise [ ArgumentError ] If required options are missing or incorrectly.
+        def initialize(kms_provider, options)
+          if options.nil?
+            raise ArgumentError.new('Key document options must not be nil')
+          end
+          master_key = options[:master_key]
+          @key_document = case kms_provider.to_s
+            when 'aws' then KMS::AWS::MasterKeyDocument.new(master_key)
+            when 'azure' then KMS::Azure::MasterKeyDocument.new(master_key)
+            when 'gcp' then KMS::GCP::MasterKeyDocument.new(master_key)
+            when 'kmip' then KMS::KMIP::MasterKeyDocument.new(master_key)
+            when 'local' then KMS::Local::MasterKeyDocument.new(master_key)
+            else
+              raise ArgumentError.new("KMS provider must be one of #{KMS_PROVIDERS}")
+          end
+        end
+
+        # Convert master key document object to a BSON document in libmongocrypt format.
+        #
+        # @return [ BSON::Document ] Master key document as BSON document.
+        def to_document
+          @key_document.to_document
+        end
+      end
+    end
+  end
+end

data/lib/mongo/crypt/kms.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Copyright (C) 2019-2021 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
+    module KMS
+      # This module contains helper methods for validating KMS parameters.
+      #
+      # @api private
+      module Validations
+        # Validate if a KMS parameter is valid.
+        #
+        # @param [ Symbol ] key The parameter name.
+        # @param [ Hash ] opts Hash should contain the parameter under the key.
+        # @param [ Boolean ] required Whether the parameter is required or not.
+        #   Non-required parameters can be nil.
+        #
+        # @return [ String | nil ] String parameter value or nil if a
+        #   non-required parameter is missing.
+        #
+        # @raise [ ArgumentError ] If required options are missing or incorrectly
+        #   formatted.
+        def validate_param(key, opts, format_hint, required: true)
+          value = opts.fetch(key)
+          return nil if value.nil? && !required
+          if value.nil?
+            raise ArgumentError.new(
+              "The #{key} option must be a String with at least one character; " \
+              "currently have nil"
+            )
+          end
+          unless value.is_a?(String)
+            raise ArgumentError.new(
+              "The #{key} option must be a String with at least one character; " \
+              "currently have #{value}"
+            )
+          end
+          if value.empty?
+            raise ArgumentError.new(
+              "The #{key} option must be a String with at least one character; " \
+              "it is currently an empty string"
+            )
+          end
+          value
+        rescue KeyError
+          if required
+            raise ArgumentError.new(
+              "The specified KMS provider options are invalid: #{opts}. " +
+              format_hint
+            )
+          else
+            nil
+          end
+        end
+
+        # Validate KMS TLS options.
+        #
+        # @param [ Hash | nil ] options TLS options to connect to KMS
+        #   providers. Keys of the hash should be KSM provider names; values
+        #   should be hashes of TLS connection options. The options are equivalent
+        #   to TLS connection options of Mongo::Client.
+        #
+        # @return [ Hash ] Provided TLS options if valid.
+        #
+        # @raise [ ArgumentError ] If required options are missing or incorrectly
+        #   formatted.
+        def validate_tls_options(options)
+          opts = options || {}
+          opts.each do |provider, provider_opts|
+            if provider_opts[:ssl] == false || opts[:tls] == false
+              raise ArgumentError.new(
+                "Incorrect TLS options for #{provider}: TLS is required"
+              )
+            end
+            %i(
+              ssl_verify_certificate
+              ssl_verify_hostname
+              ssl_verify_ocsp_endpoint
+            ).each do |opt|
+              if provider_opts[opt] == false
+                raise ArgumentError.new(
+                  "Incorrect TLS options for #{provider}: " +
+                  'Insecure TLS options prohibited, ' +
+                  "#{opt} cannot be set to false for KMS"
+                )
+              end
+            end
+          end
+          opts
+        end
+        module_function :validate_tls_options
+      end
+    end
+  end
+end
+
+require "mongo/crypt/kms/credentials"
+require "mongo/crypt/kms/master_key_document"
+require 'mongo/crypt/kms/aws'
+require 'mongo/crypt/kms/azure'
+require 'mongo/crypt/kms/gcp'
+require 'mongo/crypt/kms/kmip'
+require 'mongo/crypt/kms/local'

data/lib/mongo/crypt.rb

@@ -32,5 +32,6 @@ module Mongo
     autoload(:EncryptionIO, 'mongo/crypt/encryption_io')
     autoload(:ExplicitEncrypter, 'mongo/crypt/explicit_encrypter')
     autoload(:AutoEncrypter, 'mongo/crypt/auto_encrypter')
+    autoload(:KMS, 'mongo/crypt/kms')
   end
 end

data/lib/mongo/cursor/kill_spec.rb

@@ -25,22 +25,36 @@ module Mongo
     # @api private
     class KillSpec
 
-      def initialize(cursor_id:, coll_name:, db_name:, service_id:, server_address:)
+      def initialize(
+        cursor_id:,
+        coll_name:,
+        db_name:,
+        connection_global_id:,
+        server_address:,
+        session:
+      )
         @cursor_id = cursor_id
         @coll_name = coll_name
         @db_name = db_name
-        @service_id = service_id
+        @connection_global_id = connection_global_id
         @server_address = server_address
+        @session = session
       end
 
-      attr_reader :cursor_id, :coll_name, :db_name, :service_id, :server_address
+      attr_reader :cursor_id,
+      :coll_name,
+      :db_name,
+      :connection_global_id,
+      :server_address,
+      :session
 
       def ==(other)
         cursor_id == other.cursor_id &&
           coll_name == other.coll_name &&
           db_name == other.db_name &&
-          service_id == other.service_id &&
-          server_address == other.server_address
+          connection_global_id == other.connection_global_id &&
+          server_address == other.server_address &&
+          session == other.session
       end
 
       def eql?(other)
@@ -48,7 +62,14 @@ module Mongo
       end
 
       def hash
-        [cursor_id, coll_name, db_name, service_id, server_address].compact.hash
+        [
+          cursor_id,
+          coll_name,
+          db_name,
+          connection_global_id,
+          server_address,
+          session,
+        ].compact.hash
       end
     end
   end

data/lib/mongo/cursor.rb

@@ -80,13 +80,13 @@ module Mongo
       if @cursor_id.nil?
         raise ArgumentError, 'Cursor id must be present in the result'
       end
+      @connection_global_id = result.connection_global_id
       @options = options
       @session = @options[:session]
       unless closed?
         register
-        ObjectSpace.define_finalizer(self, self.class.finalize(kill_spec(server),
-          cluster,
-          @session))
+        ObjectSpace.define_finalizer(self, self.class.finalize(kill_spec(@connection_global_id),
+          cluster))
       end
     end
 
@@ -101,18 +101,16 @@ module Mongo
     #
     # @param [ Cursor::KillSpec ] kill_spec The KillCursor operation specification.
     # @param [ Mongo::Cluster ] cluster The cluster associated with this cursor and its server.
-    # @param [ Mongo::Server ] server The server to send the killCursors operation to.
     #
     # @return [ Proc ] The Finalizer.
     #
     # @api private
-    def self.finalize(kill_spec, cluster, session)
+    def self.finalize(kill_spec, cluster)
       unless KillSpec === kill_spec
         raise ArgumentError, "First argument must be a KillSpec: #{kill_spec.inspect}"
       end
       proc do
         cluster.schedule_kill_cursor(kill_spec)
-        session.end_session if session && session.implicit?
       end
     end
 
@@ -253,12 +251,7 @@ module Mongo
     #
     # @since 2.2.0
     def batch_size
-      value = @view.batch_size && @view.batch_size > 0 ? @view.batch_size : limit
-      if value == 0
-        nil
-      else
-        value
-      end
+      @view.batch_size && @view.batch_size > 0 ? @view.batch_size : limit
     end
 
     # Is the cursor closed?
@@ -371,13 +364,14 @@ module Mongo
     end
 
     # @api private
-    def kill_spec(server)
+    def kill_spec(connection_global_id)
       KillSpec.new(
         cursor_id: id,
         coll_name: collection_name,
         db_name: database.name,
-        service_id: initial_result.connection_description.service_id,
+        connection_global_id: connection_global_id,
         server_address: server.address,
+        session: @session,
       )
     end
 
@@ -388,6 +382,14 @@ module Mongo
 
     private
 
+    def batch_size_for_get_more
+      if batch_size && use_limit?
+        [batch_size, @remaining].min
+      else
+        batch_size
+      end
+    end
+
     def exhausted?
       limited? ? @remaining <= 0 : false
     end
@@ -410,7 +412,7 @@ module Mongo
         cursor_id: id,
         # 3.2+ servers use batch_size, 3.0- servers use to_return.
         # TODO should to_return be calculated in the operation layer?
-        batch_size: batch_size,
+        batch_size: batch_size_for_get_more,
         to_return: to_return,
         max_time_ms: if view.respond_to?(:max_await_time_ms) &&
           view.max_await_time_ms &&
@@ -421,6 +423,9 @@ module Mongo
           nil
         end,
       }
+      if view.respond_to?(:options) && view.options.is_a?(Hash)
+        spec[:comment] = view.options[:comment] unless view.options[:comment].nil?
+      end
       Operation::GetMore.new(spec)
     end
 
@@ -473,7 +478,7 @@ module Mongo
       context = Operation::Context.new(
         client: client,
         session: @session,
-        service_id: initial_result.connection_description.service_id,
+        connection_global_id: @connection_global_id,
       )
       op.execute(@server, context: context)
     end

data/lib/mongo/database/view.rb

@@ -53,9 +53,11 @@ module Mongo
       # @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
+      #   to run the command when access control is enforced.
+      # @option options [ Object ] :comment A user-provided
+      #   comment to attach to this command.
       #
-      #   See https://docs.mongodb.com/manual/reference/command/listCollections/
+      #   See https://mongodb.com/docs/manual/reference/command/listCollections/
       #   for more information and usage.
       # @option options [ Session ] :session The session to use.
       #
@@ -99,7 +101,7 @@ module Mongo
       #   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/
+      #   See https://mongodb.com/docs/manual/reference/command/listCollections/
       #   for more information and usage.
       # @option options [ Session ] :session The session to use.
       #
@@ -186,6 +188,7 @@ module Mongo
           spec[:selector][:nameOnly] = true if options[:name_only]
           spec[:selector][:filter] = options[:filter] if options[:filter]
           spec[:selector][:authorizedCollections] = true if options[:authorized_collections]
+          spec[:comment] = options[:comment] if options[:comment]
         end
       end
 

data/lib/mongo/database.rb

@@ -73,7 +73,8 @@ module Mongo
                    :read_preference,
                    :server_selector,
                    :read_concern,
-                   :write_concern
+                   :write_concern,
+                   :encrypted_fields_map
 
     # @return [ Mongo::Server ] Get the primary server from the cluster.
     def_delegators :cluster,
@@ -125,8 +126,10 @@ module Mongo
     # @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
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     #
-    #   See https://docs.mongodb.com/manual/reference/command/listCollections/
+    #   See https://mongodb.com/docs/manual/reference/command/listCollections/
     #   for more information and usage.
     #
     # @return [ Array<String> ] Names of the collections.
@@ -150,9 +153,11 @@ module Mongo
     #   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
+    #   required privilege to run the command when access control is enforced.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     #
-    #   See https://docs.mongodb.com/manual/reference/command/listCollections/
+    #   See https://mongodb.com/docs/manual/reference/command/listCollections/
     #   for more information and usage.
     #
     # @return [ Array<Hash> ] Array of information hashes, one for each
@@ -173,9 +178,11 @@ module Mongo
     # @option options [ Hash ] :filter A filter on the collections returned.
     # @option options [ true, false ] :authorized_collections A flag, when
     #   set to true and used with name_only: true, that allows a user without the
-    #   required privilege to run the command when access control is enforced
+    #   required privilege to run the command when access control is enforced.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     #
-    #   See https://docs.mongodb.com/manual/reference/command/listCollections/
+    #   See https://mongodb.com/docs/manual/reference/command/listCollections/
     #   for more information and usage.
     #
     # @return [ Array<Mongo::Collection> ] The collections.
@@ -218,8 +225,33 @@ module Mongo
 
       client.send(:with_session, opts) do |session|
         server = selector.select_server(cluster, nil, session)
+        # This code MUST be removed as soon as server starts accepting
+        # contention as int32.
+        _operation = operation.dup
+        if _operation['encryptedFields'] && _operation['encryptedFields'].key?('fields')
+          _operation['encryptedFields']['fields'] = _operation['encryptedFields']['fields'].map do |field|
+            if field['queries'] && field['queries'].key?('contention')
+              field['queries']['contention'] = BSON::Int64.new(field['queries']['contention'])
+            end
+            field
+          end
+        end
+        if schema = _operation.dig('encryptionInformation', 'schema')
+          _operation['encryptionInformation']['schema'] = schema.map do |coll, params|
+            if params['fields']
+              params['fields'] = params['fields'].map do |field|
+                if contention = field.dig('queries', 'contention')
+                  field['queries']['contention'] = BSON::Int64.new(contention)
+                end
+                field
+              end
+            end
+            [coll, params]
+          end.to_h
+        end
+        # End of code to be removed
         op = Operation::Command.new(
-          :selector => operation.dup,
+          :selector => _operation,
           :db_name => name,
           :read => selector,
           :session => session
@@ -258,6 +290,7 @@ module Mongo
             db_name: name,
             read: preference,
             session: session,
+            comment: opts[:comment],
           ).execute(server, context: Operation::Context.new(client: client, session: session))
         end
       end
@@ -378,7 +411,8 @@ module Mongo
     # @option options [ true, false ] :bypass_document_validation Whether or
     #   not to skip document level validation.
     # @option options [ Hash ] :collation The collation to use.
-    # @option options [ String ] :comment Associate a comment with the aggregation.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     # @option options [ String ] :hint The index to use for the aggregation.
     # @option options [ Integer ] :max_time_ms The maximum amount of time in
     #   milliseconds to allow the aggregation to run.
@@ -405,10 +439,35 @@ module Mongo
     # @param [ Array<Hash> ] pipeline Optional additional filter operators.
     # @param [ Hash ] options The change stream options.
     #
-    # @option options [ String ] :full_document Allowed values: 'default', 'updateLookup'.
-    #   Defaults to 'default'. When set to 'updateLookup', the change notification for partial
-    #   updates will include both a delta describing the changes to the document, as well as a copy
-    #   of the entire document that was changed from some time after the change occurred.
+    # @option options [ String ] :full_document Allowed values: nil, 'default',
+    #   'updateLookup', 'whenAvailable', 'required'.
+    #
+    #   The default is to not send a value (i.e. nil), which is equivalent to
+    #   'default'. By default, the change notification for partial updates will
+    #   include a delta describing the changes to the document.
+    #
+    #   When set to 'updateLookup', the change notification for partial updates
+    #   will include both a delta describing the changes to the document as well
+    #   as a copy of the entire document that was changed from some time after
+    #   the change occurred.
+    #
+    #   When set to 'whenAvailable', configures the change stream to return the
+    #   post-image of the modified document for replace and update change events
+    #   if the post-image for this event is available.
+    #
+    #   When set to 'required', the same behavior as 'whenAvailable' except that
+    #   an error is raised if the post-image is not available.
+    # @option options [ String ] :full_document_before_change Allowed values: nil,
+    #   'whenAvailable', 'required', 'off'.
+    #
+    #   The default is to not send a value (i.e. nil), which is equivalent to 'off'.
+    #
+    #   When set to 'whenAvailable', configures the change stream to return the
+    #   pre-image of the modified document for replace, update, and delete change
+    #   events if it is available.
+    #
+    #   When set to 'required', the same behavior as 'whenAvailable' except that
+    #   an error is raised if the pre-image is not available.
     # @option options [ BSON::Document, Hash ] :resume_after Specifies the logical starting point
     #   for the new change stream.
     # @option options [ Integer ] :max_await_time_ms The maximum amount of time for the server to
@@ -420,6 +479,8 @@ module Mongo
     #   changes that occurred after the specified timestamp. Any command run
     #   against the server will return a cluster time that can be used here.
     #   Only recognized by server versions 4.0+.
+    # @option options [ Object ] :comment A user-provided
+    #   comment to attach to this command.
     #
     # @note A change stream only allows 'majority' read concern.
     # @note This helper method is preferable to running a raw aggregation with a $changeStream