mongoid 9.1.0 → 9.1.2

data/lib/mongoid/extensions/vector.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Extensions
+    # Adds type-casting behavior to BSON::Vector class so that a field
+    # declared with +type: BSON::Vector+ is stored as a BSON binary of the
+    # vector subtype and read back as a BSON::Vector.
+    #
+    # Querying by an exact vector value (e.g. +where(embedding: vector)+) is
+    # not supported: BSON::Vector subclasses Array, so the criteria selector
+    # treats it as a list of elements rather than a scalar. Use Atlas Vector
+    # Search ($vectorSearch) for similarity queries on vector fields.
+    module Vector
+      # Turn the object from the ruby type we deal with to a Mongo friendly
+      # type.
+      #
+      # @example Mongoize the object.
+      #   object.mongoize
+      #
+      # @return [ BSON::Binary | nil ] The object as a vector binary.
+      def mongoize
+        BSON::Vector.mongoize(self)
+      end
+
+      module ClassMethods
+        # Mongoize an object of any type to how it's stored in the db.
+        #
+        # @example Mongoize the object.
+        #   BSON::Vector.mongoize(vector)
+        #
+        # @param [ Object ] object The object to Mongoize.
+        #
+        # @return [ BSON::Binary | nil ] A vector binary or nil.
+        def mongoize(object)
+          case object
+          when BSON::Vector then BSON::Binary.from_vector(object)
+          when BSON::Binary then object
+          end
+        end
+
+        # Convert the object from its mongo friendly ruby type back to a
+        # BSON::Vector.
+        #
+        # @example Demongoize the object.
+        #   BSON::Vector.demongoize(binary)
+        #
+        # @param [ Object ] object The object to demongoize.
+        #
+        # @return [ BSON::Vector | nil ] The vector or nil.
+        def demongoize(object)
+          case object
+          when BSON::Binary then (object.type == :vector) ? object.as_vector : nil
+          when BSON::Vector then object
+          end
+        end
+      end
+    end
+  end
+end
+
+if defined?(BSON::Vector)
+  BSON::Vector.include Mongoid::Extensions::Vector
+  BSON::Vector.extend(Mongoid::Extensions::Vector::ClassMethods)
+end

data/lib/mongoid/extensions.rb

@@ -26,3 +26,4 @@ require 'mongoid/extensions/symbol'
 require 'mongoid/extensions/time'
 require 'mongoid/extensions/time_with_zone'
 require 'mongoid/extensions/true_class'
+require 'mongoid/extensions/vector'

data/lib/mongoid/field_readable.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Mongoid
+  # Reads the value of a field name from a document without dispatching the
+  # name as an arbitrary method.
+  #
+  # Field names may come from application input, where a name like +destroy+
+  # or +attributes+ would delete the document or disclose its contents.
+  # Declared field and association names are validated when they are declared
+  # (see Mongoid.destructive_fields), so a name that resolves to one of them
+  # is safe to send to a document. Any other name is read from the attributes
+  # hash, which is what the database-backed query contexts do.
+  #
+  # @api private
+  module FieldReadable
+    private
+
+    # Read the value of the given field name from the given document.
+    #
+    # @param [ Document ] document The document to read from.
+    # @param [ String | Symbol ] name The name of the field.
+    #
+    # @return [ Object | nil ] The value of the field, or nil when the name
+    #   is neither a declared field nor present in the attributes.
+    def read_field_value(document, name)
+      name = name.to_s
+      # A blank name cannot name a field. Return nil, which is what reading
+      # one has always done.
+      return nil if name.blank?
+
+      if (meth = readable_method_for(document.class, name))
+        document.public_send(meth)
+      else
+        document.attributes[document.class.database_field_name(name)]
+      end
+    end
+
+    # Resolve the given name to a method that is declared by the given class,
+    # and therefore safe to send to one of its instances.
+    #
+    # @param [ Class ] klass The document class.
+    # @param [ String ] name The name of the field.
+    #
+    # @return [ String | nil ] The method to send, or nil when the name is
+    #   not declared by the class.
+    def readable_method_for(klass, name)
+      # Fields, associations, and field aliases each define a reader of their
+      # own name. Note that associations must be resolved before aliases: a
+      # belongs_to aliases its own name to its foreign key, and reading
+      # `band` must give the document, not the id.
+      return name if klass.relations.key?(name) ||
+                     klass.fields.key?(name) ||
+                     klass.aliased_fields.key?(name)
+
+      # An association may also be named by its `store_as`, which has no
+      # reader of its own, or by its ids accessor, which does.
+      if (assoc = klass.relations[klass.aliased_associations[name]])
+        return (assoc.store_as == name) ? assoc.name.to_s : name
+      end
+
+      # Localized fields also get a _translations reader, which does not
+      # appear in the fields hash.
+      base = name.delete_suffix(Fields::TRANSLATIONS_SFX)
+      return nil if base == name
+
+      name if klass.fields[klass.database_field_name(base)]&.localized?
+    end
+  end
+end

