RUBY-2996 add feature flag for update/replace (#2515)

* RUBY-2996 define feature flag

* unpend tests

* fix spacing

* RUBY-2996 use the feature flag

* RUBY-2996 move config override

* RUBY-2996 asnwer comments

* RUBY-2996 set feature flag

* RUBY-2996 include warning

* RUBY-2996 answer comments

* RUBY-2996 throttle the warning

* RUBY-2996 add user docs

* RUBY-2996 fix test

Author: neilshweky

docs/reference/create-client.txt

@@ -2050,3 +2050,29 @@ driver in production:
   <https://devcenter.heroku.com/articles/request-timeout>`_ is 30 seconds and
   is not configurable; if deploying a Ruby application using MongoDB to Heroku,
   consider lowering server selection timeout to 20 or 15 seconds.
+
+Feature Flags
+=============
+
+The following is a list of feature flags that the Mongo Ruby Driver provides:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 60
+
+   * - Flag
+     - Description
+   * - ``validate_update_replace``
+     - Validates that there are no atomic operators (those that start with $)
+       in the root of a replacement document, and that there are only atomic
+       operators at the root of an update document. If this feature flag is on,
+       an error will be raised on an invalid update or replacement document,
+       if not, a warning will be output to the logs. (default: false)
+
+These feature flags can be set directly on the ``Mongo`` module or using
+the ``options`` method:
+
+.. code::
+
+  Mongo.validate_update_replace = true
+  Mongo.options = { validate_update_replace: true }

lib/mongo.rb

@@ -75,8 +75,28 @@
 require 'mongo/version'
 require 'mongo/write_concern'
 require 'mongo/utils'
+require 'mongo/config'
 
 module Mongo
+
+  class << self
+    extend Forwardable
+
+    # Delegate the given option along with its = and ? methods to the given
+    # object.
+    #
+    # @param [ Object ] obj The object to delegate to.
+    # @param [ Symbol ] opt The method to delegate.
+    def self.delegate_option(obj, opt)
+      def_delegators obj, opt, "#{opt}=", "#{opt}?"
+    end
+
+    # Take all the public instance methods from the Config singleton and allow
+    # them to be accessed through the Mongo module directly.
+    def_delegators Config, :options=
+    delegate_option Config, :validate_update_replace
+  end
+
   # Clears the driver's OCSP response cache.
   module_function def clear_ocsp_cache
     Socket::OcspCache.clear

lib/mongo/bulk_write.rb

@@ -333,14 +333,22 @@ def validate_requests!
             if doc = maybe_first(req.dig(op, :update))
               if key = doc.keys&.first
                 unless key.to_s.start_with?("$")
-                  raise Error::InvalidUpdateDocument.new(key: key)
+                  if Mongo.validate_update_replace
+                    raise Error::InvalidUpdateDocument.new(key: key)
+                  else
+                    Error::InvalidUpdateDocument.warn(Logger.logger, key)
+                  end
                 end
               end
             end
           elsif op == :replace_one
             if key = req.dig(op, :replacement)&.keys&.first
               if key.to_s.start_with?("$")
-                raise Error::InvalidReplacementDocument.new(key: key)
+                if Mongo.validate_update_replace
+                  raise Error::InvalidReplacementDocument.new(key: key)
+                else
+                  Error::InvalidReplacementDocument.warn(Logger.logger, key)
+                end
               end
             end
           end

lib/mongo/collection/view/writable.rb

@@ -556,7 +556,11 @@ def validate_update_documents!(spec)
           if update = spec.is_a?(Array) ? spec&.first : spec
             if key = update.keys&.first
               unless key.to_s.start_with?("$")
-                raise Error::InvalidUpdateDocument.new(key: key)
+                if Mongo.validate_update_replace
+                  raise Error::InvalidUpdateDocument.new(key: key)
+                else
+                  Error::InvalidUpdateDocument.warn(Logger.logger, key)
+                end
               end
             end
           end
@@ -574,7 +578,11 @@ def validate_replacement_documents!(spec)
           if replace = spec.is_a?(Array) ? spec&.first : spec
             if key = replace.keys&.first
               if key.to_s.start_with?("$")
-                raise Error::InvalidReplacementDocument.new(key: key)
+                if Mongo.validate_update_replace
+                  raise Error::InvalidReplacementDocument.new(key: key)
+                else
+                  Error::InvalidReplacementDocument.warn(Logger.logger, key)
+                end
               end
             end
           end

lib/mongo/config.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "mongo/config/options"
+require "mongo/config/validators/option"
+
+module Mongo
+
+  # This module defines configuration options for Mongo.
+  #
+  # @api private
+  module Config
+    extend Forwardable
+    extend Options
+    extend self
+
+    option :validate_update_replace, default: false
+
+    # Set the configuration options.
+    #
+    # @example Set the options.
+    #   config.options = { validate_update_replace: true }
+    #
+    # @param [ Hash ] options The configuration options.
+    def options=(options)
+      options.each_pair do |option, value|
+        Validators::Option.validate(option)
+        send("#{option}=", value)
+      end
+    end
+  end
+end

lib/mongo/config/options.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Mongo
+  module Config
+
+    # Encapsulates logic for setting options.
+    module Options
+
+      # Get the defaults or initialize a new empty hash.
+      #
+      # @return [ Hash ] The default options.
+      def defaults
+        @defaults ||= {}
+      end
+
+      # Define a configuration option with a default.
+      #
+      # @param [ Symbol ] name The name of the configuration option.
+      # @param [ Hash ] options Extras for the option.
+      #
+      # @option options [ Object ] :default The default value.
+      def option(name, options = {})
+        defaults[name] = settings[name] = options[:default]
+
+        class_eval do
+          # log_level accessor is defined specially below
+          define_method(name) do
+            settings[name]
+          end
+
+          define_method("#{name}=") do |value|
+            settings[name] = value
+          end
+
+          define_method("#{name}?") do
+            !!send(name)
+          end
+        end
+      end
+
+      # Reset the configuration options to the defaults.
+      #
+      # @example Reset the configuration options.
+      #   config.reset
+      #
+      # @return [ Hash ] The defaults.
+      def reset
+        settings.replace(defaults)
+      end
+
+      # Get the settings or initialize a new empty hash.
+      #
+      # @example Get the settings.
+      #   options.settings
+      #
+      # @return [ Hash ] The setting options.
+      def settings
+        @settings ||= {}
+      end
+    end
+  end
+end

lib/mongo/config/validators/option.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mongo
+  module Config
+    module Validators
+
+      # Validator for configuration options.
+      #
+      # @api private
+      module Option
+        extend self
+
+        # Validate a configuration option.
+        #
+        # @example Validate a configuration option.
+        #
+        # @param [ String ] option The name of the option.
+        def validate(option)
+          unless Config.settings.keys.include?(option.to_sym)
+            raise Mongo::Error::InvalidConfigOption.new(option)
+          end
+        end
+      end
+    end
+  end
+end

lib/mongo/error.rb

@@ -151,6 +151,7 @@ def write_concern_error_labels
 require 'mongo/error/invalid_bulk_operation'
 require 'mongo/error/invalid_bulk_operation_type'
 require 'mongo/error/invalid_collection_name'
+require 'mongo/error/invalid_config_option'
 require 'mongo/error/invalid_cursor_operation'
 require 'mongo/error/invalid_database_name'
 require 'mongo/error/invalid_document'

lib/mongo/error/invalid_config_option.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Mongo
+  class Error
+
+    # This error is raised when a bad configuration option is attempted to be
+    # set.
+    class InvalidConfigOption < Error
+
+      # Create the new error.
+      #
+      # @param [ Symbol, String ] name The attempted config option name.
+      #
+      # @api private
+      def initialize(name)
+        super("Invalid config option #{name}.")
+      end
+    end
+  end
+end

lib/mongo/error/invalid_replacement_document.rb

@@ -26,13 +26,34 @@ class InvalidReplacementDocument < Error
       # @deprecated
       MESSAGE = 'Invalid replacement document provided'.freeze
 
+      # Construct the error message.
+      #
+      # @param [ String ] key The invalid key.
+      #
+      # @return [ String ] The error message.
+      #
+      # @api private
+      def self.message(key)
+        message = "Invalid replacement document provided. Replacement documents "
+        message += "must not contain atomic modifiers. The \"#{key}\" key is invalid."
+        message
+      end
+
+      # Send and cache the warning.
+      #
+      # @api private
+      def self.warn(logger, key)
+        @warned ||= begin
+          logger.warn(message(key))
+          true
+        end
+      end
+
       # Instantiate the new exception.
       #
       # @param [ String ] :key The invalid key.
       def initialize(key: nil)
-        message = "Invalid replacement document provided. Replacement documents "
-        message += "must not contain atomic modifiers. The \"#{key}\" key is invalid."
-        super(message)
+        super(self.class.message(key))
       end
     end
   end