data/lib/mongoid/fields.rb

@@ -412,6 +412,13 @@ module Mongoid
         return '' unless name.present?
 
         key = name.to_s
+
+        # A key without a "." refers to an immediate field, so it resolves to
+        # its alias (or itself) with no splitting. Short-circuiting here avoids
+        # the split and dup on every read, which is a hot path. This mirrors the
+        # same optimization already applied to the matcher.
+        return aliased_fields[key]&.dup || key unless key.include?('.')
+
         segment, remaining = key.split('.', 2)
 
         # Don't get the alias for the field when a belongs_to association

data/lib/mongoid/indexable.rb

@@ -24,18 +24,9 @@ module Mongoid
       def create_indexes
         return unless index_specifications
 
-        default_options = { background: Config.background_indexing }
-
-        index_specifications.each do |spec|
-          key, options = spec.key, default_options.merge(spec.options)
-          if database = options[:database]
-            with(database: database) do |klass|
-              klass.collection.indexes(session: _session).create_one(key, options.except(:database))
-            end
-          else
-            collection.indexes(session: _session).create_one(key, options)
-          end
-        end and true
+        Threaded.with_collection_management do
+          perform_create_indexes
+        end
       end
 
       # Send the actual index removal comments to the MongoDB driver,
@@ -46,20 +37,9 @@ module Mongoid
       #
       # @return [ true ] If the operation succeeded.
       def remove_indexes
-        indexed_database_names.each do |database|
-          with(database: database) do |klass|
-            klass.collection.indexes(session: _session).each do |spec|
-              next if spec['name'] == '_id_'
-
-              klass.collection.indexes(session: _session).drop_one(spec['key'])
-              logger.info(
-                "MONGOID: Removed index '#{spec['name']}' on collection " +
-                "'#{klass.collection.name}' in database '#{database}'."
-              )
-            end
-          rescue Mongo::Error::OperationFailure
-          end
-        end and true
+        Threaded.with_collection_management do
+          perform_remove_indexes
+        end
       end
 
       # Add the default indexes to the root document if they do not already
@@ -119,6 +99,38 @@ module Mongoid
 
       private
 
+      def perform_create_indexes
+        default_options = { background: Config.background_indexing }
+
+        index_specifications.each do |spec|
+          key, options = spec.key, default_options.merge(spec.options)
+          if database = options[:database]
+            with(database: database) do |klass|
+              klass.collection.indexes(session: _session).create_one(key, options.except(:database))
+            end
+          else
+            collection.indexes(session: _session).create_one(key, options)
+          end
+        end and true
+      end
+
+      def perform_remove_indexes
+        indexed_database_names.each do |database|
+          with(database: database) do |klass|
+            klass.collection.indexes(session: _session).each do |spec|
+              next if spec['name'] == '_id_'
+
+              klass.collection.indexes(session: _session).drop_one(spec['key'])
+              logger.info(
+                "MONGOID: Removed index '#{spec['name']}' on collection " +
+                "'#{klass.collection.name}' in database '#{database}'."
+              )
+            end
+          rescue Mongo::Error::OperationFailure
+          end
+        end and true
+      end
+
       # Get the names of all databases for this model that have index
       # definitions.
       #

data/lib/mongoid/matchable.rb

@@ -16,7 +16,12 @@ module Mongoid
     #
     # @return [ true | false ] True if matches, false if not.
     def _matches?(selector)
-      Matcher::Expression.matches?(self, selector)
+      # Opens a regexp budget for this document only. Callers that match many
+      # documents against one selector open a budget of their own first, and
+      # this one joins it rather than giving every document a fresh limit.
+      Matcher::RegexpBudget.open(selector) do
+        Matcher::Expression.matches?(self, selector)
+      end
     end
   end
 end

data/lib/mongoid/matcher/eq_impl_with_regexp.rb

@@ -18,10 +18,8 @@ module Mongoid
       # @api private
       module_function def matches?(_original_operator, value, condition)
         case condition
-        when Regexp
-          value.respond_to?(:=~) && value =~ condition
-        when ::BSON::Regexp::Raw
-          value.respond_to?(:=~) && value =~ condition.compile
+        when Regexp, ::BSON::Regexp::Raw
+          value.respond_to?(:=~) && RegexpBudget.match?(value, condition)
         else
           if value.is_a?(Time) && condition.is_a?(Time)
             EqImpl.time_eq?(value, condition)

data/lib/mongoid/matcher/regex.rb

@@ -16,24 +16,23 @@ module Mongoid
       #
       # @api private
       module_function def matches?(_exists, value, condition)
-        condition = case condition
-                    when Regexp
-                      condition
-                    when BSON::Regexp::Raw
-                      condition.compile
-                    else
-                      # Note that strings must have been converted to a regular expression
-                      # instance already (with $options taken into account, if provided).
-                      raise Errors::InvalidQuery, "$regex requires a regular expression argument: #{Errors::InvalidQuery.truncate_expr(condition)}"
-                    end
+        unless condition.is_a?(Regexp) || condition.is_a?(BSON::Regexp::Raw)
+          # Note that strings must have been converted to a regular expression
+          # instance already (with $options taken into account, if provided).
+          raise Errors::InvalidQuery, "$regex requires a regular expression argument: #{Errors::InvalidQuery.truncate_expr(condition)}"
+        end
 
+        # The condition is compiled by RegexpBudget rather than here, so that
+        # the budget's timeout can be baked into the pattern.
         case value
         when Array
+          # Object#=~ is gone as of Ruby 3.2, so an element that cannot be
+          # matched against has to be rejected rather than passed to =~.
           value.any? do |v|
-            v =~ condition
+            v.respond_to?(:=~) && RegexpBudget.match?(v, condition)
           end
         when String
-          value =~ condition
+          RegexpBudget.match?(value, condition)
         else
           false
         end

data/lib/mongoid/matcher/regexp_budget.rb

@@ -0,0 +1,372 @@
+# frozen_string_literal: true
+
+require 'timeout'
+
+module Mongoid
+  module Matcher
+    # Bounds the time spent executing regular expressions while evaluating a
+    # single in-memory match operation.
+    #
+    # A query condition can carry an application-supplied pattern, and the
+    # in-memory matcher compiles and runs that pattern in the caller's thread.
+    # Both the cost of one match and the number of matches performed are under
+    # the control of whoever supplied the condition, so the limit is cumulative
+    # over an entire operation rather than per match.
+    #
+    # The budget is held in thread- or fiber-local storage, so concurrent
+    # queries are accounted for independently.
+    #
+    # @api private
+    module RegexpBudget
+      # Whether a per-Regexp timeout can be relied on to reach Regexp.new.
+      #
+      # MRI added them in 3.2. JRuby 10.0.6 defines Regexp::TimeoutError,
+      # reports Ruby 3.4, and does honour a timeout that reaches it, but its
+      # Regexp.new accepts the keyword only for the first couple of calls
+      # through a given call site and raises ArgumentError from then on.
+      # Because that breakage is per call site, no load-time probe can predict
+      # it: a probe at its own call site reports a capability that the call in
+      # Budget#compile does not have. So non-MRI engines are excluded outright
+      # and use the Timeout fallback, which does interrupt a Joni match already
+      # under way. Worth revisiting if JRuby fixes the keyword handling.
+      PER_REGEXP_TIMEOUT =
+        if RUBY_ENGINE == 'ruby' && defined?(::Regexp::TimeoutError)
+          true
+        else
+          false
+        end
+
+      # The exception raised by a per-Regexp timeout. Tied to the constant
+      # rather than to the probe, so that a timeout set some other way (an
+      # application assigning Regexp.timeout, say) is still translated. On
+      # Rubies with no such constant, a class that is never raised stands in.
+      TIMEOUT_ERROR = defined?(::Regexp::TimeoutError) ? ::Regexp::TimeoutError : Class.new(StandardError)
+
+      # Raised by Timeout on Rubies without per-Regexp timeouts, and converted
+      # immediately. It is private to this module so that an application's own
+      # Timeout, firing inside our block, is never mistaken for ours.
+      class TimedOut < StandardError; end
+
+      # The state of one open budget: what is left of the limit, and the
+      # patterns compiled under it.
+      #
+      # @api private
+      class Budget
+        # @return [ Float ] The limit this budget started with.
+        attr_reader :limit
+
+        # @return [ Float ] The seconds left before the budget is spent.
+        attr_reader :remaining
+
+        # @param [ Float ] limit The seconds this budget may spend.
+        def initialize(limit)
+          @limit = limit
+          @remaining = limit
+          @cache = {}
+          # A per-Regexp timeout bounds one match; the cumulative budget bounds
+          # the operation. So the timeout is fixed for the life of the scope
+          # rather than following the drawdown, which is what lets a pattern be
+          # compiled once instead of once per match. It means a match that
+          # starts with almost nothing left can still run for a whole limit, so
+          # an operation can overshoot by at most one limit -- bounded, which is
+          # the point, and far cheaper than recompiling.
+          #
+          # An application that has set a stricter global Regexp.timeout keeps
+          # it: baking in a larger value would leave it less protected than it
+          # asked to be. A timeout set on one individual pattern is a different
+          # matter, and is not preserved -- Budget#compile rebuilds the pattern
+          # from its source and flags, neither of which carries one, so this
+          # value takes its place. Only trusted code can supply such a pattern:
+          # a condition decoded from JSON or BSON arrives as a string or a
+          # BSON::Regexp::Raw, with no timeout of its own.
+          @timeout = [ limit, ::Regexp.timeout ].compact.min if PER_REGEXP_TIMEOUT
+        end
+
+        # Draws the elapsed time down from the budget.
+        #
+        # @param [ Float ] elapsed The seconds to charge.
+        def charge(elapsed)
+          @remaining -= elapsed
+        end
+
+        # @return [ true | false ] Whether the budget is spent.
+        def exhausted?
+          @remaining <= 0
+        end
+
+        # Returns the condition as a Regexp which, where the Ruby in use
+        # supports it, gives up once its timeout is spent.
+        #
+        # The condition is taken uncompiled so that the cache can answer before
+        # any compiling happens. A BSON::Regexp::Raw memoizes its own compile,
+        # but FieldExpression builds a fresh one for every $regex it evaluates,
+        # so that memo is worth nothing across documents and the source would
+        # otherwise be compiled once per document.
+        #
+        # @param [ Regexp | BSON::Regexp::Raw ] condition The condition.
+        #
+        # @return [ Regexp ] The compiled pattern.
+        def compile(condition)
+          @cache[cache_key(condition)] ||= bake(RegexpBudget.coerce(condition))
+        end
+
+        private
+
+        # BSON::Regexp::Raw aliases eql? to == but leaves hash alone, so two
+        # equal instances hash differently and cannot key the cache. What they
+        # are equal by can. Anything else keys on itself and is left to coerce
+        # to reject.
+        def cache_key(condition)
+          case condition
+          when BSON::Regexp::Raw then [ condition.pattern, condition.options ]
+          else condition
+          end
+        end
+
+        # Rebuilds the pattern with the budget's timeout, where the Ruby in use
+        # has them.
+        def bake(regexp)
+          return regexp unless PER_REGEXP_TIMEOUT
+
+          ::Regexp.new(regexp.source, regexp.options, timeout: @timeout)
+        end
+      end
+
+      class << self
+        # Opens a budget scope for the duration of the block.
+        #
+        # Nested calls join the enclosing budget instead of starting a new one,
+        # which is what lets a scan over many documents share a single limit.
+        # It also keeps the recursion in Expression.matches? (through
+        # $elemMatch, $and, $or and $nor) from resetting the budget.
+        #
+        # No budget is opened for a selector that carries no regular
+        # expression. There would be nothing for it to bound, and on the
+        # Timeout path it would put a deadline on in-memory work that has
+        # nothing to do with regular expressions.
+        #
+        # The scope covers everything nested inside the block, a selector other
+        # than this one included: a nested call joins the scope rather than
+        # deciding for itself, which is what keeps a scan from walking the
+        # selector once per document. Where the scope has nothing to bound, that
+        # means nested selectors are not bounded either -- so do not open one
+        # around work that can run application code. Loading documents runs find
+        # callbacks, and a query in one of those brings its own selector.
+        #
+        # Where a selector does carry one, the Timeout path still measures the
+        # whole scope rather than the matching alone, so a long scan can trip
+        # the limit with a cheap pattern. That imprecision is accepted: the
+        # alternative is a Timeout around each individual match, which was
+        # measured at about nine seconds per million matches, and the limit
+        # exists to bound a scan of exactly that size. The error message is
+        # worded to hold either way, and Rubies with per-Regexp timeouts --
+        # every supported MRI from 3.2 on -- do not take this path at all.
+        #
+        # Code inside the block that mutates state should be wrapped in
+        # .protect, since on Rubies without a per-Regexp timeout the budget is
+        # enforced with an asynchronous exception that can land anywhere.
+        #
+        # @param [ Hash ] selector The selector about to be evaluated.
+        #
+        # @return [ Object ] The value of the block.
+        def open(selector, &block)
+          # The key is present but nil where an enclosing scope found nothing
+          # to bound, so that a nested call does not scan the selector again.
+          # Deciding before this check, in a default argument say, would walk
+          # the selector once per document on a scan.
+          return yield if Threaded.has?(Threaded::REGEXP_BUDGET_KEY)
+
+          open_with(limit_for(selector), &block)
+        end
+
+        # Opens a budget scope for a limit the caller has already decided on.
+        #
+        # A caller that rearranges its work around the decision -- loading
+        # documents up front so that nothing is mutated before the scan
+        # finishes, say -- has to make it before it can act on it, and must not
+        # then make it a second time. Asking .limit_for and letting .open ask
+        # again reads the configured limit twice, and the two reads can differ:
+        # a limit that becomes positive in between would establish a budget in
+        # the branch that was chosen for not needing one, and on the Timeout
+        # path that arms a deadline over work the branch never made
+        # interruptible.
+        #
+        # See .open for what the scope does and does not bound, and for the
+        # note about mutating state inside it.
+        #
+        # @param [ Float | nil ] limit The seconds the scope may spend, or nil
+        #   for a scope with nothing to bound.
+        #
+        # @return [ Object ] The value of the block.
+        def open_with(limit, &block)
+          return yield if Threaded.has?(Threaded::REGEXP_BUDGET_KEY)
+
+          budget = Budget.new(limit) if limit&.positive?
+
+          begin
+            # Set inside the begin so that an asynchronous exception from an
+            # enclosing timeout cannot leave the key behind on a pooled thread.
+            Threaded.set(Threaded::REGEXP_BUDGET_KEY, budget)
+
+            if budget.nil? || PER_REGEXP_TIMEOUT
+              yield
+            else
+              begin
+                Timeout.timeout(budget.limit, TimedOut, &block)
+              rescue TimedOut
+                raise timeout_error(budget)
+              end
+            end
+          ensure
+            Threaded.delete(Threaded::REGEXP_BUDGET_KEY)
+          end
+        end
+
+        # The limit a scope evaluating this selector would be bounded by.
+        #
+        # A caller that has to rearrange its work to make the scan
+        # interruptible -- loading documents up front so that nothing is
+        # mutated before the scan finishes, say -- can ask this first and skip
+        # the rearrangement, and whatever it costs, when there is no pattern to
+        # bound. It then passes what it got to .open_with, so that the decision
+        # it acted on is the one the scope is opened with. Callers with nothing
+        # to rearrange should just call .open, which asks this itself.
+        #
+        # @param [ Hash ] selector The selector about to be evaluated.
+        #
+        # @return [ Float | nil ] The limit, or nil where there is nothing to
+        #   bound.
+        def limit_for(selector)
+          # nil.to_f is 0.0, so an unset limit and a limit of zero or less are
+          # the same thing here: no limit. Zero is a common way to spell
+          # "disabled", and taking it literally would mean a budget that is
+          # spent before the first match and a query that can never run.
+          limit = Mongoid::Config.in_memory_regexp_time_limit.to_f
+          return nil unless limit.positive?
+
+          limit if contains_regexp?(selector)
+        end
+
+        # Matches a value against a regular expression condition, charging the
+        # time it takes against the open budget.
+        #
+        # @param [ Object ] value The value to match.
+        # @param [ Regexp | BSON::Regexp::Raw ] condition The condition.
+        #
+        # @raise [ Errors::InMemoryRegexpTimeout ] if the budget is exhausted.
+        #
+        # @return [ Integer | nil ] The offset of the match, or nil.
+        def match?(value, condition)
+          budget = current
+          return value =~ coerce(condition) unless budget
+
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          pattern = nil
+          begin
+            raise timeout_error(budget) if budget.exhausted?
+
+            # Compiling is charged too. It is not free, and for a pattern with
+            # very many branches it costs far more than running the pattern
+            # does, so leaving it out would leave a way to spend unbounded time
+            # without the budget ever noticing.
+            pattern = budget.compile(condition)
+            value =~ pattern
+          rescue TIMEOUT_ERROR
+            # Name the limit that actually fired, which is not always the
+            # budget's. A baked pattern carries it: the smaller of the budget's
+            # limit and any global Regexp.timeout the application has set.
+            # Where nothing was baked -- an engine that raises this error but
+            # will not take a per-Regexp timeout, which is JRuby -- the global
+            # is the only thing that can have fired, and the pattern reports
+            # nil. Naming the budget's limit in either case would state a time
+            # that was never spent and send the reader after a setting that is
+            # not the one in the way.
+            #
+            # Both readers arrived together with Regexp::TimeoutError, so every
+            # engine that can reach this rescue at all has them.
+            raise timeout_error(budget, pattern&.timeout || ::Regexp.timeout || budget.limit)
+          ensure
+            budget.charge(Process.clock_gettime(Process::CLOCK_MONOTONIC) - started)
+          end
+        end
+
+        # Runs the block without letting a scope timeout tear it in half.
+        #
+        # Where the budget is enforced with Timeout, the exception is raised
+        # asynchronously and can arrive at any point. Wrapping a mutation in
+        # this holds the exception back until the block has finished, so the
+        # interruption is deferred rather than given up.
+        #
+        # @return [ Object ] The value of the block.
+        def protect(&block)
+          Thread.handle_interrupt(TimedOut => :never, &block)
+        end
+
+        # The time left in the open budget, or nil when no budget is open.
+        #
+        # @return [ Float | nil ] The remaining seconds.
+        def remaining
+          current&.remaining
+        end
+
+        # Returns the condition as a Regexp, without a timeout.
+        #
+        # @param [ Regexp | BSON::Regexp::Raw ] condition The condition.
+        #
+        # @return [ Regexp ] The pattern.
+        def coerce(condition)
+          case condition
+          when ::Regexp then condition
+          when BSON::Regexp::Raw then condition.compile
+          else raise ArgumentError, "Not a regular expression: #{condition.inspect}"
+          end
+        end
+
+        private
+
+        # The budget for the open scope, if there is one.
+        #
+        # @return [ Budget | nil ] The open budget.
+        def current
+          Threaded.get(Threaded::REGEXP_BUDGET_KEY)
+        end
+
+        # Whether evaluating the selector could run a regular expression.
+        #
+        # A string under $regex counts: FieldExpression turns it into a pattern
+        # at match time.
+        def contains_regexp?(object)
+          case object
+          when ::Regexp, BSON::Regexp::Raw
+            true
+          when Hash
+            object.any? do |k, v|
+              k.to_s == '$regex' || contains_regexp?(v)
+            end
+          when Array
+            object.any? { |v| contains_regexp?(v) }
+          else
+            false
+          end
+        end
+
+        # Builds the error with the scope timeout held back.
+        #
+        # Composing the message goes through I18n, which reads locale files the
+        # first time it runs. An asynchronous TimedOut landing in the middle of
+        # that is caught by I18n and reraised as a locale-loading failure, so
+        # the real error never surfaces.
+        #
+        # @param [ Budget ] budget The open budget.
+        # @param [ Float ] limit The limit that was exceeded. Defaults to the
+        #   budget's own, which is the right one to name everywhere the budget
+        #   itself ran out.
+        def timeout_error(budget, limit = budget.limit)
+          protect do
+            Errors::InMemoryRegexpTimeout.new(limit)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/matcher.rb

@@ -134,6 +134,7 @@ require 'mongoid/matcher/nor'
 require 'mongoid/matcher/not'
 require 'mongoid/matcher/or'
 require 'mongoid/matcher/regex'
+require 'mongoid/matcher/regexp_budget'
 require 'mongoid/matcher/size'
 require 'mongoid/matcher/type'
 require 'mongoid/matcher/expression_operator'